Operating systems, development tools, and professional
services for connected embedded systems
日本語中文Deutsch한국어
CONNECT WITH US
Home
Developer Resources
Developer Support
Developer Resources
Blogs
Board support packages
Foundry27 projects
Forums
Hardware support listing
Online video tutorials
Product documentation

QNX Developer Support

PDF Documents
More resources
[Previous] [Contents] [Index] [Next]

mkifs

Build an OS image filesystem (QNX)

Syntax:

mkifs [-l inputline] [-n[n]] [-r rootdir] [-v]
      [buildfile [imagefile]]

Options:

-l inputline
("el") Process inputline before interpretation of the buildfile begins. Input lines given to mkifs must be quoted to prevent interpretation by the shell (especially since mkifs input lines often contain spaces). Multiple -l options are processed in the order specified. No default.
-n[n]
Force the modification times of all inline files to be 0. If you specify -nn, mkifs sets the modification times of all files to 0.

When mkifs adds files to an IFS image, it uses the timestamp information from the file on the host machine. If mkifs is creating an inline file (which doesn't exist on the host machine), it has to generate its own timestamp information. By default, it's the time that the image is generated.

This results in different checksum values for two identical builds (because the file's creation or modification times are different). If you use -n, the checksum value is the same on all identical builds.

The -nn option addresses a quirk in the NTFS filesystem relating to Daylight Savings Time. This option forces the modification time for all files in the IFS image to be set to 0. This ensures that subsequent builds of the same IFS image have the same checksum.

-r rootdir
Search the default paths in the rootdir directory before searching them in the default location. Normally, mkifs searches the default paths in the sequence shown in MKIFS_PATH below. If you specify the -r option, mkifs first searches the same paths prefixed with the rootdir variable instead of ${QNX_TARGET}, like this:
  1. rootdir/${PROCESSOR}/sbin
  2. all other default paths, similarly prefixed with rootdir
  3. ${QNX_TARGET}/${PROCESSOR}/sbin
  4. all other normal default paths prefixed with ${QNX_TARGET}

The structure of the directory paths under rootdir must be identical to that of the default paths under ${QNX_TARGET}, but rootdir itself may be any path you choose. For example, if you wanted to include this file:

/dev/ppcbe/sbin/pci-ppc405

you would specify the option like this:

-r /dev
Notice that you don't include ${PROCESSOR} in rootdir.
Note: If you set MKIFS_PATH, mkifs ignores the -r option.
-v
Operate verbosely. Specifying additional -v options increases verbosity. Default is quiet operation.

Description:

The mkifs utility is used to create an OS image filesystem from a buildfile specification.

Note: Currently, you can use mkifs to create only bootable images.

Don't confuse this command with mkefs, which builds an embedded filesystem, or mketfs, which builds an embedded transaction filesystem (ETFS).

The files are specified on the command line:

buildfile
The input buildfile that mkifs should construct an image from; use - to specify standard input (the default).
imagefile
The file to contain the image that mkifs builds; use - to specify standard output (the default). Note that you can specify the imagefile only if you've specified the buildfile.

Buildfiles

The buildfile uses the same grammar as the mkefs command, but supports different attributes.

The buildfile specifies a list of files of various types; these files are placed by mkifs into the output image. As well as the files to be included, you can specify various attributes that are used to set parameters of the files or the image as a whole.

Note: You can't use a backslash (\) to break long lines into smaller pieces.

In a buildfile, a pound sign (#) indicates a comment; anything between it and the end of the line is ignored. There must be a space between a buildfile command and the pound sign.

Each line is in the form: 

[attributes] file_specification

where the attributes (with the enclosing square brackets) and the file specification are both optional.

You can use an attribute in two ways:

Attributes are enclosed in square brackets; when combining attributes (e.g. to specify both the user ID and the group ID), enclose both attribute tokens in the same pair of square brackets. For example: 

# correct way
[uid=5 gid=5] filename

# incorrect way
[uid=5] [gid=5] filename

There are two types of attributes:

boolean attributes
Those prefixed with a plus ("+") or minus ("-") sign.
value attributes
Those ending with an equals sign ("=") followed by a value. Don't put any spaces around the equals sign.

A question mark (?) before an attribute makes the setting conditional. The attribute is set only if it hasn't already been set. For example, ?+bigendian sets the +bigendian attribute only if +bigendian or -bigendian hasn't already been set.

The file_specification takes one of the following forms:

path
The path is the same on the host as in the image.
target_path=host_path
The specified file or contents of the specified directory are fetched from the host filesystem and placed into the image.
target_path={contents}
An inline definition. The contents of the file are listed within the buildfile itself, enclosed in braces ({ }) -- the file doesn't exist on the host system anywhere. The contents of the inline file can't be on the same line as the opening or closing brace.
Note: The mkifs utility doesn't parse the contents of an inline file for anything but the closing brace. For example, mkifs doesn't interpret a pound sign (#) in an inline file as the beginning of a comment. The syntax of the inline file depends on what it's used for on the target system.

Closing braces (}) and backslashes (\) in an inline file must be escaped with a backslash.

Either class of file may be preceded by zero or more attributes. These attributes are used to specify the characteristics of the file (e.g. user ID that the file should be owned by on the target system, type of file, etc.)

Note: By default, mkifs strips usage messages, debugging information, and Photon resources from executable files that you include in the image. Doing this helps to reduce the size of the image. To keep this information, specify the +raw attribute.

You can enclose a filename in double quotes ("") if it includes spaces or unusual characters.

Attributes

The mkifs command supports the following attributes:

An OR-bar indicates that either the first or second element must be present, but not both (e.g. +|- bigendian means either +bigendian or -bigendian, but not +-bigendian).

autolink attribute (boolean)

+|-autolink

If the autolink attribute is on (which it is by default), when mkifs detects that it's processing a shared object, it looks inside the image for the SONAME (specified by the linker -h option). This is typically the shared object name, including the version number (e.g. libc.so.1). The mkifs command puts the file into the image filesystem under the name with the version number; the name without is made into a symbolic link to the file. For example, specifying: 

libc.so

in the buildfile makes libc.so.1 the name of the file and libc.so a symlink to it. Specifying: 

libc.so.1

in the buildfile gives the same results. You end up with the name with and without the version number in the image filesystem no matter which one you specify in the buildfile.

If the name that would be used as the symbolic link is already specified somewhere else in the buildfile, the symbolic link isn't created. For example: 

libc.so.1
libc.so.2
[type=link] libc.so=libc.so.2

ensures that libc.so is pointing at the "proper" version of the library.

You can disable this feature by specifying the -autolink attribute.

bigendian attribute (boolean)

+|-bigendian

Set the byte order for the image file system to either big (via +bigendian) or little (via -bigendian) endian. This option doesn't normally need to be specified when building a bootable image, since the bootfile provides the required byte order. If a bootable file system isn't being built, or the bootfile doesn't say which byte order to use, the host system byte order is used in building the image file system.

cd attribute

cd=path

Set the current working directory to the specified pathname before attempting to open the host file. Default is the directory from which mkifs was invoked.

chain attribute

chain=addr

Set the address at which the operating system will find the next image filesystem. Default is none.

code attribute

code=uip_spec

Set whether the code segment of an executable is used directly from the image file system (uip or u) or copied (copy or c) when invoked. The default is to use the code segment in place (uip). For more information, see "Notes on XIP versus copy," below.

compress attribute (boolean)

+|-compress

Set whether the image is compressed. Default is false.

data attribute

data=uip_spec

Set whether the data segment of an executable is used directly from the image filesystem (uip or u) or copied (copy or c) when invoked. The default is to use the data segment in place (uip). For more information, see "Notes on XIP versus copy," below.

dperms attribute

dperms=perm_spec

Set the access permissions of the directory. See the perms attribute for more information.

filter attribute

filter=filter_spec

Run the host file through the filter program specified, presenting the host file data as standard input to the program, and use the standard output from the program as the data to be placed into the image file system. Default is no filter.

To illustrate the use of a filter, consider storing a compressed file in the image filesystem, where the file exists in its uncompressed form on the host filesystem: 

[filter="compress"] data.Z = data

This runs compress from a shell, passing it the contents of data as standard input. The compress command runs and generates the compressed version of its standard input on its standard output. The standard output is then placed into the image filesystem as the data.Z file.

followlink attribute (boolean)

[+|-followlink]target_path=host_path

If you specify +followlink or omit it, mkifs follows any links and makes target_path a copy of host_path.

If you specify -followlink, mkifs creates a link called target_path that points to whatever host_path points at. It's up to you to make sure that the file pointed to is placed in the image.

gid attribute

gid=id_spec

Set the group ID number for the file. The value of this attribute may be either a number or an asterisk (*). If it's an asterisk, the group ID is taken from the host file; for an inline file, the group ID is the group of the user running mkifs. The default value for this attribute is *.

image attribute

image=addr_space_spec

Set the base and size limits for the image file system. The format for this attribute consists of an optional starting address, followed by zero or more address space sizing parameters.

The starting address is the base address of the image, and matters only when building a bootable image. Its default depends on the bootfile selected. For example, on an x86 using the bios.boot file, the image address begins at 4M.

-end_addr
A dash followed by a number represents an ending address, the last allowable address in the image. If the output image exceeds this address, an error is reported. The default is no limit.
,maxsize
A comma followed by a number represents the maximum allowed size of the image. If the output image becomes larger than this value, an error is reported. The default is no limit. The maximum image size depends on your configuration; for example, it may be limited on an x86 system with a BIOS.
=totalsize
An equals sign followed by a number represents the total size that the output image is padded out to. The default is no padding.
%align
A percent sign followed by a number represents the alignment value used for the image. The output image size is padded out to a multiple of this value. The default is 4.
Note: If you don't specify the ram attribute, the image is assumed to be in RAM. For more information, see "Notes on XIP versus copy," below.

keeplinked attribute (boolean)

+|-keeplinked

If true, and mkifs has to run a linker to position the executable within the image file system, the output file from the link is the basename of the host path with .sym appended. For example, if the host name is ../foo/bar, the output name is bar.sym. If false, a generated temporary name is used for the output file and it's deleted after mkifs has run. The default is false.

linker attribute

linker=(linker_id_spec)linker_spec

When building a bootable image, mkifs sometimes needs to run a linker on relocatable objects to position them within the image. This option lets you specify printf-like macro expansions to tell mkifs how to generate the linker command line (see "Linker Specification," below for details).

This option doesn't normally need to be specified, since mkifs or a bootfile provides a default. Different linkers can be used for different types of ELF files.

The attribute value consists of an optional linker ID specification and a linker specification. The linker ID specification, if present, consists of:

  1. An opening parenthesis, (.
  2. A list of comma-separated numbers giving the allowable ELF machine numbers (EM_* constants from the include file <sys/elf.h>) for the linker specification. The list of machine numbers is terminated by a semi-colon.
  3. A list of comma-separated numbers, giving the list of acceptable ELF file types (ET_* constants, from <sys/elf.h>). This list is also terminated by a semi-colon.
  4. A comma-separated list of numbers giving ELF program segment types (PT_* constants, also from <sys/elf.h>).
  5. A closing parenthesis, ).

If the ID specification is present, the linker specification is used only if the machine number of the ELF input file matches one of the given numbers, and the ELF file type of input file matches one of the given numbers and at least one of the program segment types in the input file matches one of the given numbers:

module attribute

Use this attribute to add optional modules to procnto.

For example, in order to use the adaptive partitioning scheduler, you must rebuild your OS images with the option [module=aps] added to the PATH= statement of your buildfile: 

[module=aps] PATH=/proc/boot ./procnto -vv

You can now create a partition and launch applications within a particular partition for the adaptive partitioning scheduler.

For information on creating a partition, see "Creating partitions" in the Setting Up and Using the Adaptive Partitioning Scheduler chapter of the Adaptive Partitioning TDK User's Guide.

For information on launching applications within a particular partition, see "Launch processes in partitions" in the Setting Up and Using the Adaptive Partitioning Scheduler chapter of the Adaptive Partitioning TDK User's Guide.

Note: This attribute was added in the QNX Neutrino Core OS 6.3.2.

optional attribute (boolean)

+|-optional

If true, and the host file can't be found, output a warning and continue building the image file system. If false, and the host file can't be found, output an error message and exit mkifs. The default is true. This attribute can't be set to true for bootstrap executables (see the virtual attribute for more information).

perms attribute

perms=perm_spec

Set the access permissions of the file. If specified as a number, the permissions are set to that number (just like the chmod command). If specified as an asterisk ("*"), the host file's permissions are used; for an inline file, permissions of 0666 are used. Otherwise, a symbolic mode string (which is a subset of chmod's) is used to delete, add, or set permissions.

The symbolic mode string consists of:

  1. a combination of u, g, o, and a
  2. one of -, =, or +
  3. a combination of r, w, x, s, g, and t.

You can include more than one symbolic mode string, separating them with a comma (,).

The default is *.

Note: When running on a Windows host, mkifs cannot get the execute (x) permissions from the file. Specify the permissions of executable files using the perms attribute.

physical attribute

physical=cpu_name,boot_filename filter_args

This attribute indicates that a bootable file system is being built. It may be specified only once in a control file. The image will be run in physical memory mode.

Note: The physical attribute isn't currently implemented; use virtual.

For more information, see the virtual attribute.

prefix attribute

prefix=prefix_spec

Set the prefix for the target file names. Default is proc/boot when building a bootable image, and the empty string when not.

ram attribute

ram=addr_space_spec

Set base and size limits for the read-write memory required by executables in the image file system. This attribute consists of an optional starting address, followed by zero or more address space sizing parameters.

You need to specify this attribute if the actual image is going to be stored on a read-only device such as ROM or flash memory. Use the image attribute to specify the location.

The starting address specifies the base address of the RAM, and matters only when building a bootable image. The default is dependent on whatever bootfile is selected.

-end_addr
A dash followed by a number represents an ending address, the last allowable address for RAM. If the RAM usage exceeds this address, an error is reported. The default is no limit.
,maxsize
A comma followed by a number represents the maximum allowed size of the RAM. If the output image requires more RAM than this value, an error is reported. The default is no limit. The maximum RAM size depends on your configuration.
=totalsize
An equals sign followed by a number represents the total size that the RAM usage is padded out to. The default is no padding.
%align
A percent sign followed by a number represents the alignment value used for the RAM. The RAM size is padded out to a multiple of this value. The default is 4.

For information about how everything interacts, see "Notes on XIP versus copy," below.

raw attribute (boolean)

+|-raw

If the raw attribute is false (the default), mkifs strips usage messages, debugging information, and Photon resources from executable files.

If you specify +raw for a file, the file is treated as a data file, even if it would normally be treated as an executable and relocated.

Note: Don't specify the +raw attribute for shared objects; it prevents them from being shared.

If you use the default attribute (-raw) and you specify that the data segment is to be used in place, the file's sticky bit will not be set. This identifies the executable to the QNX process manager, which will prevent the program from running more than once, avoiding the possibility of running a program with corrupted static data.

Here's a fragment from a build file that demonstrates the use and scope of the raw attribute: 

...

[+raw]            # Don't strip usage, debugging or
othello           # Photon resources from binaries

[-raw] esh        # Only esh is affected
pwm               # Still affected by +raw flag
pfm

[-raw]            # Turn off +raw, since shared objects
libphrender.so    # can't be shared if +raw is enabled
libph.so

[+raw] my_ph_app  # We want Photon resources for this
                  # file only.  The -raw flag is
                  # still in effect for other files.
libc.so           # Still affected by -raw flag
...

Note: If you use Windows tools to build your image, files specified as +raw will not have executable permission when the image is booted. This is because the win32 file system cannot set a file's executable bit. To make such files executable, specify perms=+x when using +raw in the build file.

script attribute (boolean)

+|-script

If true, the host file is opened and processed as a script file after the process manager has initialized itself. Each line is parsed as a command line to be run. If multiple files are marked with +script, they're merged sequentially into a single file in the image file system; the file's name is the first script filename in the buildfile. The filenames for the subsequent script files are ignored, but they must be unique. See "Script Files," below for more details on the command line syntax.

search attribute

search=filename:filename:...

This attribute specifies that mkifs should search for the file in the named locations on the host system. The search directory portion of the host file name isn't included in the name that's stored in the image file system. The default is the contents of the MKIFS_PATH environment variable.

Note: Colon separators and forward slashes in the paths are the standard UNIX conventions, but for Windows searches, you must use the standard Windows conventions such as semicolon separators and backslashes in the paths.

type attribute

type=file_type

Set the type of the files being created in the image filesystem. Allowable types are:

Note: Specifying [type=dir] tells mkifs to create a directory on the target system; you don't need to specify the type when you're copying the contents of a directory. For example, to copy /usr/nto/x86/bin to /usr/bin, you a just need to specify: 
/usr/bin=/usr/nto/x86/bin

uid attribute

uid=id_spec

Set the user ID number for the file. The value of this attribute may be either a number or an asterisk (*). If it's an asterisk, the user ID is taken from the host file; for an inline file, the user ID is the user running mkifs. The default value for this attribute is *.

virtual attribute

virtual=cpu_name,bootfile_name filter_args

This attribute specifies that a virtual address system is being built.

If there's a comma (,) in the value, the string in front of it is taken to be the CPU type of the target system. If no CPU type is specified, the host system CPU type is used. The PROCESSOR environment variable is set to that string (this affects the MKIFS_PATH search path for host files).

The characters after the comma (or the equal sign for the attribute if there's no comma) up to the first blank character are taken to be the name of the bootfile. The suffix .boot is appended to the given name and MKIFS_PATH is searched for the file. You can find default bootfiles in ${QNX_TARGET}/${PROCESSOR}/boot/sys. For more details on the contents of the file, see "Bootfile," below.

Any characters in the attribute value following a blank are used as arguments to any image filter command specified by the bootfile, like this: 

[virtual="x86,srec -b"] boot = {
Note: If the value of the virtual attribute includes a space, put quotation marks around the string.

Startup code can't decompress in place. In other words, the address where the compressed version of the image is located has to be different from where the image is while running.

The contents of the host file that this attribute applies to are parsed to discover the bootstrap executables used to bring up the system. Each line identifies one bootstrap executable:

Script files

As mentioned above, by specifying the [+script] attribute, you're telling mkifs that the specified file is a script file, a sequence of commands that should be executed when the process manager has completed its startup.

Note: In order to run a command, its executable must be available when the script is executed. You can add the executable to the image, or get it from a filesystem that's started before the executable is required. The latter approach results in a smaller image.

Script files, for the most part, look just like regular shell scripts, except that:

The script file consists of one or more lines, with each line having the following syntax: 

[modifiers] [command_line [&]]

The modifiers consist of a list, enclosed in square brackets, of blank-separated items that modify how QNX Neutrino runs the specified command_line. If there's a command line following the modifiers, the modifiers affect only that one command line. If there's no command line, the modifiers affect all subsequent command lines.

If you specify an ampersand (&) after the command line, the program runs in the background, and Neutrino doesn't wait for the program to finish before continuing with the next line in the script. If you don't specify the ampersand, and the program doesn't exit, then the rest of the script is never executed.

The modifiers are described below. Those marked as "boolean" accept a plus (+) or minus (-) character to enable or disable the effect; the others accept a parameter.

argv0 modifier

Sets the argv[0] element of the command argument entry. By default, this is the same as the command name. This option is typically used to simulate invoking a command via a different name; the classical example is the compress command, which can be invoked as uncompress: 

[argv0=uncompress] compress filename.Z

external modifier (boolean)

Ordinarily, mkifs recognizes certain commands as internal commands, ones that aren't loaded from the host's filesystem, but are understood directly by mkifs. These commands are:

display_msg message
Causes the message immediately following the display_msg command to be output. This is useful during startup diagnostics; often used as a checkpoint.
procmgr_symlink
Equivalent to ln -P, except that you don't need to have ln present.
reopen [filename]
Causes standard input, standard output, and standard error to be redirected to the specified filename. Also causes the interpretation of the script file to suspend temporarily until a stat() on the specified pathname succeeds. The default filename is /dev/console.
waitfor pathname [wait_time]
Causes interpretation of the script file to suspend temporarily until a stat() on the specified pathname succeeds. Often used for synchronization, to allow a resource manager to perform its startup functionality, and then for the process manager to proceed with the further interpretation of the script file.

The optional wait_time specifies the maximum number of seconds to wait for the file to appear. It can include one decimal digit to specify tenths of a second. The default is 5.0 seconds.

The +external modifier instructs mkifs to search for the specified command on the host filesystem, rather than assume the internal meaning for the command. The default is -external.

Note: Using +external is a dubious practice. Specifying an external modifier on a command that isn't an internal command is redundant.

pri modifier

Lets you specify the command's priority and optionally the scheduling algorithm. The pri modifier accepts a numeric priority optionally followed by one of the letters:

f
FIFO scheduling algorithm.
r
Round-robin scheduling algorithm.
o
Other scheduling algorithm (currently maps to round-robin).

See the System Architecture guide for a description of the various priority levels and scheduling algorithms.

For example, to start up the console driver, devc-con at priority 20, with FIFO scheduling: 

[pri=20f] devc-con -n9 &

The default for this modifier is the same as the default used by procnto.

session modifier (boolean)

If +session is specified, make the process a session leader (as per POSIX), and make the process's stdin the controlling terminal (i.e. direct Ctrl-C at this process group). If -session is specified, don't make the process a session leader. The default is -session.

This parameter is typically used for the shell: 

[+session] esh

Bootfile

When building a bootable file system, a bootfile must be specified via the physical or virtual attributes. Note that the bootfile must be the first file specification within the buildfile. If the first character of the bootfile is an left square bracket ([), a list of configuration attributes is given in the same syntax as the buildfile. The list of attributes is terminated by a right square bracket (]). The allowed attributes, and their formats, are:

attr=image_attribute
The image_attribute is an attribute that's prefixed to the start of the control file. These attributes are processed even before the -l (lowercase L) command line options, so that the latter may be overridden.
default_image=addr_space_spec
Set the defaults for the image file attribute (see above).
default_ram=addr_space_spec
Set the defaults for the ram file attribute (see above).
filter=image_filter_spec
After the image has been created, run image_filter_spec. The following formatting codes are expanded:
  • %i -- the name of the output image file.
  • %I (uppercase i) -- the name of the input file (see below).
  • %s -- the offset of the startup header in the image file, in hex with a leading 0x.
  • %a -- any arguments from the physical or virtual attribute.

See "Image filter," below for an example of using the image_filter_spec.

len=boot_length
The boot_length parameter gives the amount of space to leave at the front of the image file (before the actual image file system) for system header information or boot prefix code. This is the minimum amount of space to reserve. If the boot prefix code following the bootfile attributes is larger than the number given here, the size of the boot prefix code is used instead. The default is zero.
notloaded=length
In some systems (such as IBM OpenBIOS), the system header information isn't loaded into memory and doesn't contribute to the memory offsets where things are placed (the base address of the image being set by the image attribute in the control file). This attribute specifies the size of the information that isn't going to be loaded into memory. The default is zero.
paddr_bias=number
On some CPUs (such as MIPS), the hardware reserves a range of virtual addresses that map one-to-one with physical address. This attribute lets mkifs know how to translate a virtual address to its physical location in memory via the formula: 
    phys_addr = virt_addr + number

The default is zero.

pagesize=size
Set the size of a page in the image file system. The mkifs utility aligns various structures to a multiple of this. The default is 4K.
vboot=addr
When building a virtual system, the paging hardware is sometimes turned on by the startup code (e.g. x86 architecture), as opposed to procnto (e.g. MIPS architecture). In the first case, this option tells mkifs what base virtual address should be used for the bootstrap executables. This option has no effect when building a physical system. The default is none.

Following the closing square bracket character (]) of the bootfile attributes, mkifs searches for the string boot. If it's found, mkifs considers all data immediately following, through to the end of the file, to be boot prefix code. This data is placed at the start of the image file. If the len attribute was specified and is larger than the size of the boot prefix code, the image file is padded out to the size given.

Image filter

You can specify an image filter within the specification for the bootfile, and optionally specify macro expansions to it. These macro expansions are documented above, in the filter description.

The following image filters are currently available:

mkifsf_elf
Wrap the entire image in an ELF section.
mkifsf_openbios
Patch the header at the beginning of the image for IBM's OpenBIOS.
mkifsf_srec
Convert the image into S-Record format. This filter accepts the following options:
  • -b -- generate only 4-byte address records.
  • -c -- omit the carriage-return character at the ends of lines.
  • -l -- omit the linefeed character at the ends of lines.

Generally, image filters are expected to take the file specified by the %i variable and modify it in place. If this isn't possible (e.g. the file changes size as a result of the filter program), specifying %I causes mkifs to store the original file in a temporary filename (named by %I), and expect the modified file in the filename given by %i. This happens only when the %I macro expansion is specified.

Linker specification

The linker specification lets you control how the linker command line is built when mkifs needs to turn a relocatable object into an executable running at a particular address. It operates much like a printf() format string, with characters being copied from the format to the command line until a percent character (%) is found. The following formatting codes after a percent character are supported:

%h
The address the executable header should be placed at, in hexadecimal.
%t
The address the text segment should be placed at, in hexadecimal. This is %h plus the amount of space for the executable header structures.
%d
The address the data segment should be placed at, in hexadecimal. This value may be zero, in which case the data should be placed immediately following the text segment.
%o
The name of the output executable file, as a string.
%i
The name of the input relocatable file, as a string.
%(
Open a conditional section. Following the opening parenthesis, (, are: a single character indicating the variable that the section is conditional on; one of the usual conditional operators from the C language; a constant; and finally a comma.

The contents of the variable are compared against the constant and if the result is true, the text following the comma is included in the command string being built. If the comparison is false, the contents of the string following the comma are omitted.

The conditional is terminated by percent character followed by a closing parenthesis, %). Conditionals can nest. The variables that can be tested are:

Variable: Value:
e 0 == little endian
1 == big endian
d Data segment address
f 0 == startup file
1 == bootstrap file
2 == normal file
h Executable header address
m Machine number from the ELF header
v 0 == file linked physically
1 == file linked virtually
V 0 == physical system
1 == virtual system
%)
Terminate a conditional section.

Here's the default linker command specification for mkifs: 

static const char default_linker[] = {
    "(;1;)gcc --no-keep-memory -nostdlib -nostartfiles -nodefaultlibs" 
    " -bnto%(m==3,x86%)%(m==6,x86%)%(m==8,mips%)%(m==20,ppc%)" 
    "%(e==0, -EL%)%(e==1, -EB%)" 
    "%(h!=0, -Ttext 0x%t%)%(d!=0, -Tdata 0x%d%)" 
    " -o%o %i" 
};

For the meaning of the parameters specified, see gcc.

Output image format

The image created by mkifs has the following layout:

Image layout

Although it isn't necessary to have a detailed understanding of the format of an image to make one, a general understanding is worthwhile.

Boot prefix

The first section (called the boot prefix) is controlled by the filename in the virtual= or physical= attribute. For many systems this section doesn't occupy any space in the image. When it's present, it's typically used to address one of the following issues:

Startup header

This section contains information about the image, which is used by our IPL and startup programs.

Part of this section is written to by mkifs. Another part is set to zero, and is written to by the IPL code to pass data (determined at runtime) to startup. The data is in the form of a set of structures (for more information, see Customizing IPL Programs in Building Embedded Systems).

If an image isn't bootable, this section is omitted.

Startup

This section contains the code and data for the startup program. This code must be executed in RAM. If the image is in ROM/FLASH, our standard IPL code uses information in the startup header to always copy the startup into RAM and transfer control to it there.

If an image isn't bootable, this section is omitted.

Startup trailer

A checksum for use by startup. If an image isn't bootable, this section is omitted.

Image header

Information on the image filesystem that follows.

Image directory

A series of directory entries for each file in the image filesystem.

Files

The files within the image filesystem. Executables that are executed in place are aligned on page boundaries. An attempt is made to fill any holes created by this alignment with small data files that have no alignment needs.

Image trailer

A checksum for the image.

Notes on XIP versus copy

The code=copy|uip and data=copy|uip attributes may be applied to executables in the image.

Note: Shared objects currently assume code=uip and data=copy. To get the effect of code=copy, manually copy the shared object to /dev/shmem and set LD_LIBRARY_PATH as appropriate. To save ROM/Flash space, compress the shared object in the image filesystem and decompress it into /dev/shmem.

When an executable is run, these attributes determine whether the code or data for that executable is to be used in place or copied to RAM. An image filesystem may exist in either RAM or linearly addressable ROM/FLASH. Images in RAM are usually loaded from a device that isn't linearly addressable. This includes disk boots, network boots, and boots from bank switched ROM/FLASH devices. It also includes any image that's been compressed.

For example, a compressed image may reside in linearly addressable flash, but it can't be used until it's decompressed into RAM. The following combinations exist for any image in RAM:

Code Data Comments
uip uip Run once (default)
uip copy Run multiple
copy uip Run once but wasteful
copy copy Run multiple but wasteful

The default assumes that you want to run both code and data in place. This would be fine for an executable that has a large amount of static data and that you need to run only once (e.g. a resource manager or driver that starts when the system boots). Running data in place modifies the only copy of the data as the program runs, so you can't start the program again.

Note: In this case, the file's sticky bit will not be set. This identifies the executable to the QNX Neutrino process manager which will prevent the program running more than once, so avoiding the possibility of running a program with corrupted static data.

That's why you have to specify data=copy if you want to run the executable multiple times.

The two cases listed as "wasteful" fall out of the combinations but they provide no additional capabilities and waste memory by copying the code unnecessarily. Since the code is read-only and can't be modified, it can always be used in place.

If you are creating an image in ROM/FLASH, the following combinations exist:

Code Data Comments
uip uip Run once
uip copy Run multiple (default)
copy uip Run once
copy copy Run multiple (slow ROM/FLASH)
Note: You have to specify both image and ram file attributes if you want to create the image in ROM/FLASH, otherwise the process manager assumes that the image is in RAM. The data=copy attribute is assumed for an image in ROM/Flash.

The cases where code is copied may seem wasteful (as in the RAM image example) but it may make sense for systems where the ROM/FLASH is slow -- perhaps it has an 8-bit interface or requires extra wait states for access to it. In that case, you may wish to copy it to RAM, so that it executes faster.

Examples:

Here's a very simple buildfile that specifies the operating system, a console driver, and a shell: 

[virtual=x86,bios] .bootstrap = {
    startup-bios
    PATH=/proc/boot procnto
}

[+script] .script = {
    devc-con -n9 &
    reopen /dev/con1
    [+session] esh
}
libc.so
[data=copy]
devc-con
esh
[type=link] /usr/lib/ldqnx.so.2=/proc/boot/libc.so
Note: The runtime linker is expected to be found in a file called ldqnx.so.2, but the runtime linker is currently contained within the libc.so file, so we make a process-manager symbolic link to it.

You can now build an image from the above, like this (assuming that the buildfile is called simple.bld, and that we want the resultant image to be called simple.ifs): 

mkifs simple.bld simple.ifs

Here's a buildfile with EIDE disk support: 

[virtual="x86,bios +compress"] .bootstrap = {
    startup-bios
    PATH=/proc/boot procnto
}
[+script] .script = {
    devc-con -e &
    devb-eide &
    reopen /dev/con1
    [+session] PATH=/proc/boot esh
}
libc.so
libcam.so
cam-disk.so
io-blk.so
fs-qnx4.so

[data=copy]
devc-con
esh
ls
devb-eide
[type=link] /usr/lib/ldqnx.so.2=/proc/boot/libc.so.2

This example includes an inline /etc/hosts file that's used to resolve addresses used at boot time by programs such as fs-nfs3; it also shows how environment variables can be passed to different commands:

Note: In a real buildfile, you can't use a backslash (\) to break a long line into shorter pieces, but we've done that here, just to make the buildfile easier to read.
[image=0x1f0000]
[virtual=ppcbe,raw] .bootstrap = {
    startup-mtx604-smp -v -Nmtx604-5 -D0x800003f8^0.9600
    PATH=/proc/boot:/bin:/usr/bin:/sbin:/usr/sbin \
LD_LIBRARY_PATH=/proc/boot:/lib:/usr/lib:/lib/dll \
procnto-600-smp -v
}

[+script] startup-script = {
    procmgr_symlink ../../proc/boot/libc.so.2 /usr/lib/ldqnx.so.2

    pci-raven &
    waitfor /dev/pci

    io-net -dtulip irq=2,media=9,vid=0x1011,did=0x9 -ptcpip &
    if_up -p en0
    ifconfig en0 mtx604-5 up
    if_up en0

    fs-nfs3 -ru ra:/qssl/QNXsdk /qssl/QNXsdk &
    waitfor /qssl/QNXsdk/target/qnx6/ppcbe/usr/sbin/slogger 360

    # setup environment variables
    TZ=est05edt04

    procmgr_symlink /qssl/QNXsdk/target/qnx6/ppcbe/bin /bin
    procmgr_symlink /qssl/QNXsdk/target/qnx6/ppcbe/lib /lib
    procmgr_symlink /qssl/QNXsdk/target/qnx6/ppcbe/sbin /sbin
    procmgr_symlink /qssl/QNXsdk/target/qnx6/ppcbe/usr/bin /usr/bin
    procmgr_symlink /qssl/QNXsdk/target/qnx6/ppcbe/usr/sbin /usr/sbin
    procmgr_symlink /qssl/QNXsdk/target/qnx6/ppcbe/usr/lib /usr/lib
    procmgr_symlink /qssl/QNXsdk/target/qnx6/etc /etc

    slogger &
    waitfor /dev/slog
    devc-ser8250 -e -c1846200 -b 9600 0x800003f8,104 0x800002f8,103 &
    waitfor /dev/ser1
    pipe &
    waitfor /dev/pipe
    devc-pty &
    waitfor /dev/ptyp0
    mqueue &
    inetd &

    tinit
}

[type=link] /tmp = /dev/shmem
[type=link] /dev/con1 = /dev/ser1

# data files are created in the named directory
/etc/hosts = {
127.0.0.1       localhost
192.168.1.1     ra
192.168.1.111   mtx604-5
}

libc.so
devn-tulip.so
npm-tcpip.so
libsocket.so

[data=uip]
pci-raven
io-net

[data=copy]
if_up
ifconfig
fs-nfs3

For more examples, see ${QNX_TARGET}/${PROCESSOR}/build.

Environment variables:

PROCESSOR
Specifies the target CPU. If not set, the default is the same as the CPU of the host system (e.g. x86).
MKIFS_PATH
Specifies a colon-separated list of directories to search for host files that should be included in the image. The default value consists of:
  1. The current working directory, if the filename contains a slash (/) but doesn't start with a slash.
  2. ${QNX_TARGET}/${PROCESSOR}/sbin
  3. ${QNX_TARGET}/${PROCESSOR}/usr/sbin
  4. ${QNX_TARGET}/${PROCESSOR}/boot/sys
  5. ${QNX_TARGET}/${PROCESSOR}/bin
  6. ${QNX_TARGET}/${PROCESSOR}/usr/bin
  7. ${QNX_TARGET}/${PROCESSOR}/lib
  8. ${QNX_TARGET}/${PROCESSOR}/lib/dll
  9. ${QNX_TARGET}/${PROCESSOR}/usr/lib
  10. ${QNX_TARGET}/${PROCESSOR}/usr/photon/bin

Exit status:

0
Successful completion.
1
An error occurred.

See also:

dumpifs, gcc

Making an OS Image and the Sample Buildfiles appendix in Building Embedded Systems

[Previous] [Contents] [Index] [Next]
 
©2013 QNX Software Systems Limited, a subsidiary of BlackBerry.   BlackBerry Logo