Layout Configuration Reference

API Version

api-version (integer)

The API version used in this configuration file. The API version must reflect the options being used in the layout configuration file. E.g. when using the option bootbus from the mmc section, the API version must be at least 2.

The provided number must be equal or smaller than the major version of the currently used partup executable. This means the partup executable is backwards-compatible with previous API versions of layout configuration files. An exception are alpha releases with program and API version 0, which are never compatible with stable releases starting with 1. See the following table for examples of compatible version combinations:

API version	Compatible partup versions
0	0 only
1	1, 2, 3, …
2	2, 3, 4, …
3	3, 4, 5, …

This scalar is mandatory.

Supported Device Types

supported-device-types (sequence)

A sequence of supported device type strings. Possible options are:

mmc: MultiMediaCard (MMC) devices, such as SD cards and eMMC.
hd: Hard disk drives, including SSD and NVMe devices.
mtd: Memory Technology Devices (MTD) used as an abstraction layer for raw NOR and NAND flash devices.

The default value is [mmc, hd].

Available since: 3.0.0

MMC and HD Options

Disk Options

disklabel (string)

Partition table for the device. Currently supported options are msdos (default) and gpt.

Since 2.2.0, not specifying disklabel or setting it to null will skip partitioning altogether and omit any overwrite checks. In particular, this can be used to flash devices with raw disk images that already contain a partition table and associated partitions.

alignment (string)

Alignment type of all partitions to be written to the device. This specifies how the partitions’ start and end sector are placed.

The following alignment types are currently supported:

minimal/minimum: Align partitions to the minimum hardware requirements.
optimal/optimum: Align partitions on the device for optimal performance.

The default alignment type is optimal.

If no alignment information can be retrieved from the device, a block size of 1 MiB is used.

Available since: 4.0.0

Clean Data

The section clean contains a sequence of mappings describing where the mmc device is cleaned outside of partitions. Each entry should contain the following options:

offset (integer/string)

Offset of the cleaned space.

size (integer/string)

Size of the cleaned space.

It is possible set a string with a unit after the size number, e.g. 12kiB or 34MB. Possible units are the same as specified by GNU parted’s unit command. When no unit is specified, the default is sectors.

Raw Data

The section raw contains a sequence of mappings describing data that is written outside of partitions.

Since 2.1.0, the written output is always being verified by checking against the input’s SHA1 sum, including any given offsets. The checksum is not being verified when --skip-checksum is given as a runtime argument. Note, that this checksum is independent from the input’s sha256sum option.

Each raw entry may contain the following options:

input-offset (integer/string): Offset of the input data to be written.
output-offset (integer/string): Offset of the written output data.
input (mapping): An input mapping. See Input Files.

Partitions

The section partitions contains a sequence of mappings describing the contained partitions of an MMC device. Each entry may contain the following options:

label (string)

A partition label. The label is set in the filesystem of the partition and in the partition table if GPT is used. For raw ext[234] images, providing a label overwrites the label included in the filesystem image. The default value is null.

partuuid (string)

The PARTUUID of the partition. Only supported on GPT partitioned devices. A random UUID is used by default.

type (string)

The partition type. May be one of primary or logical. Note, that with the first occurrence of a logical partition the following ones must be logical, too. Logical partitions are only supported with the msdos partition table.

filesystem (string)

The filesystem type to use during formatting of the partition.

The following filesystems are currently supported:

ext2
ext3
ext4
fat16 (Available since: 2.0.0)
fat32

mkfs-extra-args (string)

Extra arguments to be passed to mkfs. Note, that the allowed arguments may be different, depending on the used filesystem type. See the man page of mkfs with the particular filesystem to read up allowed arguments, e.g. man mkfs.fat.

Available since: 2.0.0

size (integer/string)

The size of the partition.

It is possible set a string with a unit after the size number, e.g. 12kiB or 34MB. Possible units are the same as specified by GNU parted’s unit command. When no unit is specified, the default is sectors.

expand (boolean)

Expands the partition to fill the rest of the flash device. If multiple partitions are specified to be expanding, then the space is equally divided between them. By default, partitions do not expand.

offset (integer/string)

The offset of a partition.

