buildqnx

Build a custom version of QNX (QNX)

Syntax:

buildqnx [-b baseaddr] [-Vv] [macro=name] 
         buildfile [os_file]

Options:

-b baseaddr

Load QNX into memory, starting at baseaddr (default is 0x1000). This is a linear address that must reside in the first 640K of memory. The address must be specified in hex, must be greater than or equal to 0x1000, and must be a multiple of 0x1000.

-v

Be verbose.

-V

Be very verbose.

macro=name

Define a macro.

buildfile

An input file of module names.

os_file

An output image file (default: standard output).

Description:

The buildqnx utility builds a QNX boot image. A boot image is a collection of processes that are "preloaded" into a file that's loaded into memory at boot time. Once the image is in memory, control is transferred to the first process in the image; this process starts each of the other processes. For the full 32-bit Proc (versions 4.23A and later), this control is first transferred to the code in /boot/sys/boot, which can be either explicitly named in the buildfile or implicitly added by buildqnx when it sees that the full 32-bit Proc is being used in the image. The boot code relocates the processes in the boot image, sets up segments, and then runs Proc.

You may create images statically by explicitly invoking buildqnx, or create them dynamically for machines booting from the network by running the netboot utility.

Each major QNX service is provided by a process. You can add or delete an operating system service by adding or deleting the process that manages it. Most processes may be started after the system boots and as such don't need to be included in an image.

For example, let's say you've booted from disk and the boot image didn't contain the DOS filesystem manager (Dosfsys). At this point you're getting your files and commands from a local QNX filesystem. You could start Dosfsys by typing its name on the command line and running it as a background process, as follows:

Dosfsys &

It's necessary to start some processes before the system becomes functional. For example, if a diskless workstation boots over the network, it needs to have a network manager in the image to access the remote filesystem. Likewise, if you boot from a hard disk, you can't start a filesystem manager process by loading it off the disk, since you don't yet have a filesystem to load from. In this case, build a boot image containing Fsys, and an Fsys driver, and mount so that the filesystem is available immediately upon loading.

As a general rule, you should build into the image only the minimum services needed, and start other services after booting. In some environments, you may want to freeze an OS and a larger number of services by building a large image that you don't change. If you're in a special embedded environment where dynamic loading isn't possible (such as would be the case if, for instance, neither a network manager (Net) nor filesystem manager (Fsys) were going to be run), you may also choose to build a complete load image of all the processes you need.

The core kernel modules and images are placed under the /boot directory. This directory contains:

Makefile

A file that references a set of buildfiles that name the processes to be included in an image.

sys

A directory that contains key image components that aren't runnable on their own from the command line, such as Proc, Slib16 and Slib32, Debugger32, and boot.

The following table lists standard QNX processes that are often included in an image:

The process categories are as follows:

A

Must be present as the first entry in the image. If it's omitted from the buildfile, buildqnx automatically inserts it (without any options).

B

Must be present in an image as the first two processes after boot.

C

Needed if you want to boot from a disk controlled through that adapter type.

D

Can be started later in the sysinit file -- we recommend this method.

E

