Building an OS Image

This chapter covers the following topics:

• Introduction
• Constructing a build file
• Where executables are stored
• Selecting processes for an image

Introduction

QNX is a modular operating system composed of a microkernel and one or more processes that provide services. For example, the process named Fsys provides filesystem services, the process named Net provides network services, and so on.

When you build an OS image, you select the services that you want to be available immediately after boot, and include the processes that provide those services into a custom-built OS. You create this image with the buildqnx utility. The image can be booted from disk by the QNX partition loader or booted over the network using the netboot utility.

Constructing a build file

The buildqnx utility produces a binary image file containing several processes as listed in an input text file called a "build" file. The build files are kept in the /boot/build directory; the image files are kept in the /boot/images directory.

You can create an image for any node by invoking buildqnx directly or by using the make utility and the Makefile in the /boot directory. For example, you could enter either of the following commands to create an image file called hard.1 from the sample build file hard.1:

cd /boot
buildqnx build/hard.1 images/hard.ata.1

OR

cd /boot
make b=hard.ata.1

Build file format

Each program you want included in the created image is specified using three lines in the build file:

• first line -- the pathname of the program you want included
• second line -- starts with a $, followed by an initial heap size value of 1, followed by a command.
• third line -- must be blank to separate one entry from the next.

Relative pathnames are assumed to start at /boot.

Here's the sample build file hard.ata.1:

sys/boot
$ 1 boot -v

sys/Proc32
$ 1 Proc32 -l 1

sys/Slib32
$ 1 Slib32

sys/Slib16
$ 1 Slib16

/bin/Fsys
$ 1 Fsys

/bin/Fsys.ata
$ 1 Fsys.ata

/bin/mount
$ 1 mount -p /dev/hd0 /dev/hd0t77 /

/bin/sinit
$ 1 sinit TERM=ansi

Setting heap sizes

The number after the $ symbol sets the initial heap size. A value of "1" will cause the heap size to grow dynamically as needed.

Setting priorities

You can set the initial priority of a process by following the heap size value with an optional :nn argument, where nn is the desired priority in the range from 1 (the lowest) to 30 (the highest). For example, the following would start the floppy driver (Fsys.floppy) with a priority of 8:

/bin/Fsys.floppy
$ 1:8 Fsys.floppy

Where executables are stored

Most QNX system executables are stored in the /bin directory. Some components are usable only as part of the boot image; these are stored in subdirectories under the /boot directories.

The following table summarizes these conventions:

For more information on where files are stored in QNX, see Appendix B.

Selecting executables for an image

The processes you include in an OS image are determined by several factors. You can typically group images into three classifications:

• images loaded from disk
• images loaded over the network
• images loaded into embedded systems

The boot process (/boot/sys/boot) is always automatically inserted into the first line of the generated image, even if it isn't explicitly specified. If you need to supply options to sys/boot, you must add the line "sys/boot" to the build file as the first process.

For images loaded from disk or over the network, you can start most processes after booting. You do so by placing their command lines in the system initialization file that QNX executes after boot (see "The system initialization file" in the Basic Installation chapter). This lets you keep the boot image small (< 512K) and simple.

The build file doesn't generally contain the Device Manager /bin/Dev. The Device Manager and its drivers are usually started in the system initialization file after the system boots.

If the system initialization file isn't executed, the Device Manager will not be started. As a result, your keyboard and system console won't function.

Mandatory processes

When you're building an image, remember that there are two mandatory processes:

• the Process Manager/Microkernel (/boot/sys/Proc32)
• the system shared library (/boot/sys/Slib32)

To run 16-bit programs, you must include the 16-bit shared library /boot/sys/Slib16.

Disk images

For hard disk booting, you need to include:

• the two required system processes (Proc32 first and Slib32 second)
• the Filesystem Manager (Fsys)
• the driver required to access the drive (Fsys.driver)

For more information, see buildqnx, Fsys*, Proc32, Slib*, and sinit in the Utilities Reference.

The Makefile for disk booting

The Makefile for building boot images (under the directory /boot) contains an entry for making a generic hard disk boot image. When you build the OS image, default parameter values are used unless you enter new values when you invoke the make utility.

