| # 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 <current_year>_disk_layout.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. Expand is only supported value. | |
| "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 | |
| Legal fs_format values: | |
| ext2 | |
| ext3 | |
| ext4 | |
| vfat | |
| fat | |
| fat12 | |
| fat16 | |
| fat32 | |
| ubifs | |
| Features values: | |
| expand | |
| 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. If it does not contain a valid file system, it will | |
| be formatted to ext4 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. | |
| 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 | |
| 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 |