System configuration

Exactly how you should configure your system depends on the type of system you're building. Below are some very general guidelines to help you understand how to use a mkifs buildfile to configure your system, including which executables should be used in what circumstances, and which shared libraries are required for these executables.

The general procedure to set up a system is as follows:

Establish an output device (see “Output device”).
Run drivers and filesystems (see “Drivers and filesystems”).
Run applications (see “Applications”).

For changes you make to your mkifs buildfile to affect your system configuration, you must re-build your system. For instructions on how to build a new system image after you have modified the buildfile, see the chapter Working with QNX BSPs in this guide.

See the Sample Buildfiles appendix in this guide for some sample buildfiles. If you are use a QNX product such as QNX CAR or QNX Platform for ADAS, see Working with Target Images for more information about how to use filesets, profiles and product-specific configuration files.

Note: If your system will use a watchdog utility (see “Software watchdog” in the System Architecture guide), you should start it before you set up your output device. Watchdog utilities are board-specific; see the “Driver commands” section of the BSP User's Guide for your board for more information.

Output device

One of the first things you should do in a buildfile is start a driver to which you can redirect standard input, output, and errors. Starting a driver early on in the startup sequence provides all subsequent drivers and applications a known location to which they can output their startup messages, diagnostics and error messages. In most cases, the output device you should start will be a serial port driver (e.g., devc-ser8250).

If your system doesn't have a serial driver, you may choose to omit this step, or use some other type of device, for which you will need to write a specialized driver. If you don't specify a driver, by default, output goes to the debug output driver provided by the startup code.

CAUTION:

If you don't redirect output, the default debug output driver may cause performance problems on your system. These problems are often quite difficult to debug.

Drivers and filesystems

Your embedded system must run drivers and filesystems that will make the hardware accessible to external devices.

You can include these drivers and filesystems in the image you build before you trasfer it to your target. QNX Neutrino supports numerous drivers and filesystems. These are documented in the Utilities reference:

disk drivers (devb-*)
flash filesystems (devf-*)
network drivers (devnp-*)
input drivers (devi-*)
USB drivers (devu-*)
filesystems (fs-*)

Note: Board-specific drivers aren't documented in the Utilities reference; see the BSP User's Guide for your BSP and the src directory and its subdirectories in the BSP for you board.

Placing drivers in the startup sequence

For most systems it is best to keep the OS image small. This means not putting all the executables and shared libraries into the OS image. Instead, do the following:

In some other medium, such as a flash filesystem, a network filesystem, or rotating disk, place the executables and libaries you won't need immediately.
In the OS image, place the the executables you need to have start immediately (e.g., the watchdog and a serial driver), and the drivers the system will need to access the executables from the other media (start drivers, etc.).

In other words:

