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 config file of genimage uses a simple configuration language, provided by libconfuse. This supports nested sections, as well as simple key-value pairs.
The config file is separated into the main sections image, flash and config,
and provides an include primitive.
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 |
| mountpoint: | mountpoint if image refers to a filesystem image. |
| exec-pre: | Custom command to run before generating the image. |
| exec-post: | Custom command to run after generating the image. |
| flashtype: | refers to a flash section. Optional for non flash like images like hd images |
| partition: | can be given multiple times and refers to a partition described below |
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, 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. The last partition may have size 0 to make this partition use the rest of the available space on the device. |
| partition-type: | Used by dos partition tables to specify the partition type. |
| image: | The image file this partition shall be filled with |
| autoresize: | used by ubi (FIXME: do we need this? isn't size = 0 enough) |
| bootable: | Boolean specifying whether to set the bootable flag. |
| in-partition-table: | Boolean specifying whether to include this partition in the partition table. |
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. |
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
}
In this section the global behaviour of the program is described. 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.
| config: | default: genimage.cfg
Path to the genimage config file. |
|---|---|
| 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. |
| 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) |
| tar: | path to the tar program (default tar) |
| tune2fs: | path to the tune2fs program (default tune2fs) |
| ubinize: | path to the ubinize program (default ubinize) |
To include a "foo.cfg" config file, use the following statement:
include("foo.cfg")
This allows to re-use, for example flash configuration files, accross different image configurations.