Needed if you want to boot over the network; otherwise can be started in the sysinit file. (May be omitted when booting over the network if the machine being booted is a standalone machine that doesn't need to read the sysinit or fetch other resources at boot time from the boot server.)

F

Normally included to execute a shell file of processes that you start dynamically.

G

Needed for low-level system work.

H

Required for running 16-bit executables from versions of QNX prior to 4.23.

You must include the Process manager (Proc) and the 32-bit shared library (Slib32) in the boot image. Each manager typically requires that you include one or more drivers if it's to be useful.

The operating system bootstrap, boot, is automatically inserted as the first entry in the boot image if it isn't explicitly specified. To access the optional functions of the bootstrap (such as its -v (verbose) option, which lists the components that are loaded in the boot image) you must explicitly specify boot as the first entry, supplying the desired options.

The list of programs to build into the image is kept in a buildfile under /boot/build. Each program occupies two lines in this file (empty lines are ignored). The first line is the pathname of the program. The second line starts with a $ followed, in order, by:

1. An optional number representing the size of the initial heap (alloc space)
2. An optional :nn, where nn is the starting priority of the process
3. An optional comma (,) followed by one or more of the following modifiers:

   d or D

   Mark the process as the system debugger.

   m or M

   Mark the code as impure (i.e. copy it from XIP or ROM into RAM).

4. A command line.

If you don't specify a priority, your program starts at priority 10. A program always starts with a round-robin scheduling algorithm.

The following is a simple buildfile for creating an image to boot from a hard disk with an enhanced IDE controller on a single-node computer. The sinit utility is used to execute the system initialization file:

sys/Proc
$ Proc

sys/Slib32
$ Slib32

sys/Slib16
$ Slib16

/bin/Fsys
$ Fsys

/bin/Fsys.eide
$ Fsys.eide
	
/bin/mount
$ mount -p /dev/hd0 /dev/hd0t77 /
	
/bin/sinit 
$ sinit TERM=qnx

Likewise, the following buildfile creates an image to boot a workstation over an Ethernet network using an NE1000/2000 compatible Ethernet card:

sys/Proc
$ Proc -l $(lnode)

sys/Slib32
$ Slib32

sys/Slib16
$ Slib16

/bin/Net
$ Net -m $(netmap)

/bin/Net.ether1000
$ Net.ether1000

/bin/sinit
$ sinit -r //$(bnode)/ TERM=qnx TZ=$(TZ)

In both the previous examples, the operating system bootstrap was inserted first into the boot image by buildqnx. The bootstrap may be specified explicitly, allowing options to be passed to the bootstrap. In this example, the bootstrap displays the OS components in the boot image as it executes:

sys/boot
$ boot -v

sys/Proc
$ Proc -l $(lnode)

sys/Slib32
$ Slib32

/bin/Net
$ Net -m $(netmap)

/bin/Net.ether1000
$ Net.ether1000

/bin/sinit
$ sinit -r //$(bnode)/ TERM=qnx TZ=$(TZ)

The following macros are replaced with appropriate information when buildqnx is run. The values used for the macro replacement must be specified via buildqnx's command line arguments (macro=name). Normally this is done by the netboot utility when it invokes buildqnx.

Using the supplied Makefile

A makefile is provided in /boot as a convenience for building static boot images. It allows for images to be built based on macros that define disk drive types, etc, for which the makefile supplies default values if none are specified.

Buildfiles that use these macros can't be used for network booting because netboot doesn't set the macros when it runs buildqnx.

Let's say the hard disk buildfile is in /boot/build/hard.1. You could build an image with the make utility, using the following:

cd /boot
make b=hard.1

An image, called hard.1, is placed in the /boot/images directory. To make this image bootable from a hard disk, copy it to the /.boot file in the root directory of the hard disk. Before copying the file, you may wish to make a copy of the existing boot image -- in case you made a mistake in your buildfile -- by copying the existing /.boot to /.altboot, as follows:

cp /.boot /.altboot
cp /boot/images/hard.1 /.boot

We've provided a Makefile and a few standard buildfiles in the /boot directory that you can use as models:

To make a hard disk image:

make b=hard.1 d=driver_name

Starting processes omitted from the image

You should start the processes that were omitted from the image in the system initialization file, which is executed by the sinit process. This process attempts to execute the /etc/config/sysinit.node file on the current node. If the file doesn't exist, sinit attempts to execute the /etc/config/sysinit file.

For more information, see the section on the system initialization file in the Basic Installation chapter of the QNX Installation & Configuration manual.

Examples:

Build the OS image /boot/images/ws from the buildfile /boot/build/ws:

cd /boot
buildqnx build/ws images/ws

Files:

The buildqnx command requires an ASCII text buildfile to be specified on the command line, and writes the resulting binary OS image to the os_file file named on the command line, or to standard output if no os_file is specified.

When the binary isn't being written to the standard output and -v or -V is specified, informative messages are written to the standard output as buildqnx does its work.

When buildqnx encounters an error, a diagnostic message is written to standard error.

The buildqnx command doesn't use standard input.

Exit status:

0

Successful.

>0

An error occurred.

Caveats:

The syntax of the buildfile is fragile. The buildqnx command "knows" that there are at least two characters (the newline and the $) between the tail of the actual file (e.g. /bin/Fsys) and the argv[0] string (e.g. Fsys). Intermediate chars are squeezed out and argv[0] is copied to one character after the tail of the filename.

By default, buildqnx:

• Inserts the command sys/boot if the first program isn't 16 bit.
• Marks *Slib* as impure code if it's a 16-bit program (i.e. the code must be copied from XIP or ROM into RAM).
• Marks *Debugger* as the system debugger and impure.
• Translates *Debugger to *Debugger32.

Also, a 32-bit program matching *Slib* defaults to priority 28, and a 16-bit program matching *Slib* defaults to priority 26. This is to ensure proper startup order.

We are quite embarassed.

See also:

boot, netboot, sinit, tinit

QNX Installation & Configuration guide