Disk, flash and network drivers all rely on a process that loads one or more .so files. (These files are selected either through the command line, or via automatic configuration detection.)
Since these drivers all use shared object (.so) files (both their own driver-specific files, and standard ones such as the C library), these .so files must be present before the drivers start.
Therefore, the .so files needed to start these drivers must be on a medium other than the one for which the driver is being started. (e.g., Don't put the executables and libraries the system will need to access a rotating disk on the rotating disk.)
In short, put the .so files in the OS image.

Note: If you system has no secondary storage media, or if it requires everything to be available immediately, without needing to start a driver, then you need to place all the executables and shared libraries directly into the OS image.

Disk drivers

When configuring your image to support a rotating or solid-state disk, you must first determine what hardware controls the disk interface. The QNX Neutrino RTOS supports a number of interfaces, including the EIDE controller. For details on the supported interface controllers, see the various devb-* entries in the Utilities Reference.

The only instruction you need to put in your buildfile is to start the driver for the appropriate hardware. For example, for the AHCI SATA interfaces driver on an x86 board:

Detect all SATA controllers and list all the connected devices:
```
devb-ahci &
```
Detect all SATA controllers and use DMA-typed memory
```
devb-ahci mem name=/ram/dma &
```

The driver will then dynamically load the required modules, in this order:

libcam.so — Common Access Method library
cam-*.so — Common Access Method module(s)
io-blk.so — block I/O module
fs-*.so — filesystem personality module(s)

The CAM .so files are documented under cam-* in the Utilities Reference. Currently, QNX Neutrino supports CD-ROMs (cam-cdrom.so), hard disks (cam-disk.so), and optical disks (cam-optical.so).

The io-blk.so module is responsible for dealing with a disk on a block-by-block basis. It includes caching support.

The fs-* modules are responsible for providing the high-level knowledge about how a particular filesystem is structured. QNX Neutrino currently supports the following:

Filesystem	Module
MS-DOS	fs-dos.so
Macintosh HFS and HFS Plus	fs-mac.so
Windows NT	fs-nt.so
Power-Safe	fs-qnx6.so
ISO-9660 CD-ROM, Universal Disk Format (UDF)	fs-udf.so

Network drivers

Network services are started from the io-pkt* command, which is responsible for loading in the required .so files (see io-pkt-v4-hc, io-pkt-v6-hc in the Utilities Reference).

Two levels of .so files are started, based on the command-line options given to io-pkt*:

-d: The -d option specifies driver .so files. It lets you choose the hardware driver you need for the network card on your system. For example, choosing -d e1000 instructs io-pkt* to load devnp-e1000.so, which is needed to access Intel Gigabit Ethernet controllers. After the -d, you may specify additional command-line options , such as the interrupt vector the card should use.
-p: The -p option specifies protocol .so files. It lets you choose the protocol driver required for a particular protocol. As with the -d option, after the -p for the driver you may specify further command-line options, such as the IP address for a particular interface.

For more information, see the Core Networking Stack User's Guide, as well as the devnp-*, and io-pkt* entries in the Utilities Reference.

Note:

To dynamically load a network driver, simply use the mount command at command line. For example:

mount -T io-pkt devnp-e1000.so

Flash filesystems

To run a flash filesystem, you need to select the appropriate flash driver for your target system. For details on the supported flash drivers, see the various devf-* entries in the Utilities Reference. Note that:

NOR flash: The devf-generic NOR flash driver that can be thought of as a universal driver whose capabilities make it able to access most NOR flash devices (see devf-generic).; The NOR flash filesystem drivers don't rely on any flash-specific .so files, so the only module required is the standard C library (libc.so).; Since the NOR flash filesystem drivers are written for specific target systems, you can usually start them without command-line options; they'll find the flash for the specific system for which they were written.
NAND flash: The devb-nand NAND flash driver isn't shipped with the QNX Neutrino. It is included in BSPs for boards that support NAND flash filesystems.

For instructions on how to build a flash filesystem images, “Building a flash filesystem image” in the OS Images chapter. For specific instructions for starting flash filesystem drivers, see the BSP User's Guide for your board and QNX Neutrino release.

Network filesystems

Before it attempts to load a network filesystem, your system must load the network drivers it will need (see “Network drivers” above). Be sure to set the load sequence appropriately in your startup configuration.

QNX Neutrino support two types of network filesystems:

NFS: Allows file access over a network to a UNIX or other system running an NFS server (see fs-nfs2 and fs-nfs3) in the Utilities Reference).; NFS is primarily a UNIX-based filesystem, but you may find some versions of NFS available for Windows platforms.
CIFS: Allows file access over a network to a Windows 98 or NT system, or to a UNIX system running an SMB server. (see fs-cifs in the Utilities Reference).; The CIFS protocol makes no attempt to conform to POSIX.

Applications

Nothing special is required to run applications. Usually, you'll place them in the script file after all the drivers have started, or later in a the flash filesystem image you generate with mkefs (see “Building a flash filesystem image” in the OS Images chapter). If you require a particular driver to be present and ready, before you start an application, you would typically use the waitfor command in the script part of your buildfile (see “Scripts” in the OS Image Buildfiles chapter).

Here's an example. Before it starts, an application called peelmaster needs to wait for a driver (driver-spud) to be ready. The following sequence is typical:

driver-spud &
waitfor /dev/spud
peelmaster

This sequence causes the driver (driver-spud) to be run in the background (specified by the ampersand character). The expectation is that when the driver is ready, it will register the pathname /dev/spud. The waitfor command tries to access (stat()) the pathname /dev/spud periodically, blocking execution of the script until either the pathname appears, or a pre-determined timeout threshold has been reached.

Once the pathname appears in the pathname space, we assume that the driver is ready to accept requests. At this point, the waitfor unblocks, and the next program in the list (in our case, peelmaster) executes.

Without the waitfor command, the peelmaster program would run immediately after the driver was started, which could cause peelmaster to miss the /dev/spud pathname and fail.

Boot optimization

For information about how to optimize boot times, or how to get specific components up quickly so that they can provide services (e.g., rear-view camera in a vehicle), see the Boot Optimization Guide.