block-size (integer/string)

Set the partition size to a multiple of the specified value. The default is the device’s alignment grain size. This depends on the selected alignment type. See alignment (string) for more information.

flags (sequence)

Set flags for this partition. Flags to be enabled should be provided as a sequence of strings. Possible flags are the same as specified by GNU parted’s set command.

input (sequence)

A sequence of input mappings. See Input Files.

MMC-specific Controls

MMC specific controls can be specified using the keyword mmc containing a mapping of the following options:

hwreset (string)

Enable or disable the eMMC H/W reset feature with enable or disable. By default, H/W reset is not changed.

Warning

This is a one-time programmable, irreversible change.

Available since: 2.0.0

bootbus (string)

Set the boot bus conditions. See the mmc-utils manpage for a description of possible values.

Available since: 2.0.0

boot-partitions (mapping)

An eMMC boot partitions mapping. See eMMC Boot Partitions.

eMMC Boot Partitions

eMMC’s special boot partitions can be specified using the keyword boot-partitions containing a mapping of the following options:

enable (integer)

Enable and select the boot partition. 0 to disable boot partitions.

boot-ack (boolean)

Set the boot acknowledge property of the eMMC. The default value is false.

Available since: 2.0.0

binaries (sequence)

A sequence of binaries to copy to the boot partitions. See Binaries. This keyword is optional.

Binaries

Binary files are specified by a scalar named binaries containing a sequence of mappings with at least an input.

Since 3.0.0, the written output is always being verified by checking against the input’s SHA1 sum, including any given offsets. The checksum is not being verified when --skip-checksum is given as a runtime argument. Note, that this checksum is independent from the input’s sha256sum option.

input-offset (integer/string): Offset of the input data to be written. This keyword is optional.
output-offset (integer/string): Offset of the written output data. This keyword is optional.
input (mapping): An input mapping. See Input Files.

MTD Options

Memory Technology Device (MTD) support is available since: 3.0.0

MTD Partitions

The section partitions contains a sequence of mappings describing the contained partitions of an MTD. Each entry may contain the following options:

name (string)

The partition name. The name is used to identify the partition. However, multiple partitions may have the same name. The default value is null.

Available since: 3.0.0

size (integer/string)

The size of the partition. This scalar is mandatory and must be greater than zero. The size must also be a multiple of the underlying device’s erase block size, if not using an expanding partition.

It is possible set a string with a unit after the size number, e.g. 12kiB or 34MB. Possible units are the same as specified by GNU parted’s unit command. When no unit is specified, the default is sectors.

Available since: 3.0.0

offset (integer/string)

The offset of a partition, relative to the previous partition (or the beginning of the device for the first partition). The default value is 0.

Available since: 3.0.0

erase (boolean)

Erases the partition after creation and before writing any data. The default value is true.

Available since: 3.0.0

expand (boolean)

Expand a partition to the rest of the device. Only the last partition can be expanded. The default is false for all partitions.

Available since: 3.0.0

input (mapping)

An input mapping. See Input Files.

The written output is always being verified by checking against the input’s SHA1 sum, including any given offsets. The checksum is not being verified when --skip-checksum is given as a runtime argument. Note, that this checksum is independent from the input’s sha256sum option.

Available since: 3.0.0

Input Files

Input files are specified by a scalar named input containing a mapping with at least a filename. For verifying the checksum of the given input file by filename, an optional checksum can be provided with md5sum and/or sha256sum.

filename (string): A valid relativ path pointing to a file that should be written to the parent partition or volume.
md5sum (string): The MD5 sum of the given file specified by filename. This sum is checked against the provided file before writing to the target partition or volume.
sha256sum (string): The SHA256 sum of the given file specified by filename. This sum is checked against the provided file before writing to the target partition or volume.

Supported File Types

The provided input files are copied to the filesystem of the corresponding partition by default. However, if files are of one of the supported special file types, they are treated as following.

tar or tar.*: Archives and compressed archives are extracted into the filesystem.
ext[234]: Raw filesystem files are written directly to the partition. This overrides any existing filesystem, so it should be specified as filesystem: null or not be specified at all. Additionally ext filesystems are resized to utilize the whole partition.