YAML Config Interface

Introduction

The configuration interfaces using a YAML file is implemented in the plugin embdgen-config-yaml. This can load a configuration file and run embdgen to generate an image. The idea is to describe an image in a hierarchial structure in a declarative format. A label is the root of this hierarchy. It can be an MBR or GPT partition table.

One label consists of multiple regions. A region can but does not have to be part of the partition table. This can be useful, for example, when the bootloader requires data at a specific address.

Every region is filled with content. A content can be everything, that is written to the image. Some contents are containers for other contents, so that the data written to image is transformed or enhanced with metadata for example. Examples for these staggered contents are:

An ext4 filesystem content which is created from an archive content

A raw filesystem image with added verity metadata

If a content (for example an archive) is split up into multiple contents, a generator has to be used. In that case the root of the yaml document is split up into a contents and an image node. See section Content Generator Example.

Simple Example

Every element in the tree is YAML sequence, that contains a scalar type, that identifies the implementation.

simple example

type: mbr
boot_partition: boot

parts:
  - name: u-boot part 1
    type: raw
    start: 0
    size:  256 B
    content:
      type:  raw
      file:  files/fip.s32

  - name: u-boot part 2
    type: raw
    start:  512 B
    content:
      type:   raw
      file:   files/fip.s32
      offset: 512 B

  - name: uboot.env
    type:  empty
    start: 0x1e0000 B
    size:  0x2000 B

  - name: boot
    type: partition
    fstype: fat32
    content:
      type: fat32
      content:
        type: files
        files:
          - files/fitimage
    size: 100 MB

  - name: root
    type: partition
    fstype: ext4
    content:
      type: raw
      file: files/root.raw

The example above would create a master boot record partition table, with two partition entries (boot and root). This fat32 boot partition is created by embdgen and contains a single file (fitimage). The root partition is an ext4 partition, that is filled with a partition image, that already contains an ext4 filesystem. Three additional partitions are created, that are not recorded in the partition table. This setup is an example for the bootloader requirements the NXP’s S32 series of SoCs:

uboot part 1 and 2: Write NXP specific code (i.e. the image vector table with its payload uboot and atf) around the partition table (between byte 256 and 512)

uboot.env: Creates an unused range (type: empty) between 0x1e0000 and 0x1e2000, which is the default area, where NXP’s u-boot writes its environment

To generate the image, the embdgen can be executed from the directory where the config file is stored and the files directory with the referenced files exist. Assuming the yaml config is save as config.yml:

$ embdgen config.yml
Preparing...

The final layout:
MBR:
  0x00000000 - 0x00000100 Part u-boot part 1
    RawContent(files/fip.s32@0x00000000)
  0x000001b8 - 0x00000200 Part MBR Header
  0x00000200 - 0x000fead0 Part u-boot part 2
    RawContent(files/fip.s32@0x00000200)
  0x001e0000 - 0x001e2000 Part uboot.env
  0x001e2000 - 0x065e2000 Part boot
    Fat32Content()
  0x065e2000 - 0x1c0e3000 Part root
    RawContent(files/root.raw@0x00000000)

Writing image to image.raw

The tool prints out the final layout of all Regions. There is now one more region than defined in the config file (“MBR Header”). This is inserted by the MBR label, to reserve the area where the partition table is written to. For the boot and root partition no start addresses were defined in the config file, so these addresses are calculated automatically to the next free offset in the image.

Content Generator Example

generator example

contents:
  - name: archive
    type: split_archive
    archive: files/archive.tar
    splits:
      - name: home
        root: home
      - name: data
        root: data
    remaining: root


image:
  type: mbr
  parts:
    - name: root
      type: partition
      fstype: ext4
      content:
        type: verity
        metadata: root.verity
        content:
          size: 100MB
          type: ext4
          content: archive.root

    - name: home
      type: partition
      fstype: ext4
      size: 100MB
      content:
        type: ext4
        content: archive.home

    - name: data
      type: partition
      fstype: ext4
      size: 100MB
      content:
        type: ext4
        content: archive.data

This example uses the split archive content generator, to split the archive in files/archive.tar into three separate contents and assigns names to these contents according to the name of the module used (archive) and the name of split and the remaining property.

archive.home will contain the content of the directory home in the archive

archive.data will contain the content of the directory data in the archive

archive.remaining will contain all remaining files and empty folders for home and data

The image definition will then create an image with three entries in the partition table. For the root partition dm verity metadata is created as well.

Reference

This configuration reference is generated with all plugins loaded.

Label Types

GUID Partition Table (GPT) partition type (`gpt`)

Options

(required) partsList[BaseRegion]: List of regions to be included in the image
boot_partitionstr: Name of the partitions marked as ‘bootable’

Master Boot Record (DOS) partition type (`mbr`)

If more than 4 partitions are configured, all partitions starting at the third will be created as extended partitions automatically.

Options

(required) partsList[BaseRegion]: List of regions to be included in the image
boot_partitionstr: Name of the partitions marked as ‘bootable’
diskidint: Diskid value (part of the partition table metadata)

Region Types

A region without any data (`empty`)

This can be used to reserve a range (e.g. for the uboot environment) This does not generate an entry in the partition table.

Options

(required) namestr

Name of the region

sizeSizeType

Size of the region

This can either be specified or should be calculated automatically by the label or the content

startSizeType

Start of the region

This can either be specified or should be calculated automatically by the label implementation.

Partition region (`partition`)

This creates an entry in the partition table

Options

(required) contentBinaryContent

Content of this Region

(required) fstypestr

Filesystem type of this region (e.g. ext4, fat32)

(required) namestr

Name of the region

sizeSizeType

Size of the region

This can either be specified or should be calculated automatically by the label or the content

