build a custom version of QNX (QNX)
buildqnx [-b baseaddr] [-Vv] [macro=name] build_file [os_file]
Build the OS image /boot/images/ws from the buildfile /boot/build/ws:
cd /boot buildqnx build/ws images/ws
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:
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:
Category | Process | Description |
---|---|---|
A | boot | Operating system bootstrap |
B | Proc | Process Manager, including the microkernel |
B | Slib32 | 32-bit Shared Libraries |
H | Slib16 | 16-bit Shared Libraries |
C | Fsys | QNX Filesystem Manager |
C | Fsys.* drivers | QNX Filesystem Drivers |
D | Dosfsys | DOS Filesystem Manager (requires Fsys) |
D | Dev | Device Manager |
D | Dev.* drivers | Device Drivers |
E | Net | Network Manager |
E | Net.* drivers | Network Drivers |
F | sinit | System initialization process |
G | Debugger32 | Low-level system debugger (not for general use) |
The process categories are as follows:
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:
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:
This macro: | Will be replaced by: |
---|---|
$(lnode) | the workstation's logical node ID |
$(bnode) | the boot server's filesystem root, under which /etc/config/sysinit.node may be found |
$(netmap) | the logical-to-physical node mapping of the boot server |
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
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.
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.