build_library/README.disk_layout - mirrors/cros/chromiumos/platform/crosutils - Git at Google

 # 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
	# 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