diskimage configuration file

The configuration file has these parts:

• disk configuration—(Required unless the output file is a disk device) A description of disk-wide parameters.
• partition definitions—(Optional) Any number of partition descriptions. The partition descriptions specify the partitions to create, as well as the contents and characteristics (attributes) of each partition.
• raw data sections—(Optional) Any number of raw data sections (e.g., for IPLs), stored outside partitions.

The configuration file uses a specific syntax. The following general rules apply:

• Line breaks and spaces can occur anywhere, except in literals or tokens.
• Whitespaces used in a string literal in double quotes ("") are interpreted as part of that string.
• A line feed (LF) character indicates the end of a line. Carriage return characters (CR) are silently ignored and aren't interpreted as the end of line.
• A hash (#) character indicates the beginning of a comment. Comments can begin anywhere and always extend to the end of the line.
• Numeric values can be specified as decimal, octal, or hexadecimal. Optionally, numeric values can use these suffix values to indicate a factor:
  • k or K to represent kilo (1024)
  • m or M to represent mega (1024²)
  • g or G to represent giga (1024³)
  • t or T to represent tera (1024⁴)
  • p or P to represent peta (1024⁵)

The diskimage command supports the following disk attributes:

cylinders=number

(Required) The number of cylinders on the disk. The value must be in the range 1–4294967295 (i.e., 2³² - 1) for MBR disks or 1–18446744073709551615 (i.e., 2⁶⁴ - 1) for GPT disks.

heads=number

(Required) The number of heads on the disk. The value must be in the range 1–255.

sectors_per_track=number

(Required) The number of sectors on each track. The value must be in the range 1–63.

sector_size=number

(Optional) The number of bytes per sector. The value must be one of 512, 1024, 2048, or 4096. If not specified, a default value of 512 is used.

num_sectors=number

(Optional) The total number of sectors on the disk. This is usually calculated from the values for cylinders, heads, and sectors_per_track. If the number of sectors that the device reports isn't the product of these three, you must explicity specify the total sector count to generate correct GPT disk images.

• For MBR, the value must be in the range 1–8589934590 (i.e., 2³³ - 2), but we recommend a maximum of 4294967295 (i.e., 2³² - 1). If you use a value that's greater than the recommended one, diskimage gives you a warning.
• For GPT disks, the value must be in the range 1–18446744073709551615 (i.e., 2⁶⁴ - 1)

align=number

(Optional) The sector count for partition alignment. Every partition is adjusted such that its first sector number is an integral multiple of this value. The value must be in the range 1–4294967295 (2³² - 1) for MBR disks or 1–18446744073709551615 (2⁶⁴ - 1) for GPT disks. By default, the number of sectors per cylinder is used (i.e., each partition begins on a cylinder boundary).

start_at_cylinder=number

(Optional) The cylinder at which the first partition begins. The value must be in the range 0–4294967294 (i.e., 2³² - 2) for MBR disks or 0–18446744073709551614 (i.e., 2⁶⁴ - 2) for GPT disks. The default is 0 (zero).

Note:

The first few sectors of the disk are always reserved for partition table metadata. For MBR disks, the first track is reserved (= sectors_per_track sectors); for GPT disks, 2 + ((num_partitions * 128 + sector_size - 1) / sector_size) sectors are reserved. The first partition begins at the next multiple of the alignment unit size.

You can declare primary, extended, and logical partitions using the following syntax (for the complete configuration file syntax, see Grammar):

...

primary_partn_def : '[' 'partition' '=' partn_idx ppartn_attr* ']' [partn_file]

extended_partn_def : '[' 'extended' '=' partn_idx epartn_attr* ']'

logical_partn_def : '[' 'logical' lpartn_attr* ']' [partn_file]

...

where:

partn_idx

A unique value in the range 1–4 for MBR disks or 1–number for GPT disks (where there are number partitions).

ppartn_attr, epartn_attr, lpartn_attr

The partition attributes that apply for primary, extended, and logical partitions, respectively. For details, see Grammar.

partn_file

The pathname of the file containing the filesystem image for the partition. The pathname must be enclosed in double quotes (""), and can't exceed the host's maximum pathname length. The file size must not exceed the partition size. For filesystems that are not Power-Safe filesystems, the image file can be smaller than the partition (although a warning is issued). If no pathname is specified, an empty partition is created. In this case, the num_sectors attribute must be specified.

The following partition attributes are supported by diskimage:

boot=true|false

(Optional) Specifies whether the partition should be marked as bootable. A boolean value is used, where true indicates that the partition is bootable and false indicates that it isn't. The default value is false.

type=number

(Required; MBR only) Specifies the partition type. The value must be in the range 1–255 and should match the type of the filesystem in the partition image file. Frequently used types include 11/12 (DOS FAT32) and 177/178/179 (Power-Safe filesystem). For more information about partitions and a list of partition IDs, refer to http://en.wikipedia.org/wiki/Partition_type.

type_guid=type_or_guid

(Required; GPT only) Specifies the GUID partition type. Either a short type name enclosed in double quotes (""), or a GUID enclosed in curly braces of the form {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}. For more information on GPT disks and GUID partition types, refer to Partition information and http://en.wikipedia.org/wiki/GUID_Partition_Table.

num_sectors=number

(Optional) Specifies the number of sectors to allocate for the partition. The value must be in the range 1–4294967295 (i.e., 2³² - 1) for MBR disks, or 1–18446744073709551615 (i.e., 2⁶⁴ - 1) for GPT disks. If this attribute isn't specified, it's set to the smallest number of sectors required for the partition’s filesystem image.

Note:

If no partition file is specified, num_sectors is required.

ebr_sectors=number

(Optional; MBR, logical partitions only) Specifies the number of sectors to be reserved in front of the logical partition. At least one sector is required for the EBR (Extended Boot Record) associated with the partition. The value must be in the range 1–4294967295 (i.e., 2³² - 1). If this attribute isn't specified, exactly one track is reserved. For more information, see the sectors_per_track disk attribute.

name=string

(Optional; GPT only) Specifies an arbitrary name for the partition. The name must be enclosed in double quotes ("") and be between 1 and 35 characters in length. If this attribute isn't specified, a default name of the form type.N is created, where type is the type_guid short name and N is a sequential number for this type. The string is expected to be UTF-8 encoded.

required=true|false

(Optional; GPT only) Specifies whether the "Required Partition" attribute bit is set for this GUID partition (true for set; false otherwise). For more information about partition attribute bits, refer to the UEFI specification 2.4B, 5.3.3, "GPT Partition Entry Array", Table 20.

noblock=true|false

(Optional; GPT only) Specifies whether the "No Block I/O Protocol" attribute bit is set for this GUID partition (true for set; false otherwise). For more information about partition attribute bits, refer to the UEFI specification 2.4B, 5.3.3, "GPT Partition Entry Array", Table 20.

The total combined size of all logical partitions (including any overhead) must be less than or equal to the size of the extended partition. When calculating the space required for the extended partition, be aware that each logical partition is preceeded by an Extended Boot Record (EBR), which is exactly one sector in size, and some optional padding sectors:

To illustrate this calculation, consider the following example, in which the specified partitions intentionally don't add up to fill the disk:

Target disk geometry

16 cylinders

32 heads

32 sectors per track

Partitions

One primary type 11 (DOS FAT32), bootable, 4096 sectors

One extended partition with:

• 1 logical type 179 (Power-Safe filesystem), 2048 sectors
• 1 logical type 178 (Power-Safe filesystem), 6144 sectors

To calculate the extended partition, use the following formula:

  <sectors_per_track>	/* First logical EBR  */
+ <logical-type-179>	 /* First logical data */
+ <sectors_per_track>	/* Second logical EBR  */
+ <logical-type-178>	 /* Second logical data */
= ext_sectors

For the example, these are the values to use in the formula:

    32    /* sectors_per_track */
+ 2048    /* First logical data */
+   32    /* sectors_per_track  */
+ 6144    /* Second logical data */
= 8256    /* size of extended partition sectors */

To define the configuration specified in the previous example, the configuration file would be:

[cylinders=16 heads=32 sectors_per_track=32]
[partition=1 boot=true  type= 11 num_sectors=4096] "fat.img"
[extended=2                      num_sectors=8256]
[logical     boot=false type=179 num_sectors=2048] "qnx-179.img"
[logical     boot=false type=178 num_sectors=6144] "qnx-178.img"

However, if you assume the three filesystem images are full-sized, you can use a simplified syntax by taking advantage of default behavior:

[cylinders=16 heads=32 sectors_per_track=32]
[partition=1 boot=true type=11] "fat.img"
[logical type=179] "qnx-179.img"
[logical type=178] "qnx-178.img"

For example:

[raw start_lba=1024 num_lba=16] "generated/ipl-foo"

The following is a sample configuration for a disk with three primary partitions—one DOS FAT32 filesystem and two Power-Safe filesystems—intended for a disk geometry of 974/255/63 (cylinders/heads/sectors). The configuration file expects the filesystem images to reside in the directory ../fsi.

[cylinders=974]
[heads=255]
[sectors_per_track=63]

# DOS FAT32
[partition=1
  boot=false
  type=11
  num_sectors=963837
] "../fsi/fat32.fsi"

# First Power-Safe filesystem, >2GB, bootable
[partition=2
  boot=true
  type=179
  num_sectors=4273290
] "../fsi/qnx6-1.fsi"

# Second Power-Safe filesystem
[partition=3
  boot=false
  type=178
  num_sectors=1060290
] "../fsi/qnx6-2.fsi"

The configuration below is for a disk with three primary and two logical partitions. The primary partitions are a DOS FAT32 filesystem and a Power-Safe filesystem, plus an empty partition reserved for another Power-Safe filesystem. Both logical partitions are Power-Safe filesystems. The extended partition uses slot 3 in the MBR. The resulting image is intended for a disk geometry of 4096/64/32 (cylinders/heads/sectors), which could represent an eMMC. The configuration file expects the filesystem images to reside in the directory ../fsi.

[cylinders=4096 heads=64 sectors_per_track=32]

# DOS FAT32 (~480MB)
[partition=1 type=11 num_sectors=963837] "../fsi/fat32.fsi"

# Primary Power-Safe filesystem, >2GB, bootable
[partition=2 boot=true type=179 num_sectors=4273290] "../fsi/qnx6-1.fsi"

[extended=3]

# Reserved for Power-Safe filesystem
[partition=4 type=178 num_sectors=65536]

# Power-Safe filesystem (~500MB)
[logical type=178 num_sectors=1060290] "../fsi/qnx6-2.fsi"

# Power-Safe filesystem (~500MB)
[logical type=177 num_sectors=1060290] "../fsi/qnx6-3.fsi"

This example is for a GPT disk with two partitions–one DOS FAT32 named "dos" and one Power-Safe filesystem named "qnx". This configuration is intended for a disk geometry of 65536/32/16 (cylinders/heads/sectors). Partitions are aligned to multiples of 1MB. Use the first and the last entry of the partition table. The configuration file expects the filesystem images to reside in the directory ../fsi.

[cylinders=64k heads=32 sectors_per_track=16]
# At 512 bytes/sector, 2k sectors give 1MB
[align=2k]
    
# DOS FAT32
[partition=1
  type_guid="ms"
  name="dos"
  num_sectors=2097108
] "../fsi/fat32.fsi"
   
# Power-Safe filesystem, bootable
[partition=128
  boot=true
  type_guid="qnx6"
  name="qnx"
  num_sectors=4273290
] "../fsi/qnx6.fsi"