==================================

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

.. _libconfuse: https://github.com/martinh/libconfuse

Single-line comments can be introduced with

#

//

/* … */

The config file is separated into the main sections

image

flash

config

include

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:

:name: The name of this image. This is used for some image types to set the name of the image. :size: Size of this image in bytes. 'k', 'M' or 'G' can be used as suffix to specify the size in multiple of 1024 etc. The suffix 's' specifies a multiple of the (traditional) sector size of 512. If the image if filled from a mountpoint then '%' as suffix indicates a percentage. '200%' means the resulting filesystem should be about 50% filled. Note that is is only a rough estimate based on the original size of the content. :mountpoint: mountpoint if image refers to a filesystem image. The default is "/". The content of "${rootpath}${mountpoint}" will be used used fill the filesystem. :empty: If this is set to true, then the specified rootpath and mountpoint are ignored for this image and an empty filesystem is created. This option is only used for writeable filesystem types, such as extX, vfat, ubifs and jffs2. This defaults to false. :temporary: If this is set to true, the image is created in

tmppath

outputpath

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:

:offset: The offset of this partition as a total offset to the beginning of the device. :size: The size of this partition in bytes. If the size and autoresize are both not set then the size of the partition image is used. :align: Alignment value to use for automatic computation of

offset

size

align

autoresize

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:

:image: The source image that will be converted. :block-size: The granularity that the sparse image uses to find "don't care" or "fill" blocks. The supported block sizes depend on the user. The default is 4k.

cpio

Generates cpio images.

Options:

:format: archive format. Passed to the

-H

bin

odc

newc

crc

tar

ustar

hpbin

hpodc

gzip

lzop

cramfs

Generates cramfs images.

Options:

:extraargs: Extra arguments passed to mkcramfs

ext2, ext3, ext4

Generates ext* images.

Options:

:use-mke2fs: If set to true, then mke2fs is used to create the image. Otherwise, genext2fs is used. Defaults to false. :mke2fs-conf: mke2fs.conf that should be used. If unspecified, the system default is used. :extraargs: Extra arguments passed to genext2fs or mke2fs. :features: Filesystem features. Passed to the

-O

man ext4

has_journal

extents,uninit_bg,dir_index,has_journal

^

-L

set_current_time

set_super_value mkfs_time

set_super_value lastcheck

0:0

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

It is possible to add a

file

genimage

:holes: A list of

"(;)"

For example::

image foo { hdimage { gpt = true 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

bootloader

bootloader.img

FIT

Generates U-Boot FIT images.

Options:

:its: String option holding the path of the input its file :keydir: String option holding the directory containing the keys used for signing.

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:

:align: Partition alignment. Defaults to 512 bytes :partition-table: Boolean. If true, writes a partition table. If false, no partition table is generated. Defaults to true. Deprecated: use

partition-table-type

none

in-partition-table

mbr

gpt

hybrid

partition-type

random

partition-table-type

iso

Generates an ISO image.

Options:

:boot-image: Path to the El Torito boot image. Passed to the

-b

-no-emul-boot -boot-load-size 4 -boot-info-table -c boot.cat -hide boot.cat

default

-V

jffs2

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

Options:

:extraargs: Extra arguments passed to mkfs.jffs2

qemu

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

Options:

:format: A valid

qemu-img

qcow

qcow2

parallels

vdi

vhdx

vmdk

qemu-img convert --help

qcow2

qemu-img convert

squashfs

Generates a squashfs image.

Options:

:extraargs: Extra arguments passed to mksquashfs :compression: compression type for the image. Possible values are

gzip

lzo

xz

none

-b

rauc

Generates a RAUC update bundle.

Options:

:extraargs: Extra arguments passed to RAUC :file: Specify a file to be added into the RAUC bundle. Usage is:

file foo { image = "bar" }

--key

--cert

--keyring

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:

:extraargs: Extra arguments passed to ubinize

ubifs

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

Options:

:extraargs: Extra arguments passed to mkubifs :max-size: Maximum size of the UBIFS image

vfat

Generates a VFAT image.

Options:

:extraargs: Extra arguments passed to mkdosfs :label: Specify the volume-label. Passed to the

-n

file foo { image = "bar" }

Note: If no content is specified with

file

files

rootpath

mountpoint

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:

:pebsize: The size of a physical eraseblock in bytes :lebsize: The size of a logical eraseblock in bytes (for ubifs) :numpebs: Number of physical eraseblocks on this device. The total size of the device is determined by pebsize * numpebs :minimum-io-unit-size: The minimum size in bytes accessible on this device :vid-header-offset: offset of the volume identifier header :sub-page-size: The size of a sub page in bytes.

Several flash related image types need a valid flash section. From the image types the flash type section is referred to using the

flashtype

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

--foo

:config: default:

genimage.cfg

:loglevel: default: 1 genimage log level.

:outputpath: default: images Mandatory path where all images are written to (must exist). :inputpath: default: input This mandatory path is searched for input images, for example bootloader binaries, kernel images (must exist). :rootpath: default: root Mandatory path to the root filesystem (must exist). :tmppath: default: tmp Optional path to a temporary directory. There must be enough space available here to hold a copy of the root filesystem. :includepath: Colon-separated list of directories to search for files included via the ``include'' function. The current directory is searched after these. Thus, if this option is not given, only the current directory is searched. This has no effect when given in the config file.

:cpio: path to the cpio program (default cpio) :dd: path to the dd program (default dd) :e2fsck: path to the e2fsck program (default e2fsck) :genext2fs: path to the genext2fs program (default genext2fs) :genisoimage: path to the genisoimage program (default genisoimage) :mcopy: path to the mcopy program (default mcopy) :mmd: path to the mmd program (default mmd) :mkcramfs: path to the mkcramfs program (default mkcramfs) :mkdosfs: path to the mkdosfs program (default mkdosfs) :mkfsjffs2: path to the mkfs.jffs2 program (default mkfs.jffs2) :mkfsubifs: path to the mkfs.ubifs program (default mkfs.ubifs) :mksquashfs: path to the mksquashfs program (default mksquashfs) :qemu-img: path to the qemu-img program (default qemu-img) :tar: path to the tar program (default tar) :tune2fs: path to the tune2fs program (default tune2fs) :ubinize: path to the ubinize program (default ubinize)

Include Configurations Fragments

To include a

"foo.cfg"

include("foo.cfg")

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