System configuration

Updated: April 19, 2023

Before you can use your embedded system, you need to configure it for the drivers, filesystems, and applications it needs to run.

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 an 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:

  1. Establish an output device (see Output device).
  2. Run drivers and filesystems (see Drivers and filesystems).
  3. Run applications (see Applications).

For changes you make to your mkifs buildfile to affect your system configuration, you must rebuild 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 using 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, 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 error. Starting a driver early in the startup sequence provides all subsequent drivers and applications a known location for outputting startup, 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.

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 transfer it to the target. QNX Neutrino supports many drivers and filesystems, which are described in the Utilities Reference:

Note: Board-specific drivers aren't documented in the Utilities Reference. For information about these drivers, see your BSP User's Guide. To find the drivers, look in the src directory and its subdirectories in the BSP itself.

Placing drivers in the startup sequence

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

  1. 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.
  2. In the OS image, place the executables that need to be started 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:

Note: If your 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 of 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:

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

  1. — Common Access Method library
  2. cam-*.so — Common Access Method module(s)
  3. — block I/O module
  4. fs-*.so — filesystem personality module(s)

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

The 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
Macintosh HFS and HFS Plus
Windows NT
ISO-9660 CD-ROM, Universal Disk Format (UDF)

Network drivers

Network services are started from the io-pkt* command, which is responsible for loading 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*:

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, 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.
The -p option specifies protocol .so files. It lets you choose the 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.

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

mount -T io-pkt

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

Flash filesystems

To run a flash filesystem, you must 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 can be thought of as a universal driver because it can access most NOR flash devices (see the devf-generic reference).
The NOR flash filesystem drivers don't rely on any flash-specific .so files, so the only module required is the standard C library (
Since these drivers are written for specific target boards, you can usually start them without command-line options; they'll find the flash filesystem for the board for which they're written.
NAND flash
The devb-nand NAND flash driver isn't shipped with the QNX Neutrino RTOS. It is included in BSPs for boards that support NAND flash filesystems.

For instructions on building the filesystem image, see Building a flash filesystem image in the OS Images chapter. For instructions on starting flash filesystem drivers, see your BSP User's Guide.

Network filesystems

Before it tries 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:

Allows file access over a network to a UNIX or other system running an NFS server (see 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.
Allows file access over a network to a Windows 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.


Nothing special is required to run applications. Usually, you place them in the script file after all the drivers have started, or later in a 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 running 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

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 (with stat()) the pathname /dev/spud periodically, blocking execution of the script until either the pathname appears or a pre-determined timeout has been reached.

When 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 they can provide services (e.g., rearview camera in a vehicle), see the Boot Optimization Guide.