| # Copyright (c) 2014 The Chromium OS Authors. All rights reserved. |
| # Use of this source code is governed by a BSD-style license that can be |
| # found in the LICENSE file. |
| |
| Disk Layout Format: |
| |
| The board layout scripts/build_library/legacy_disk_layout.json is used unless |
| there is a board specific layout. |
| |
| To create a board specific layout that modifies this: |
| Create: |
| overlay-<board>/scripts/disk_layout.json |
| list disk_layout_v<N>.json as a parent in disk_layout.json for |
| modern images, or legacy_disk_layout.json for old boards. |
| |
| A layout file consists of layouts. Common types of layouts would be "base", |
| "usb", "vm" and "common". Each of these layouts is made up of one or more |
| partitions. |
| |
| The "common" layout is special, since it's the layout on which all other layouts |
| get overlaid upon. The base layout represents the "installed" layout, the way |
| things should be once the image has been installed onto a device. The "usb" |
| layout represents how things should look on a USB image (typically, this means |
| that ROOT-B is 1 block long). |
| |
| |
| Here is an example disk layout with comments. |
| |
| # Comments are NOT legal in json, but you can include line comments if |
| # the line starts with a #. Note that in-line comments are not supported, |
| # the # char must to be the first non-blank char of the line. |
| { |
| "_comment": "Old style _comment entries will be ignored as well.", |
| |
| # Space seperated list of files to inherit from. |
| "parent": "legacy_disk_layout.json", |
| |
| # Required. Define drive and filesystem block sizes. |
| # Inherited. |
| "metadata":{ |
| "block_size": 512, |
| "fs_block_size": 4096, |
| # Where (in LBA) to place the primary partition entry array. |
| # If not specified, the value is 2. |
| "primary_entry_array_lba": 2, |
| # The rootdev sysfs path to install the base image. Wildcards are allowed. |
| # The scripts will translate that path into a block device name. |
| # If not specified in your overlay file, a recovery image can not be used |
| # for that platform. |
| "rootdev_base": "/sys/devices/pci0000:00/0000:00:1f.2/ata1/host*/target*/*/block/sd*", |
| |
| }, |
| |
| # All disk layouts for this file. |
| "layouts":{ |
| |
| # All other layouts inherit from 'common'. |
| "common": [ |
| # Every layout is a list of partitions. They will appear on disk in |
| # the order they appear here. |
| { |
| "num": 11, |
| "label":"RWFW", |
| "type":"firmware", |
| "size":"8 MiB" |
| }, |
| { |
| # Number to use in partition device name. ie: /dev/sda1. Not tied to |
| # order of partitions on disk. This is the id used for inheritance. |
| "num": 1, |
| |
| # Partition name. |
| "label":"STATE", |
| |
| # GPT partition type uuid. Values map to cgpt binary command line |
| # arguments, which contain ChromiumOS specific extentions. |
| "type":"data", |
| |
| # Size of partition in disk blocks (block_size * blocks == bytes). |
| # Only blocks or size can be used here, error will occur if both are |
| # used. |
| "blocks":"2097152", |
| |
| # Size of partition in size (block_size * blocks / 1024 / 1024 == MiB). |
| # Only blocks or size can be used here, error will occur if both are |
| # used. |
| "size":"1024 MiB", |
| |
| # What file system will this partition be formatted with. |
| "fs_format":"ext4", |
| |
| # Optional, extra filesystem specific options passed to the program that |
| # creates the filesystem. For example, you can pass compression options |
| # to a compressed filesystem. This accepts a dictionary where the key is |
| # any of the valid fs_format values or a string, which will be used |
| # regardless of the fs_format value. |
| "fs_options":{ |
| # Create an inode every 64 KiB of data on ext2 filesystems. |
| "ext2":"-i 65536", |
| # Compress squashfs with lzo. |
| "squashfs":"-comp lzo" |
| }, |
| |
| # Optional, default is size of partition. Meaningless without |
| # fs_format. Must be less than size of partition. |
| # Size of filesystem in fs size |
| # (block_size * fs_blocks / 1024 / 1024 == MiB). |
| "fs_size": "2048 MiB", |
| |
| # Special handling of this partition. |
| "features":["expand"], |
| |
| # Optional, default 'random'. Explicitly define the partition uuid. |
| # 'random' means generate a new one. |
| "uuid": "random", |
| |
| # Optional, default is "" indicating a normal block device. |
| # With the value "ubi", it indicates that UBI should be formatted |
| # on this partition, which can support ubifs in read-write mode |
| # or any other filesystem read-only. |
| "format": "ubi", |
| |
| # Optional, for NAND devices, indicate the number of erase blocks |
| # reserved for bad blocks. This needs to be separate from the size |
| # and the fs_size because this is on top of all the space that is |
| # reserved for verity's signatures and headers. |
| "reserved_erase_blocks": 25 |
| } |
| # metadata type sections in a layout allow the inclusion of extra |
| # key/value information which pertain to a particular layout. |
| { |
| "num": "metadata", |
| |
| # Optional. Defaults to false. |
| "hybrid_mbr": true, |
| } |
| |
| ], |
| # common is usually good enough for "base", the partition installed on the |
| # fixed device. |
| "base": [ |
| { |
| "num": "metadata", |
| # Some features are mostly useful on NAND flash devices. |
| # In principle these may be useful on other types of devices (e.g., NOR |
| # flash) though those parameters would be specified differently, for |
| # example because erase block size is nonuniform and there are no bad |
| # blocks. |
| # Size of an erase block (needed for partition alignment and making |
| # the partitions in the GPT bigger for reserved blocks). |
| "erase_block_size": "128 KiB", |
| # Size of a page, i.e., write granularity (needed for sizing UBI |
| # metadata). |
| "page_size": "4 KiB", |
| # Maximum bad blocks on the device (for verifying reserved_erase_blocks). |
| # The value will be found in NAND device datasheets. |
| "max_bad_erase_blocks": 80, |
| # Size of the base target device. This feature is mutually exclusive with |
| # the 'expand' feature for partitions, and it is used to calculate what |
| # is a reasonable value for bad block reservation. |
| "size": "1 GiB", |
| # Set to true if the GPT is held on external memory (e.g., for NAND) |
| "external_gpt": true, |
| } |
| ], |
| "usb": [ |
| # This extends base. Partitions can not be removed or added. |
| # Normaly only used to modify partition or fs sizes. |
| { |
| # This number correlates to same partition in base. |
| "num": 11, |
| |
| # This label overrides the label on the base partition. |
| "label":"RWFW", |
| |
| # Type overrides to firmware. |
| "type":"firmware", |
| |
| # This partition is resized to be 4 MiB large (from 1024 MiB). |
| "size":"4 MiB" |
| } |
| ] |
| } |
| } |
| |
| Legal partition types: |
| data |
| efi |
| blank |
| firmware |
| kernel |
| rootfs |
| nand |
| ubi |
| reserved |
| minios |
| |
| Legal fs_format values: |
| ext2 |
| ext3 |
| ext4 |
| vfat |
| fat |
| fat12 |
| fat16 |
| fat32 |
| ubifs |
| |
| Features values: |
| expand |
| last_partition |
| |
| |
| |
| In the ChromiumOS build system and installers, a number of partitions have |
| 'special' handling. Partitions with special handling are always identified |
| by partition number. Disk partitioning design is described here: |
| http://www.chromium.org/chromium-os/chromiumos-design-docs/disk-format |
| |
| Partition 1 - Stateful Partition |
| The stateful partition will have it's size expanded for USB and recovery |
| images to be exactly large enough to hold files. |
| |
| On installation, its size will be expanded to use all available space |
| on the target drive, leaving room for a 'last_partition' if it exists. |
| If it does not contain a valid file system, it will be formatted on |
| system boot. |
| |
| Partition 2 - Kernel Slot A |
| Contains the recovery kernel on recovery images. Contains the standard |
| kernel on all other images. Will be used at initial boot. |
| |
| Partition 3 - Rootfs Slot A |
| Contains the rootfs to match kernel A. It's offset on the disk must |
| match security values embedded in the standard kernel which are validated |
| by the signers. |
| |
| Partition 4 - Kernel Slot B |
| Contains the standard kernel on recovery images. Is empty on standard |
| recovery images. |
| |
| 1 block in size on USB Images |
| |
| Will be overridden with a copy of the standard kernel from Slot A after |
| installation. Will be overridden with new kernel after first update. |
| |
| Partition 5 - Rootfs Slot B |
| Empty on most USB and Recovery images. |
| |
| Will be resized to match Partition 3 during installation. |
| with a copy of the rootfs from Slot A after installation. |
| with new rootfs after first update. |
| |
| Partition 8 - OEM |
| May or may not have content installed during build image depending on the |
| board. |
| |
| Partition 12 - EFI Paritition |
| Ignored/empty on installation to ChromeOS hardware, but not during VM Tests. |
| |
| Only used with legacy boot bioses (especially during VM Testing). If |
| installation/update don't detect a secure bios (ie: ChromeOS hardware), then |
| GRUB/UBoot, or other bios boot files/kernels will be installed here. |
| |
| Partition 9 - MiniOS A (src/platform2/minios) |
| Partition at the beginning of disk. MiniOS A will have priority over |
| MiniOS B when booting. |
| |
| Partition 10 - MiniOS B |
| Has feature 'last_partition' which ensures that it is placed at the |
| end of the disk. |
| |
| Partition 11 - Powerwash data |
| The powerwash partition preserves rollback data. It does not |
| have a filesystem. |
| |
| Inheritance Rules: |
| |
| As noted above, a layout in a given file is defined by the common layout with |
| overrides specified by the named layout. The usb layout in the example above |
| is the full common layout with overrides for partition 11. Let's denote this |
| inheritance as: |
| |
| local usb <----- |
| \ |
| -- local common |
| / |
| local base <---- |
| |
| These rules change a bit when a parent is involved. Specifically, if a |
| common, usb and base are defined in a local file and a parent has them as well |
| this would be the ordering: |
| |
| overlay | parent |
| | |
| local usb <----- | ---- parent usb --- |
| \ |/ \ |
| -- local common -- -- parent common |
| / |\ / |
| local base <---- | ---- parent base -- |
| |
| Note this means if any of these are empty or not defined, the ordering is still |
| the same. For instance, if local common is not defined: |
| |
| overlay | parent |
| | |
| local usb <-----------------------|----- parent usb --- |
| | \ |
| | -- parent common |
| | / |
| local base <----------------------|----- parent base -- |
| |
| |
| If a local usb if usb isn't actually defined will be: |
| |
| overlay | parent |
| | |
| | ---- parent usb --- |
| |/ \ |
| local common -- -- parent common |
| |
| |
| Rootfs size limitations: |
| |
| In newer disk layouts (4gb and greater), the fs_size is much smaller than the |
| partition size. There are two reasons for this: |
| |
| 1. We store verity hash and a boot cache in this partition too. |
| 2. We intentionally keep the filesystem size low to catch bloat. |
| |
| If you are an on-call trying to quickly fix an issue when rootfs size is greater |
| than fs_size, you can override the board specific disk_layout.json (example CL: |
| crrev.com/c/3067827). |
| |
| Along with bumping up the fs_size, you should also flag this regression with |
| chromeos-image-size@google.com. Include the following breakdown: |
| |
| * Find the regressing build version and the last live version from Goldeneye. |
| * The last live version will have a "Live" label. Prefer to take the canary |
| version for the closest comparison. |
| * Run `cros analyze-image --board=$BOARD --version=$VERSION --spreadsheet` for |
| both the regressing build and the one before it. |
| |
| FAQ |
| |
| I want to update a package and I used to use the --rootfs_size and |
| --rootfs_partition_size options to make my root filesystem larger to aid this, |
| how do I do this now? |
| |
| Most commonly, create an image using one of the development layouts: |
| ./build_image --disk_layout 2gb-rootfs |
| ./build_image --disk_layout 2gb-rootfs-updatable |
| ./build_image --disk_layout 4gb-rootfs |