Description:
The diskimage utility creates an image for a partitioned medium.
The partitioned medium image can contain any number of filesystem images. For
example, Power-Safe filesystems that were created using
mkqnx6fsimg or mkqnx6fs. After an image is
successfully created, it can be copied to a hard drive, SD, or MMC. Options are
available to adjust Power-Safe filesystems in the image so that they are bootable.
With this command, you can also specify the IPL file to write into the master boot
record (MBR).
You must use a configuration file to specify the disk image
content and layout. The configuration file consists of a description for the disk
and any number of optional descriptions about the partitions. There are three types
of partitions you can use: primary, extended, and logical. The following constraints
apply when you use
diskimage:
- The disk can have up to four primary partitions or up to three primary and
one extended partition. That extended partition can be used as a container
for any number of logical partitions.
- Any logical partitions on the 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.
- Filesystem images are copied to the disk image in blocks of up to 4096 bytes.
You can override this default setting using the -s option.
Overview of configuration file
syntax
The configuration file uses a specific structure, syntax, and grammar.
For an explanation of the configuration structure (or contents), see
"Configuration file structure".
For a full description of the grammar, see
"Summary of configuration file syntax".
The configuration file can have these special characters:
- Whitespaces used in double quotes ("") of
a string literal are interpreted as part of that string. Whitespaces
aren't allowed within numeric literals (including the suffix).
- Line breaks and spaces can occur anywhere, except in literals or tokens.
- 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
(10242)
- g or G to represent giga
(10243)
Configuration file
structure
The configuration file structure has two parts:
- disk configuration― (Required) 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.
The disk configuration is required in each configuration file. The configuration file
defines a number of disk attributes that mainly 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 a whitespace.
Disk attributes
The
diskimage command supports the following disk attributes:
- cylinders=number
- (Required) Specifies the number of cylinders on the disk. The value must be
in the range of 1–4294967295 (232-1).
- heads=number
- (Required) Specifies the number of heads on the disk. The value must be
in the range of 1–255.
- sectors_per_track=number
- (Required) Specifies the number of sectors on each track. The value must
be in the range of 1–63.
- sector_size=number
- (Optional) Specifies the number of bytes per sector. The value must be
in the range of 1–4294967295 (232-1). If not specified,
a default value of 512 is used.
- start_at_cylinder=number
- (Optional) Specifies the cylinder at which the first partition shall
begin. The value must be in the range of
0–4294967294 (232-2). The default is zero.
Note:
The first track is always reserved for the MBR. Because of this, a
partition beginning at cylinder zero has
sectors_per_track
x (heads-1) sectors available in the
first cylinder.
The partition definitions are optional and you can specify as many as
you require. You can define primary, extended, and logical partitions using the
following syntax where:
- partn_idx
- A unique value in the range of 1–4.
- 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).
- Primary
partition:
[partition=partn_idx boot=true|false
type=number
num_sectors=number] partn_file
Example:
# Power-Safe filesystem, > 2GB, bootable
[partition=2 boot=true type=179 num_sectors=4273290] "../fsi/qnx6-1.fsi"
- Extended
partition:
[extended=partn_idx num_sectors=number]
Example:
[extended=2 num_sectors=8256]
- Logical
partitions:
[logical type=number
num_sectors=number
ebr_sectors=number] partn_file
Example:
# Power-Safe filesystem (~500MB)
[logical type=178 num_sectors=1060290] "../fsi/qnx6-2.fsi"
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) Specifies the partition type. The value must be in the range
of one to 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.
- num_sectors=number
- (Optional) Specifies the number of sectors to allocate for the
partition. The value must be in the range of 1–4294967295
(232-1). If this attribute isn't specified, it's set to
the smallest number of sectors required for the partition’s filesystem
image.
- ebr_sectors=number
- (Optional) 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 of 1–4294967295 (232-1). If this attribute
isn't specified, exactly one track is reserved. For more information,
see the sectors_per_track disk attribute.
Using extended and logical
partitions
When logical partitions are used, an extended partition is
required as well. 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 config
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. To
determine the space required for the extended partition, include the following items
in your calculation:
- the size of each logical partition
- each logical partition's ebr_sectors
By default, the
ebr_sectors option is set to the disk's number
of sectors per track. The size of the
ebr_sectors option includes
the EBR and any optional padding. It's recommended that the default of one track is
used.
Attention: Even though the EBR requires one sector, the entire
track is allocated for it.
Figure 1. Extended boot record, padding, and logical partition
To illustrate the calculation, consider the following
example:
Note: In the following example, 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
Therefore, 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 wanted to presume that the three filesystem images are
full-sized, you can use a more simplified syntax:
[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"
Summary of configuration file syntax
The following excerpt explains the configuration file grammar:
# Configuration file
config_file : disk_cfg+ partn_def*
# Disk configuration
disk_cfg : '[' disk_attr+ ']'
# Disk attributes
disk_attr : 'cylinders' '=' uint
| 'heads' '=' uint
| 'sectors_per_track' '=' uint
| 'sector_size' '=' 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
| nsec_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 num_sectors attribute
nsec_attr : 'num_sectors' '=' uint
# The ebr_sectors attribute
esec_attr : 'ebr_sectors' '=' uint
# Partition file
partn_file : string
# The boolean definition
bool : 'true'
| 'false'
# Unsigned integer
uint : '0' [0-7]+ sfx?
| '0x' [0-9a-fA-F]+ sfx?
| [1-9][0-9]* sfx?
# Factors that can be used to with integers.
sfx : [kKmMgG]
# string values must be enclosed within double quotes ("")
string : '"' [^"]* '"'
Examples:
Create an imagediskimage –c mydisk.cfg –o mydisk.img
Create an image and specify a primary boot loader (IPL)
diskimage -c mydisk.cfg
-b C:\qnx660\target\qnx6\x86\boot\sys\ipl-diskpc1
-o mydiskipl.img
Configuration file for three primary partitions
An example for a disk with three primary partitions, one DOS FAT32 and two Power-Safe
filesystems. It's targeted at 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"
Configuration file for two primary and two logical partitions
An example for a disk with two primary and two logical partitions. The primary
partitions are DOS FAT32 and Power-Safe filesystems. 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 can
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]
# 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"