Here's a make example that will create a boot image called /boot/images/hard.1 using a build file called /boot/build/hard.1:

cd /boot
make b=hard.1

Note that you can create images statically by invoking the buildqnx utility or dynamically by running the netboot utility. For details, see these utilities in the Utilities Reference.

Here's an example of invoking buildqnx "by hand" -- this will create an image called /boot/images/ws32.ether1000 from a build file called /boot/build/ws32.ether1000:

cd /boot
buildqnx build/ws images/ws32.ether1000

Copying an image to /.boot

Once you've built an image, it won't become the new boot image until you copy it to the /.boot file. However, before you do this, you should make a backup of the current /.boot file by copying it to the /.altboot file:

cp /.boot /.altboot

If for any reason your new image doesn't work properly, you can press Esc when prompted during the boot process and load the /.altboot file instead of the /.boot file.

When you select the alternate boot image, the normal check for the /etc/config/sysinit.node file is replaced by a check for the /etc/config/altsysinit file. You should ensure that the altsysinit file contains the latest copy of your working sysinit file:

cp /etc/config/sysinit.node /etc/config/altsysinit

Network images

For network booting, you need to include:

• the two required system processes (Proc32 first and Slib32 second)
• the Network Manager (Net)
• the driver required to access the network hardware (Net.driver)

The build file for network booting

The following build file (/boot/build/ws.ether1000) contains parameter markers that inherit their values from the network environment:

sys/Proc32
$ 1 Proc32 -l $(lnode) -D

sys/Slib32
$ 1 Slib32

sys/Slib16
$ 1 Slib16

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

/bin/Net.ether1000
$ 1 Net.ether1000

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

sys/Debugger32
$ 1 Debug

The $(lnode) marker in the Proc32 command takes as its value the logical node ID of a booting machine. The logical node ID is determined by netboot and passed to buildqnx based on the Ethernet address of the booting machine and its mapping entry in the /etc/config/netmap file.

The $(netmap) marker in the Net command tells Net the initial network mapping of the boot server so that the booting machine can start network communications with it.

The $(bnode) marker in the sinit command represents the logical node ID of the boot server. The command sets the root (/) of the booting machine's filesystem to the root of the boot server.

The value of the $(TZ) marker is inherited from the boot server. The command sets the booting machine's time zone information to match the current setting of the boot server's TZ environment variable.

If you must build a pre-built image for a node, don't use markers -- hardcode the required values directly into a custom build file instead. For more information, see buildqnx in the Utilities Reference as well as the Networking chapter in this guide.

When you boot over the network, you have the option of loading a pre-built image or building one on the fly. If you build an image on the fly -- which is recommended -- then you won't need to build one manually as shown above. This option is specified in the /etc/config/netboot file and documented in the netboot utility man page.

When the netboot utility invokes buildqnx to build an image on the fly, the image file is not written to disk.

Embedded images

An embedded image is required for embedded CPU systems. While the term "embedded system" has various meanings, QNX supports two general classifications:

• embedded PCs
• custom hardware

Embedded PCs

These are computerized controllers that behave just like a PC -- they can have keyboards, screens, disks, or network cards connected to them. They're typically used in process control applications. Some of these systems have a small amount of Flash memory available, either built into the CPU card (such as the Ziatech ZT8902) or available as a plug-in card (such as the Ampro MM/SSD).

The QNX Embedded Kit supports various CPU cards and Flash cards. This support includes booting from the Flash card (usually via some BIOS hook) and using the Flash memory as a filesystem.

Custom hardware

These systems are custom designed to fit one specific application. They usually have Flash memory, but no disk or network card. Most of these kinds of systems (e.g. Intel 386EX and AMD SC400 processors) have no keyboard or screen. The QNX Embedded Kit provides support for some of the commonly used processor evaluation boards.

Selecting processes for an embedded image

You can modify the QNX Embedded Kit to support your particular hardware. Your embedded image should contain only the processes required to run the system. This image would then have to be transferred to the embedded system (most likely in ROM).