buildqnx

build a custom version of QNX (QNX)

Syntax:

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

Options:

-b baseaddr

Load QNX into memory, starting at baseaddr (default is 1000). 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.

build_file

An input file of module names.

os_file

An output image file. (default: standard output)

Examples:

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

cd /boot

buildqnx build/ws images/ws

Description:

The buildqnx utility builds a QNX boot image. A boot image is a collection of processes that are "pre-loaded" into a file which is 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 will first be transferred to the code in /boot/sys/boot which can be either explicitly named in the build file 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 by running the netboot utility. A makefile is provided in the /boot directory to help you create static images.

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 do not 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 will need 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, you would 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 boot. 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 the file Makefile, which references a set of build files that name the processes to be included in an image, and a directory sys which contains key image components.

The /boot/sys directory contains standard boot image components that are not runnable on their own from the command line, such as such as Proc, Slib16 and Slib32, Debugger32, and boot.

The following 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 is omitted from the buildfile, buildqnx will automatically insert 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.

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 Shared Library (Slib32/Slib16) 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, will be automatically inserted as the first entry in the boot image if it is not 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 build file 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. a command line

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

The following is a simple build file 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 build file will create 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 will display 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 will be replaced with appropriate information at boot time:

Using the supplied Makefile

Let's say the hard disk build file 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 build file — by copying the existing /.boot to /.altboot, as follows:

cp /.boot /.altboot

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

We have provided a Makefile and a few standard build files 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. The sinit process will attempt to execute the /etc/config/sysinit.node file on the current node. If the file doesn't exist, sinit will attempt 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.

Exit status:

0

Successful.

>0

An error occurred.

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 is not 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 will be written to standard error.

The standard input is not used by buildqnx.

See also:

• boot bootstrap (Bootstrap the operating system)
• netboot manager (Service network boot requests)
• sinit utility (System initialization)
• tinit utility (Terminal initialization)
• QNX Installation & Configuration