diskimage configuration file

Description:

The diskimage utility requires a configuration file that specifies the disk image layout and content.

For the full grammar of the configuration file, see “Grammar.”

The diskimage utility also supports short type names for some GUID partitions.

Grammar

The contents of the diskimage configuration file must conform to the following grammar, which is defined using a BNF-like notation.

# Configuration file
config_file : disk_cfg* ( partn_def | raw_def )*

# Disk configuration
disk_cfg : '[' disk_attr+ ']'

# Disk attributes
disk_attr : 'cylinders' '=' uint
          | 'heads' '=' uint
          | 'sectors_per_track' '=' uint
          | 'sector_size' '=' uint
          | 'num_sectors' '=' uint
          | 'align' '=' uint
          | 'start_at_cylinder' '=' uint
            
# Partition definition            
partn_def : primary_partn_def
          | extended_partn_def
          | logical_partn_def
            
# Primary partition definition            
primary_partn_def : 
      '[' 'partition' '=' partn_idx ppartn_attr* ']'  [partn_file]

# Extended partition definition  
extended_partn_def : 
     '[' 'extended' '=' partn_idx epartn_attr* ']'

# Logical partition definition  
logical_partn_def : 
     '[' 'logical' lpartn_attr* ']'  [partn_file]
  
# Partition index  
partn_idx : uint

# The primary partition attributes  
ppartn_attr : boot_attr
            | type_attr
            | type_guid_attr
            | nsec_attr
            | name_attr
            | required_attr
            | noblock_attr

# The extended partition attributes  
epartn_attr : nsec_attr

# The logical partition attributes  
lpartn_attr : boot_attr
            | type_attr
            | nsec_attr
            | esec_attr

# The boot attribute
boot_attr : 'boot' '=' bool

# The type attribute
type_attr : 'type' '=' uint

# The type_guid attribute
type_guid_attr : 'type_guid' '=' type_guid_name
               | 'type_guid' '=' type_guid_guid

# The num_sectors attribute
nsec_attr : 'num_sectors' '=' uint

# The ebr_sectors attribute
esec_attr : 'ebr_sectors' '=' uint

# The name attribute
name_attr : 'name' '=' gpt_partn_name

# The 'required' attribute
required_attr : 'required' '=' bool

# The noblock attribute
noblock_attr : 'noblock' '=' bool

# Partition file
partn_file : string

# GUID name
type_guid_name : string

# GUID
type_guid_guid : guid

# The raw section definition
raw_def :
    '[' 'raw' start_lba_attr num_lba_attr']' raw_file

# The start_lba attribute
start_lba_attr : 'start_lba '=' number

# The num_lba attribute
    num_lba_attr : 'num_lba' '=' number

# The file_name attribute
    raw_file : '"'file_name'"'

# The boolean definition
bool : 'true'
     | 'false'

# Unsigned integer 
uint : '0' odigit* sfx?
     | '0x' xdigit+ sfx?
     | [1-9] ddigit* sfx?

# Octal digits
odigit : [0-7]

# Decimal digits
ddigit : [0-9]

# Hexadecimal digits
xdigit : [0-9a-fA-F]

# Factors that can be used with integers 
sfx : [kKmMgGtTpP]

# String values must be enclosed within double quotes ("")            
string : '"' [^"]* '"'

# A GUID
guid : 
'{' xdigit{8} '-' xdigit{4} '-' xdigit{4} '-' xdigit{4} '-' xdigit{12} '}'

Disk configuration

Unless the diskimage output goes to a disk device, you must specify a disk configuration in the configuration file. The disk configuration is made up of disk attributes, most of which describe the disk's geometry. All disk attribute definitions must be enclosed in square brackets ([]). A single pair of brackets can contain one or more attribute definitions; multiple attribute definitions within a pair of brackets must be separated by whitespace.

Disk attributes

Partition configuration

In the partition configuration, you can specify the following kinds of partitions: primary, extended, and logical. These partition definitions must comply with the following conditions:

• You can use the -G option to specify the number of primary partitions in a GPT disk. The minimum number is 128 (the default). GPT disks can't have any extended or logical partitions.
• An MBR disk can have up to four primary partitions or up to three primary and one extended partition, where the extended partition can contain any number of logical partitions.
• Any logical partitions on an MBR disk require the existence of an extended partition. When logical partitions are used, you're not required to explicitly specify the extended partition. Regardless of whether you do this, there can be only three primary partitions if you define logical partitions. If no extended partition is defined but logical partitions are defined, an extended partition is automatically created. You can't specify more than one extended partition in the configuration file.
• The extended partition must be explicitly defined when a specific partition index must be assigned to it or the required space exceeds the defined logical partitions. For information about calculating the size of the extended partition, see “Using extended and logical partitions.”
• The combined size of all logical partitions (including any overhead) should be equal to and must not exceed the size of the extended partition.

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.

Partition Attributes

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.

Using extended and logical partitions

If you want to use logical partitions, you must also define exactly one extended partition. It can be defined explicitly or created automatically by diskimage. The extended partition acts as a primary partition and serves as a container for the logical partitions. Within the extended partition, the logical partitions are laid out in the order in which they appear in the configuration file.

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:

Figure 1. Extended boot record, padding, and logical partition

By default, the ebr_sectors option is set to the disk's number of sectors per track (i.e., exactly one track). The ebr_sectors value includes the EBR as well as any padding sectors. We recommend that you use the default value of one track.

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"

Supported short type names for GUID partitions

The following tables list the GUID partition types for which diskimage has a defined short type name. You can use any of the listed types in a partition declaration by specifying the string in the “Type Name” column as the value of the type_guid partition attribute. For types not listed, you must specify the full GUID.

General

QNX

Windows

Apple (Mac OS X)

Ceph

ChromeOS

FreeBSD

Haiku

HP-UX

Linux

MidnightBSD

NetBSD

OpenBSD

Solaris

Raw data

The raw attribute can be used to copy data (e.g., IPLs) to areas on the disk that aren't covered by any partition.

Since raw data sections aren't part of any partition, they aren't included in the partition table. However, the diskimage utility makes sure that the defined raw sections don't overlap with any of the defined partitions or with any partition-table metadata.

The diskimage utility supports the following raw data attributes:

start_lba=number

The logical block address (LBA) of the raw data to be included in the disk image.

num_lba=number

The number of LBAs of raw data to be included in the disk image.

raw_file

The path and name of the file with the raw data to be added to the image.

For example:

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

Examples

Configuration file for three primary partitions

[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"

Configuration file for three primary and two logical partitions

[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"

Configuration file for a GPT disk with two partitions

[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"