| # 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 |
| overlay-<board>/scripts/legacy_disk_layout.json symlink -> |
| scripts/build_library/legacy_disk_layout.json |
| list legacy_disk_layout.json as a parent in disk_layout.json. |
| |
| To create a board specific layout that is all new: |
| Read the list of partitions with special handling below. |
| Create overlay-<board>/scripts/disk_layout.json |
| |
| 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 are used here. |
| { |
| "_comment": "_comment entries will be ignored.", |
| |
| // Optional. Defaults to false. |
| "hybrid_mbr": true, |
| |
| // 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, 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" |
| } |
| ], |
| // common is usually good enough for "base", the partition installed on the |
| // fixed device. |
| "base": [ |
| ], |
| "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 |
| |
| 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 |
