README

This directory contains a tool for partitioning disk images for Brillo
and Android.

-- FILES AND DIRECTORIES

 Android.mk

   Build instructions.

 bpttool

   A tool written in Python for partioning disk images.

 bpttool_test

   Unit tests for bpttool.

 test/

   Contains test data used in unit tests.

-- PARTITION DEFINITION FILES

Partitioning directives are expressed in JSON and the file extension
".bpt" is typically used. A typical .bpt-file looks like this

  {
      "settings": {
          "disk_size": "4 GiB"
      },
      "partitions": [
          {
              "ab": true,
              "label": "boot",
              "size": "32 MiB",
              "guid": "auto",
              "type_guid": "brillo_boot"
          },
          {
              "ab": true,
              "label": "system",
              "size": "512 MiB",
              "guid": "auto",
              "type_guid": "brillo_system"
          },
          [...]
          {
              "label": "userdata",
              "grow": true,
              "guid": "auto",
              "type_guid": "brillo_userdata"
          }
      ]
  }

The two root objects are "settings" and "partitions". Well-known
key/value-pairs for "settings" are

 ab_suffixes:    List of suffixes to use for A/B partitions, for example
                 ["-A", "-B"] or ["0", "1", "2"]. Default is ["_a",
                 "_b"].

 disk_size:      The size of the target disk to use, in bytes. This has
                 no default value.

 partitions_offset_begin :
                 The size of the disk partitions offset begin, in bytes.
                 Default is 0.

 disk_alignment: The alignment, in bytes, to use when laying out
                 partitions. Default is 4096.

 disk_guid:      The GUID to use for the disk or 'auto' to make bpttool
                 generate it. The default is 'auto'.

Each of these settings can be overriden or set using command-line
options in bpttool.

The "partitions" object is an array of objects with the following
well-known key/value pairs:

 label:       The label of the partition. This must be able to fit in 36
              UTF-16 code-points.

 offset:      Offset of the partition, in bytes. This will always be
              re-calculated when using bpttool.

 size:        Size of the partition, in bytes.

 grow:        If 'true', the partition will be grown to use available free
              space. Default value is 'false'.

 guid:        The GPT instance GUID. Default value is 'auto'.

 type_guid:   The GPT type GUID. A RFC-4122 style GUID is accepted as
              are the following special values:

                brillo_boot
                brillo_bootloader
                brillo_system
                brillo_odm
                brillo_oem
                brillo_userdata
                brillo_misc
                brillo_vbmeta
                brillo_vendor_specific
                linux_fs
                ms_basic_data

              for well-known GPT partition GUIDs. If unset, the value
              'brillo_vendor_specific' is used.

 flags:       A 64-bit integer (decimal or hexadecimal representations are
              accepted) for GPT flags. Default value is 0.

 ignore:      If 'true', the partition will not be included in the final
              output.

 ab:          Set to 'true' if the partition should be expanded for A/B.
              Default value is 'false'.

 ab_expanded: Set to 'true' only if this partition has already been
              expanded for A/B. Default value is 'false'.

 position:    The position for the partition, used to determine the sequence
              of partitions (and, indirectly, partition numbers) or 0 if
              position doesn't matter. Partitions with low 'position'
              numbers will be laid out before partitions with high
              'position' numbers. Default value is 0.

For key/value-pairs involving sizes, either integers can be used, e.g.

 "size": 1048576

means 1 mebibyte. Strings with base-10 units (kB, MB, GB, TB, PB) and
base-2 units (KiB, MiB, GiB, TiB, PiB) are also supported. For
example:

 "size": "1 MiB"

means 1,048,576 bytes and

 "size": "1 MB"

means 1,000,000 bytes.

If a partition size is not a multiple of the disk sector size, it will
be rounded up and if a disk size is not a multiple, it will be rounded
down.

The bpttool program reads one or more of .bpt-files and the order
matters. Partitions are identified by label and if a partition has
already been mentioned in a previous file, directives in the latter
file will override the existing entry. This allows for setups where
e.g. a file with the following content

  {
      "partitions": [
          {
              "label": "system",
              "size": "128 MiB"
          }
      ]
  }

can be used on top to specify that system partitions should be 128 MiB
instead of 512 MiB. Similarly, a file with the content

  {
      "partitions": [
          {
              "label": "my_app_data",
              "size": "512 MiB",
              "type_guid": "linux_fs"
          }
      ]
  }

can be used on top to have a new 512 MiB partition "my_app_data" in
addition to existing partitions. Notably the "userdata" data partition
will be shrunk in order to make room for the newly added partition.

Additionally, 'bpttool make_table' generates a .bpt-file - in addition
to the binary GPT partition tables - that is complete in the sense
that it can be used as input to generate the same output without
additional command-line options.

Also, expanded A/B partitions in input files are folded and then
expanded again. This allows for setups as the following:

 $ bpttool make_table \
    --input prev_output.bpt \
    --ab_suffixes "-A,-B,-C" \
    --output_json new_output.bpt
    [...]

where if prev_output.bpt contained the partitions "system_a",
"system_b" (for the default A/B suffixes) then new_output.bpt would
contain partitions "system-A", "system-B", and "system-C".

-- DISK IMAGE GENERATION

Disk images may be created given an unfolded .bpt file. 'bpttool
make_disk_image' generates the output disk image file.

To generate a disk image, use the following subcommand:

  $ bpttool make_disk_image \
      --output disk-image.bin \
      --input /path/to/bpt-file.bpt \
      --image system_a:/path/to/system.img \
      --image boot_a:/path/to/boot.img \
      [...]

where the 'output' argument specifies the name and location of the outputted
disk image and the 'input' argument is the .bpt file containing valid labels and
offsets for each partition.  The 'image' argument specifies a mapping  from
partition name/label to the path of the corresponding image partition image.
All partitions specified in the .bpt file must be passed in via the 'image'
argument.

Typically, each of the 'image' argument files are located in the
ANDROID_PRODUCT_OUT directory after a build is complete.

-- BUILD SYSTEM INTEGRATION NOTES

To generate partition tables in the Android build system, simply add
the path to a .bpt file to the BOARD_BPT_INPUT_FILES variable.

 BOARD_BPT_INPUT_FILES += "hardware/bsp/vendor/soc/board/board-specific.bpt"

The variable BOARD_BPT_DISK_SIZE can be used to specify or override
the disk size, for example:

 BOARD_BPT_DISK_SIZE := "10 GiB"

Additional arguments to 'bpttool make_table' can be specified in the
variable BOARD_BPT_MAKE_TABLE_ARGS.

If BOARD_BPT_INPUT_FILES is set, the build system generates two files

 partition-table.img
 partition-table.bpt

in ${ANDROID_PRODUCT_OUT} using 'bpttool make_table'. The former is
the binary partition tables generated using bptool's --output_gpt
option and the latter is a JSON file generated using the --output_json
option. These files will also be put in the IMAGES/ directory of
target-files.zip when running 'm dist'.