Genimage - The Image Creation Tool

genimage is a tool to generate multiple filesystem and flash/disk images from a given root filesystem tree. genimage is intended to be run in a fakeroot environment. It also supports creating flash/disk images out of different file-system images and files.

Configuration is done in a config file parsed by libconfuse. Options like the path to tools can be given via environment variables, the config file or from commandline switches.

The Configuration File

The config file of genimage uses a simple configuration language, provided by libconfuse. This supports nested sections, as well as simple key-value pairs.

Single-line comments can be introduced with # or //, multi-line comments look like /* … */ (as in C).

The config file is separated into the main sections image, flash and config, and provides an include primitive.

The image section

An image section describes a single filesystem or disk image to be built. It can be given multiple times to generate multiple images. An image can also have multiple partitions which refer to images themselves. Each image must have a type which can have different suboptions depending on the type.

Let's have a look at an example:

image nand-pcm038.img {
        flash {
        }
        flashtype = "nand-64M-512"
        partition barebox {
                image = "barebox-pcm038.bin"
                size = 512K
        }
        partition root {
                image = "root-nand.jffs2"
                size = 24M
        }
}

This would generate a nand-pcm038.img which is a flash of type "nand-64M-512" The image contains two partitions, "barebox-pcm038.bin" and "root-nand.jffs2" which must refer to images described elsewhere in the config file. For example "root-nand.jffs2" partition could be described like this:

image root-nand.jffs2 {
        name = "root"
        jffs2 {}
        size = 24M
        mountpoint = "/"
}

In this case a single jffs2 image is generated from the root mountpoint.

Here are all options for images:

Additionally each image can have one of the following sections describing the type of the image:

cpio, cramfs, ext2, ext3, ext4, file, flash, hdimage, iso, jffs2, qemu, squashfs, tar, ubi, ubifs, vfat.

Partition options:

For each partition, its final alignment, offset and size are determined as follows:

• If the align option is not present, it defaults to the value of the image's align option if the partition is in the partition table, otherwise to 1.
• If the offset option is absent or zero, and in-partition-table is true, the partition is placed after the end of all previously defined partitions, with the final offset rounded up to the partition's align value.
• Otherwise, the offset option is used as-is. Note that if absent, that option defaults to 0, so in practice one must specify an offset for any partition that is not in the partition table (with at most one exception, e.g. a bootloader).
• If the partition has the autoresize flag set, its size is computed as the space remaining in the image from its offset (for a GPT image, space is reserved at the end for the backup GPT table), rounded down to the partition's align value. If the partition also has a size option, it is ensured that the computed value is not less than that size.
• Otherwise, if the size option is present and non-zero, its value is used as-is.
• Otherwise, if the partition has an image option, the size of that image, rounded up to the partition's align value, is used to determine the size of the partition.

The following sanity checks are done on these final values (in many cases, these will automatically be satisfied when the value has been determined via one of the above rules rather than given explicitly):

• For a partition in the partition table, the partition's align value must be greater than or equal to the image's align value.
• The partition's offset and size must both be multiples of its align.
• The size must not be 0.
• The partition must not overlap any other partition, or the areas occupied by the partition table.

The image configuration options

android-sparse

Generate android sparse images. The are typically used by fastboot. Sparse images encode "don't care" areas and areas that are filled with a single 32 bit value. As a result, they are often much smaller than raw disk images. Genimage assumes that all 'holes' in the input file are "don't care" areas. This is a reasonable assumption: Tools to generate filesystems typically operate on devices. So they only create holes in areas they don't care about. Genimage itself operates the same way when generating HD images.

Options:

cpio

Generates cpio images.

Options:

cramfs

Generates cramfs images.

Options:

ext2, ext3, ext4

Generates ext* images.

Options:

file

This represents a pre-existing image which will be used as-is. When a partition section references an image that is not defined elsewhere in the configuration file, a file rule is implicitly generated. It is up to the user to ensure that the image exists in the input directory, or to use an absolute path to the image.

It is possible to add a file image explicitly, which allows one to provide genimage with some information about the image which can not be deduced automatically. Currently, one such option exists:

For example:

image foo {
        hdimage {
                partition-table-type = "gpt"
                gpt-location = 64K
        }

        partition bootloader {
                in-partition-table = false
                offset = 0
                image = "/path/to/bootloader.img"
        }

        partition rootfs {
                offset = 1M
                image = "rootfs.ext4"
        }
}

image /path/to/bootloader.img {
        file {
                holes = {"(440; 1K)", "(64K; 80K)"}
        }
}

This tells genimage that despite the bootloader partition overlapping both the last 72 bytes of the MBR (where the DOS partition table is located) and the GPT header occupying the sector starting at offset 512, this is all OK because bootloader.img does not contain useful data in that range. Further, in this example, the bootloader image has been carefully crafted to also allow placing the GPT array at offset 64K (the GPT header is always at offset 512).

If the bootloader image is not declared explicitly and only used once then the holes can also be configured in the partition. This simplifies the config file for simple use-cases.

For example:

image bar {
        hdimage {}

        partition bootloader {
                in-partition-table = false
                offset = 0
                image = "/path/to/bootloader.img"
                holes = {"(440; 512)"}
        }

        partition rootfs {
                offset = 1M
                image = "rootfs.ext4"
        }
}

FIT

Generates U-Boot FIT images.

Options:

flash

Generates flash images. These are basically the partition contents padded to the partition sizes concatenated together. There is no partition table. Needs a valid flashtype where the flash parameters are read from.

hdimage

Generates DOS partition images.

Options:

iso

Generates an ISO image.

Options:

jffs2

Generates a JFFS image. Needs a valid flashtype where the flash parameters are read from.

Options:

qemu

Generates a QEMU image. Needs at least one valid partition.

Options:

squashfs

Generates a squashfs image.

Options:

rauc

Generates a RAUC update bundle.

Options:

tar

Generates a tar image. The image will be compressed as defined by the filename suffix.

ubi

Generates an UBI image. Needs a valid flashtype where the flash parameters are read from.

Options:

ubifs

Generates a UBIFS image. Needs a valid flashtype where the flash parameters are read from.

Options:

vfat

Generates a VFAT image.

Options:

Note: If no content is specified with file or files then rootpath and mountpoint are used to provide the content.

fip

Generates a Firmware Image Package (FIP). A format used to bundle firmware to be loaded by ARM Trusted Firmware.

Options:

The Flash Section

The flash section can be given multiple times and each section describes a flash chip. The option names are mostly derived from the UBI terminology. There are the following options:

Several flash related image types need a valid flash section. From the image types the flash type section is referred to using the flashtype option which contains the name of the flash type to be used.

For more information of the meaning of these values see the ubi(fs) and mtd FAQs:

http://www.linux-mtd.infradead.org/faq/general.html

Example flash section:

flash nand-64M-512 {
        pebsize = 16384
        lebsize = 15360
        numpebs = 4096
        minimum-io-unit-size = 512
        vid-header-offset = 512
        sub-page-size = 512
}
...
image jffs2 {
        flashtype = "nand-64M-512"
}

The config section

In this section the global behaviour of the program is described. Except as noted below, all options here can be given from either environment variables, the config file or command line switches. For instance, a config option foo can be passed as a --foo command line switch or as a GENIMAGE_FOO environment variable.

Include Configurations Fragments

To include a "foo.cfg" config file, use the following statement:

include("foo.cfg")

This allows to re-use, for example flash configuration files, across different image configurations.