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