startSizeType

Start of the region

This can either be specified or should be calculated automatically by the label implementation.

Raw region (`raw`)

Writes some BinaryContent directly to the image without any partition table entry.

Options

(required) contentBinaryContent

Content of this region

(required) namestr

Name of the region

sizeSizeType

Size of the region

This can either be specified or should be calculated automatically by the label or the content

startSizeType

Start of the region

This can either be specified or should be calculated automatically by the label implementation.

Content Types

Cominit content (`cominit`)

Creates a partition with metadata for cominit

There are currently two modes (dm_type) implemented: plain to create cominit metadata for a normal partition with the given filesystem or verity to create cominit metadata for a verity partition with the given filesystem and metadata.

Options

(required) contentBinaryContent: Content of the cominit partition
(required) dm_typestr: The type (either plain or verity)
(required) filesystemstr: Type of the filesystem, that is contained in the partition and mounted by cominit
(required) keyPath: Path to the private key for signing the cominit metadata
metadataPath: If dm_type == verity, path to the metadata of the verity content (as generated by veritysetup or the VerityContent module)
readonlybool: Set to true, to make cominit mount the partition readonly (required for dm_type == verity)

Content from an archive (`archive`)

Options

(required) archivePath: Archive to be unpacked

Empty content (`empty`)

Options

Ext4 Content (`ext4`)

Options

contentFilesContentProvider: Files, that are added to the filesystem
sizeSizeType: N/A

Fat32 Content (`fat32`)

Currently this can only be created using a FilesContent, that contains a list of files, that are copied to the root of a newly created fat32 filesystem.

Options

contentFilesContentProvider: Content of this region
sizeSizeType: N/A

A list of files (`files`)

It is up to the including content module, to decide what happens with the files.

Options

(required) filesList[Path]: The list of files Wildcards are allowed and expanded using python glob module. Note that you probably only want one glob for a directory like dir/*. This will include all files including the directory structure under and excluding dir.

Raw binary content (`raw`)

It is up to the including content module, to decide what happens with the files.

Options

(required) filePath

Path of the raw content file

offsetSizeType

Offset into the input file.

This can be used, if the file has a header, that should be skipped.

In combination with RawRegion’s size attribute, this can also be used, to copy a specific part of a fle to the resulting image.

Resize an ext4 partition (`resize_ext4`)

Allows increasing the size of an ext4 filesystem

Options

(required) contentBinaryContent

Content to resize

add_spaceSizeType

Space to add.

This must be a multiple of the sector size (see: SizeType)

U-Boot Environment region (`uboot_env`)

The variables passed in using file and vars is merged with variables defined in vars overwriting variables defined in the variables file.

Options

filePath: Variable file with key=value pairs
varsDict: Variables placed in the environment

dm-verity hashed content (`verity`)

Calculates the hashes for the content and writes them directly after the content (block aligned).

Additionally a metadata file is generated, that contains the all values required, to open the verity device. This file can be parsed by CominitContent (from embdgen-cominit), to generate cominit metadata.

Options

(required) contentBinaryContent

The payload content of the partition

(required) metadataPath

A path to a file, where the metadata is written to.

This is in the same format as the output of veritysetup.

algorithmstr

Hash algorithm to use (defaults to sha256)

data_block_sizeSizeType

Size of data blocks (defaults to 4096)

hash_block_sizeSizeType

Size of hash blocks (defaults to 4096)

saltstr

Salt to use for verity hashes. This can be useful, to generate reproducible images

use_internal_implementationbool

If set to false, veritysetup is used, otherwise a pure python solution is used, to generate the hash tree.

Content Generator Types

Split an archive into multiple parts (`split_archive`)

This can be used to create multiple content modules from a single archive. Each split can define up to one root directory. The content of that directory is moved to the split and the directory is kept as an empty directory (that can be used as a mountpoint later).

Options

(required) archivePath: Archive to be unpacked
(required) namestr: Name of this content generator
(required) splitsList[Split]: List of splits
remainingstr: Name of the remaining content

Utility: Split for a SplitArchiveContentGenerator (Split)

Options

(required) namestr: Name of this split
(required) rootstr: Root directory of this split in the archive
remove_rootbool: If set to true, the root directory of the split is removed from the remaining tree

YAML Config Interface

Introduction

Simple Example

Content Generator Example

Reference

Label Types

GUID Partition Table (GPT) partition type (gpt)

Options

Master Boot Record (DOS) partition type (mbr)

Options

Region Types

A region without any data (empty)

Options

Partition region (partition)

Options

Raw region (raw)

Options

Content Types

Cominit content (cominit)

Options

Content from an archive (archive)

Options

Empty content (empty)

Options

Ext4 Content (ext4)

Options

Fat32 Content (fat32)

Options

A list of files (files)

Options

Raw binary content (raw)

Options

Resize an ext4 partition (resize_ext4)

Options

U-Boot Environment region (uboot_env)

Options

dm-verity hashed content (verity)

Options

Content Generator Types

Split an archive into multiple parts (split_archive)

Options

Utility: Split for a SplitArchiveContentGenerator (Split)

Options

GUID Partition Table (GPT) partition type (`gpt`)

Master Boot Record (DOS) partition type (`mbr`)

A region without any data (`empty`)

Partition region (`partition`)

Raw region (`raw`)

Cominit content (`cominit`)

Content from an archive (`archive`)

Empty content (`empty`)

Ext4 Content (`ext4`)

Fat32 Content (`fat32`)

A list of files (`files`)

Raw binary content (`raw`)

Resize an ext4 partition (`resize_ext4`)

U-Boot Environment region (`uboot_env`)

dm-verity hashed content (`verity`)

Split an archive into multiple parts (`split_archive`)