blob: b4e604926f7d361ae54a1c46ec4ee579980f1fdf [file] [log] [blame]
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.
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'.