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.

 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_system
                brillo_odm
                brillo_userdata
                brillo_misc
                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.

 rpi_boot:    This is a Raspberry Pi boot partition. You can have one and only
              one such partition. Declaring it introduces several hacks into the
              protective MBR to allow this partition to appear as a boot
              partition to the Pi's (MBR-only) boot loader, but still present a
              GPT partition table to the Linux kernel after boot.

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".

-- 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'.