Caution: This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.

Building OS and Flash Images

In this chapter:

Introducing the QNX System Builder

One of the more distinctive tools within the IDE is the QNX System Builder perspective, which simplifies the job of building OS images for your embedded systems. Besides generating images intended for your target board's RAM or flash, the QNX System Builder can also help reduce the size of your images (e.g. by reducing the size of shared libraries). The Builder also takes care of tracking library dependencies for you, prompting you for any missing components.

When you open the QNX System Builder to create a project, you have the option to either import or customize an existing buildfile in order to generate an image, or create one from scratch. The QNX System Builder editor lets you select the components (the binaries, DLLs, and libraries) that you want to incorporate into your system image. As you add a component, the QNX System Builder automatically adds any shared libraries required for runtime loading. For example, if you add the telnet application to a project, the QNX System Builder will automatically include libsocket.so to ensure that telnet can run.


Note:

The QNX System Builder won't automatically include the necessary DLLs because they aren't listed in the NEEDED section for a given binary.

For more information, see Managing your images


The QNX System Builder contains a Serial Terminal view for interacting with your board's ROM monitor or QNX Initial Program Loader (IPL) and for transferring images (using the QNX sendnto protocol). The QNX System Builder also has an integrated TFTP Server that lets you transfer your images to network-aware targets that can boot via the TFTP protocol.

When you open the QNX System Builder to create a project, you have the option to either import or customize an existing buildfile in order to generate an image, or create one from scratch. The QNX System Builder editor lets you select the components (the binaries, DLLs, and libraries) that you want to incorporate into your system image. As you add a component, the QNX System Builder automatically adds any shared libraries required for runtime loading. For example, if you add the telnet application to a project, the QNX System Builder will automatically include libsocket.so to ensure that telnet can run.


Note:

The QNX System Builder won't automatically include the necessary DLLs because they aren't listed in the NEEDED section for a given binary.

For more information, see Managing your images.”


Using standard QNX embedding utility (mkifs, mkefs), the QNX System Builder can generate configuration files for this tool that can be used outside of the IDE for scripted/automated system building. As you do a build, a Console view shows the output from the underlying build command. You can use the mksbp utility to build a QNX System Builder project.bld from the command-line; mksbp automatically calls mkifs or mkefs, depending on the kind of image being built to build the image.

Here's what the QNX System Builder perspective looks like:

Builder perspective

One of the main areas in the QNX System Builder is the editor, which presents two panes side by side:

Builder perspective

Images
Shows all the images you're building. You can add or remove binaries and other components, view their properties, etc.
Filesystem
Shows the components of your image arranged in a hierarchy, as they would appear in a filesystem on your target.

Toolbar buttons

Above the Images and Filesystem panes in the editor you'll find several buttons for working with your image:

Icon: Add new binary button
Add a new binary.
Icon: Add new shared lib button
Add a new shared library.
Icon: Add new DLL button
Add a new DLL.
Icon: Add new symlink button
Add a new symbolic link.
Icon: Add new file button
Add a new file.
Icon: Add new inline file button
Add a new inline file (i.e. a file whose contents are specified in the buildfile).
Icon: Add new directory button
Add a new directory.
Icon: Add Image button
Add a new image.
Icon: Optimize button
Run the System Optimizer.
Icon: Rebuild project
Rebuild the current project.
Icon: Combine images
Merge two or more images into a single image.

Binary Inspector

Below the Images and Filesystem panes is the QNX Binary Inspector view, which shows the usage message for any binary you select:

Binary inspector

The Binary Inspector also has a Use Info tab that gives the selected binary's name, a brief description, the date it was built, and so on.

Boot script files

All QNX BSPs ship with a buildfile, which is a type of “control” file that gives instructions to the mkifs command-line utility to generate an OS image. The buildfile specifies the particular startup program, environment variables, drivers, etc. to use for creating the image. The boot script portion of a buildfile contains the sequence of commands that the Process Manager executes when your completed image starts up on the target.


Note: For details on the components and grammar of buildfiles, see the section Configuring an OS image in the chapter Making an OS Image in Building Embedded Systems, as well as the entry for mkifs in the Utilities Reference.

The QNX System Builder perspective provides a convenient graphical alternative to the text-based buildfile method. While it hides most of the “gruesome” details from you, the QNX System Builder perspective also lets you see and work with things such as boot scripts.

The QNX System Builder perspective stores the boot script for your project in a .bsh file. If you double-click a .bsh file in the Navigator or System Builder Projects view, you'll see its contents in the editor.

QNX System Builder projects

Like other tools within the IDE, the QNX System Builder perspective is project-oriented — it organizes your resources into a project of related items. Whenever you create a project in the QNX System Builder perspective, you'll see a project.bld file in the Navigator or System Builder Projects view.

The project.bld file drives the System Builder editor; if you select the project.bld, you'll see your project's components in the Images and Filesystem panes, where you can add and remove items for the image you'll be building.


Note: As with most other tools in the IDE, you build your QNX System Builder projects using the standard Eclipse build mechanism via Project-->Build Project.

The scope of the QNX System Builder

You can use the QNX System Builder throughout your product-development cycle:


Note: For details on importing a BSP, see the section Importing a BSP or other QNX source packages in the chapter Managing Source Code in this guide.

Overview of images

Before you use the QNX System Builder to create OS and flash images for your hardware, let's briefly describe the concepts involved in building images so you can better understand the QNX System Builder in context.

This section covers the following topics:

The components of an image, in order of booting

Neutrino supports a wide variety of CPUs and hardware configurations. Some boards require more effort than others to embed the OS. For example, x86-based machines usually have a BIOS, which greatly simplifies your job, while other platforms require that you create a complete IPL. Embedded systems can range from a tiny memory-constrained handheld computer that boots from flash, to an industrial robot that boots through a network, to a multicore system with lots of memory that boots from a hard disk.

Whatever your particular platform or configuration, the QNX System Builder helps simplify the process of building images and transferring them from your host to your target.


Note: For a complete description of OS and flash images, see the Building Embedded Systems guide.

The goal of the boot process is to get the system into a state that lets your program run. Initially, the system might not recognize disks, memory, or other hardware, so each section of code needs to perform whatever setup is needed in order to run the subsequent section:

  1. The IPL initializes the hardware, makes the OS image accessible, and then jumps into it.
  2. The startup code performs further initializations, and then loads and transfers control to the microkernel/process manager (procnto), the core runtime component of the QNX Neutrino OS.
  3. The procnto module then runs the boot script, which performs any final setup required and runs your programs.


Introduction: QNX System Builder; boot order


Typical boot order.

At reset, a typical processor has only a minimal configuration that lets code be executed from a known linearly addressable device (e.g. flash, ROM). When your system first powers on, it automatically runs the IPL code at a specific address called the reset vector.

IPL

When the IPL loads, the system memory usually isn't fully accessible. It's up to the IPL to configure the memory controller, but the method depends on the hardware — some boards need more initialization than others.

When the memory is accessible, the IPL scans the flash memory for the image filesystem, which contains the startup code (described in the next section). The IPL loads the startup header and startup code into RAM, and then jumps to the startup code.

The IPL is usually board-specific (it contains some assembly code) and is as small as possible.

Startup

The startup code initializes the hardware by setting up interrupt controllers, cache controllers, and base timers. The code detects system resources such as the processor(s), and puts information about these resources into a centrally accessible area called the system page. The code can also copy and decompress the image filesystem components, if necessary. Finally, the startup code passes control, in virtual memory mode, to the procnto module.

The startup code is board-specific and is generally much larger than the IPL. Although a larger procnto module could do the setup, we separate the startup code so that procnto can be board-independent. Once the startup code sets up the hardware, the system can reuse a part of the memory used by startup because the code won't be needed again.


Note: If you're creating your own startup variant, its name must start with startup or the QNX System Builder perspective won't recognize it.

The procnto module

The procnto module is the core runtime component of the QNX Neutrino OS. It consists of the microkernel, the process manager, and some initialization code that sets up the microkernel and creates the process-manager threads. The procnto module is a required component of all bootable images.

The process manager handles (among other things) processes, memory, and the image filesystem. The process manager lets other processes see the image filesystem's contents. Once the procnto module is running, the operating system is essentially up and running. One of the process manager's threads runs the boot script.

Several variants of procnto are available (e.g. procnto-400 for PowerPC 400 series, procnto-smp for x86 multicore machines, etc.).


Note: If you're creating your own procnto variant, its name must start with procnto- or the QNX System Builder perspective won't recognize it.

For more information, see the System Architecture Guide, as well as procnto in the Utilities Reference

Boot script

If you want your system to load any drivers or to run your program automatically after powering up, you should run those utilities and programs from the boot script. For example, you might have the boot script:

When you build your image, the boot script is converted from text to a tokenized form and saved as /proc/boot/.script. The process manager runs this tokenized script.

Types of images you can create

The IDE lets you create the following images:

OS image (.ifs file)
An image filesystem. A bootable image filesystem holds the procnto module, your boot script, and possibly other components such as drivers and shared objects.
Flash image (.efs file)
A flash filesystem. (The “e” stands for “embedded.”) You can use your flash memory like a hard disk to store programs and data.
Combined image
An image created by joining together any combination of components (IPL, OS image, embedded filesystem image) into a single image. You might want to combine an IPL with an OS image, for example, and then download that single image to the board's memory via a ROM monitor, which you could use to burn the image into flash. A combined image's filename extension indicates the file's format (e.g. .elf, .srec, etc.).

If you plan on debugging applications on the target, you must include pdebug in /usr/bin. If the target has no other forms of storage, include it in the OS image or flash image.

BSP filename conventions

In our BSP docs, buildfiles, and scripts, we use a certain filename convention that relies on a name's prefixes and suffixes to distinguish types:

Part of filename Description Example
.bin Suffix for binary format file ifs-artesyn.bin
.build Suffix for buildfile sandpoint.build
efs- Prefix for QNX Embedded Filesystem file; generated by mkefs efs-sengine.srec
.elf Suffix for ELF (Executable and Linking Format) file ipl-ifs-mbx800.elf
ifs- Prefix for QNX Image Filesystem file; generated by mkifs ifs-800fads.elf
ipl- Prefix for IPL (Initial Program Loader) file ipl-eagle.srec
.openbios Suffix for OpenBIOS format file ifs-walnut.openbios
.prepboot Suffix for Motorola PRePboot format file ifs-prpmc800.prepboot
.srec Suffix for S-record format file ifs-malta.srec

Note: The QNX System Builder uses a somewhat simplified convention. Only a file's three-letter extension, not its prefix or any other part of the name, determines how the QNX System Builder should handle the file.

For example, an OS image file is always an .ifs file in the QNX System Builder, regardless of its format (ELF, binary, SREC, etc.). To determine a file's format in the IDE, you'll need to view the file in an editor.


OS image (.ifs file)

The OS image is a bootable image filesystem that contains the startup header, startup code, procnto, your boot script, and any drivers needed to minimally configure the operating system:

Introduction: QNX System Builder; .ifs structure

Generally, we recommend that you keep your OS image as small as possible to realize the following benefits:

If your embedded system has a hard drive or CompactFlash (which behaves like an IDE hard drive), you can access the data on it by including a block-oriented filesystem driver (e.g. devb-eide) in your OS image filesystem and calling the driver from your boot script. For details on the driver, see devb-eide in the Utilities Reference.

If your system has an onboard flash device, you can use it to store your OS image and even boot the system directly from flash (if your board allows this — check your hardware documentation). Note that an OS image is read-only; if you want to use the flash for read/write storage, you'll need to import create a flash filesystem image (.efs file).

Flash filesystem image (.efs file)

Flash filesystem images are useful for storing your programs, extra data, and any other utilities (e.g. qconn, ls, dumper, and pidin) that you want to access on your embedded system.

If your system has a flash filesystem image, you should include a devf* driver in your OS image and start the driver in your boot script. While you can mount an image filesystem only at /, you can specify your own mountpoint (e.g. /myFlashStuff) when you set up your .efs image in the IDE. The system recognizes both the .ifs and .efs filesystems simultaneously because the process manager transparently overlays them. To learn more about filesystems, see the Filesystems chapter in the QNX Neutrino System Architecture guide.

Combined image

For convenience, the IDE can join together any combination of your IPL, OS image, and .efs files into a single, larger image that you can transfer to your target:

Introduction: QNX System Builder; .bin structure

When you create a combined image, you specify the IPL's path and filename on your host machine. You can either select a precompiled IPL from an existing BSP, or compile your own IPL from your own assembler and C source.


Note: The QNX System Builder expects the source IPL to be in ELF format.

Padding separates the IPL, .ifs, and .efs files in the combined image.

Padding after the IPL

The IPL can scan the entire combined image for the presence of the startup header, but this slows the boot process. Instead, you can have the IPL scan through a range of only two addresses and place the startup header at the first address.

Specifying a final IPL size that's larger than the actual IPL lets you modify the IPL (and change its length) without having to modify the scanning addresses with each change. This way, the starting address of the OS image is independent of the IPL size.


Caution: You must specify a padding size greater than the total size of the IPL to prevent the rest of the data in the combined image file from partially overwriting your IPL.

Padding before .ifs images

If your combined image includes one or more .efs images, specify an alignment equal to the block size of your system's onboard flash. The optimized design of the flash filesystem driver requires that all .efs images begin at a block boundary. When you build your combined image, the IDE adds padding to align the beginning of the .efs image(s) with the address of the next block boundary.

Project layout

A single QNX System Builder project can contain your .ifs file and multiple .efs files, as well as your startup code and boot script. You can import the IPL from another location or you can store it inside the project directory.

By default, your QNX System Builder project includes the following parts:

Item Description
Images directory The images and generated files that the IDE creates when you build your project.
Overrides directory When you build your project, the IDE first looks in this directory for a directory matching the image being built. Any files in that directory are used to satisfy the build requirements before searching the standard locations. You can use the Overrides/image_name directory to easily test a change to your build. The image_name subdirectory is created automatically, and you must populate it with the override files your image needs.
Reductions directory The IDE lets you reduce your image size by eliminating unused libraries, and shrinking the remaining libraries. The IDE stores the reduced libraries in the Reductions/image_name directory (where image_name is the name of the image being built).
.project file Information about the project, such as its name and type. All IDE projects have a .project file.
.sysbldr_meta file Information about the properties specific to a QNX System Builder project. This file describes where the IDE looks for files (including the Overrides and Reductions directories), the location of your IPL file, how the IDE includes .efs files, and the final format of your .ifs file.
project.bld file Information about the structure and contents of your .ifs and .efs files. This file also contains your boot script file.
.bsh file Contains the boot script for your project.

Overview of workflow

Here are the main steps involved in using the IDE to get Neutrino up and running on your board:


Note: To create an EFS project, you'll need to follow the Workaround instructions found in Creating a project for an OS image,” below.

Creating a project for an OS image

To create a new QNX System Builder Project:

  1. From the main menu, select File-->New-->Project.
  2. Expand QNX, and then select QNX System Builder Project. Click Next.
  3. Name your project, and then click Next.
  4. At this point, you can either import an existing buildfile (as shipped with your QNX BSPs) or select a generic type (e.g. “ppcbe”).

    Creating a QNX System Builder project


    Note: We recommend that you select Import Existing Buildfile, rather than a generic option. Creating a buildfile requires a working knowledge of boot script grammar (as described in the entry for mkifs in the Utility Reference and in the Building Embedded Systems manual).

    Click the Browse… button to select an existing buildfile. Refer to your BSP docs for the proper .build file for your board. You can find buildfiles for all the BSPs installed on your system in $QNX_TARGET/processor/boot/build/ on your host.

    If you're creating a generic buildfile, select your desired platform from the dropdown list.

  5. Click Finish. The IDE creates your new project, which includes all the components that make up the OS image.

Note:

Workaround: To create an EFS project:

  1. Create an empty (default) IFS project.
  2. Add an EFS image to the new IFS project.
  3. Remove the empty IFS image.

Creating a project for a flash filesystem image

To create a flash filesystem project:

  1. From the main menu, select File-->New-->Project.
  2. Expand QNX, then select QNX System Builder EFS Project in the right. Click Next.
  3. Name your project and click Next.
  4. Specify your target hardware (e.g. “armle”).
  5. Click Finish. The IDE creates your new EFS project, which includes a “generic” .efs image; you'll likely need to specify the block size, image size, and other properties to suit the flash on your particular board.

Creating a project with multiple images

Building an OS image

To build your QNX System Builder projects using the standard Eclipse build mechanism:
From the main menu, select Project-->Build Project.

You can also build projects using the context menu:

  1. In the Navigator or System Builder Projects view, right-click the project.
  2. Select Build Project.

The System Builder Console view shows the output produced when you build your images:

System Builder Console view

Output can come from any of these utilities:

For more information, see their entries in the Utilities Reference.

You can clear the view by clicking the Clear Output button (Icon: Clear Console).

Creating a new image

You can create a new image for your QNX System Builder project by using the Add New Image icon (Add New Image) in the System Builder editor's toolbar:

  1. Click the Add New Image icon in the toolbar.

    The IDE shows the Create New Image dialog box:

    Create new image

  2. Use the Create New Image dialog to:
  3. Click OK to create the new image and add it to your project.

Combining images

As mentioned earlier, the QNX System Builder lets you create a combined image. You use the Combine image(s) icon (Combine images) to:

Adding an IPL to the start of your image

To add an IPL to the start of your image:

  1. In the Images view, select your image.
  2. Click the Combine image(s) icon (Combine image(s)).
  3. In the Create New Image dialog box, check Add IPL.

    Create new image

  4. Enter the IPL filename (or select it by clicking the browse icon).
  5. In the Pad IPL to: field, select padding equal to or greater than the size of your IPL.

    Caution: If the padding is less than the size of the IPL, the image won't contain the complete IPL.

  6. Click OK.

Note: If you get a “File Not Found” error while building, make sure the Build with profiling option is unchecked in all of the C/C++ projects in the BSP working set, and then rebuild all of the projects.

Right-click on a project, then choose Properties and select QNX C/C++ Project to view the Build with profiling setting.


Adding an EFS to your image

To append a flash filesystem to your image:

  1. In the Create New Image dialog, check Append Image(s).
  2. In the Align to field, select the granularity of the padding. The padding is a multiple of your selected alignment.
  3. Click OK.

Setting the final format of your OS image

You'll use the Final Processing section of the Create New Image dialog to set the final format for your image:

  1. In the Create New Image dialog, check the Final Processing box.
  2. In the Offset field, enter the board-specific offset. This setting is generally used for S-Record images.
  3. In the ROM size field, enter the size of the ROM.
  4. In the Format field, select the format from the dropdown menu (e.g. SREC, Intel hex records, binary.)
  5. Click OK.

For more information of the final processing of an OS image, see mkrec in the Utilities Reference.

Downloading an image to your target

Many boards have a ROM monitor, a simple program that runs when you first power on the board. The ROM monitor lets you communicate with your board via a command-line interface (over a serial or Ethernet link), download images to the board's system memory, burn images into flash, etc.

The QNX System Builder has a TFTP server that you can use to communicate with your board.


Note: If your board doesn't have a ROM monitor, you probably can't use the download services in the IDE; you'll have to get the image onto the board some other way (e.g. JTAG). To learn how to connect to your particular target, consult your hardware and BSP documentation.

Downloading

The QNX System Builder includes a built-in TFTP server, you don't need to leave the IDE and open a serial communications program (e.g. HyperTerminal) in order to talk to your target, download images, etc.

Using the Terminal view, you can:

Opening a terminal

To open a terminal:
From the main menu, select Show View-->Other…, and then select QNX System Builder-->TFTP Server.

The Terminal view lets you set standard communications parameters (baud rate, parity, data bits, stop bits, and flow control), choose a port (COM1 or COM2), send a BREAK command, and so on.

To communicate with your target

To communicate with your target over a serial connection:

  1. Connect your target and host machine with a serial cable.
  2. Specify the device (e.g. COM 2) and the communications settings in the view's menu:

    The Terminal view

You can now interact with your target by typing in the view.


Note:

By default on Linux hosts, the owner (root) and the group (uucp) have read-write permission on all /dev/ttyS* serial devices; users outside this group have no access.

If you're logged in as a non-root user, and you aren't a member of the uucp group, then the Terminal view doesn't show any serial devices to select from, since you don't have access rights to any of them. To work around this problem, add non-root users to the uucp group.


Using the QNX Send File button

When a connection is made, the Send File button changes to its enabled state (Send file icon), indicating that you can now transfer files to the target.

To transfer a file using the Terminal view:

  1. Using either the Terminal view or another method (outside the IDE), configure your target so that it's ready to receive an image. For details, consult your hardware documentation.
  2. In the Terminal view, click the Send File button (Send file icon).
  3. In the Select File to Send dialog, enter the name of your file (or click Browse).
  4. Select a protocol (e.g. sendnto).

    Note: The QNX sendnto protocol sends a sequence of records (including the start record, data records, and a go record). Each record has a sequence number and a checksum. Your target must be running an IPL (or other software) that understands this protocol.

  5. Click OK. The QNX System Builder transmits your file over the serial connection.

Note: You can click the Cancel button to stop the file transfer:

Cancel file transfer icon


Downloading using TFTP

The QNX System Builder's TFTP server eliminates the need to set up an external server for downloading images (if your target device supports TFTP downloads). The TFTP server knows about all QNX System Builder projects in the system and automatically searches them for system images whenever it receives requests for service.

When you first open the TFTP Server view (in any perspective), the QNX System Builder starts its internal TFTP server. For the remainder of the current IDE session, the TFTP server listens for incoming TFTP transfer requests and automatically fulfills them.

The TFTP Server view provides status and feedback for current and past TFTP transfers. As the internal TFTP server handles requests, the view provides visual feedback:


TFTP Server view


The TFTP Server view shows the current and past TFTP transfers.

Each entry in the view shows:

Transferring a file

To transfer a file using the TFTP Server view:

  1. Open the Terminal view. The internal TFTP server starts.
  2. Using the QNX System Builder's TFTP terminal, configure your target to request a file recognized by the TFTP server. (The TFTP Server view shows your host's IP address.) During the transfer, the view shows your target's IP address, the requested file, and the transfer status.

You can clear the TFTP Server view of all completed transactions by clicking its clear button (Icon: Clear TFTP view).


Note: The internal TFTP server recognizes files in the Images directory of all open QNX System Builder projects; you don't need to specify the full path.

Transferring files that aren't in Images


Caution: The IDE deletes the content of the Images directory during builds — don't use this directory to transfer files that the QNX System Builder didn't generate. Instead, configure a new path, as described in the following procedure.

To enable the transfer of files that aren't in the Images directory:

  1. From the main menu, select Window-->Preferences.
  2. In the left pane of the Preferences dialog, select QNX-->Tftp Server-->User Search Paths.
  3. Click New, and then select your directory from the Add New Search Path dialog.
  4. Click OK.
  5. Click OK. The TFTP server is now aware of the contents of your selected directory.

Transferring an image

To transfer an image to the target machine:
From the Terminal view toolbar, select Transfer image to target icon.

Settings for the TFTP server

To configure settings for a terminal:
From the Terminal view toolbar, select the Connect icon (Icon: Connect icon).

TFTP view settings

Setting font and color preferences

To set font and color preferences for a terminal:
From the main menu, select Window-->Preferences-->General-->Appearance-->Colors and Fonts, and then select Terminal Console Font.

Setting font and color preferences

Downloading using other methods

If your board doesn't have an integrated ROM monitor, you may not be able transfer your image over a serial or TFTP connection. You'll have to use some other method instead, such as:

For more information, see the documentation that came with your board.

Configuring your QNX System Builder projects

In order to use the QNX System Builder to produce your final embedded system, you'll likely need to:

As mentioned earlier, every QNX System Builder project has a project.bld file that contains information about your image's boot script, all the files in your image, and the properties of those files.

If you double-click the project.bld, you'll see your project's components in the Images and Filesystem panes in the editor area, as well as a Properties view:

Builder editor and properties

Managing your images

The Images pane shows a tree of all the files in your image, sorted by type:


Note:

The System Builder can determine which shared libraries are required since it inspects the NEEDED section for the binaries. Since DLL's don't get listed in the NEEDED section, they're not automatically included. If they exist in the NEEDED section, every DLL would have to be linked into every server (i.e. io-net would have to load every driver at runtime, as well as every protocol stack.) Alternately, you'll have to rebuild everything to specify all of the libraries you're using. Ensure that you include the proper driver; otherwise, you'll have to rebuild.


Determining the shared libraries and DLLs are required for an executable

To determine which shared libraries are required, you'll need to look at the NEEDED section. For DLL's, see Optimizing your system.” For the most common cases, use the following:


Note: The QNX System Builder won't automatically include the necessary DLLs as these aren't listed in the NEEDED section for a given binary.

Finally, you can use the Korn shell, and include DL_DEBUG=1 in your command line to print the list of libraries and DLLs being loaded at program startup. If you don't have a library that's being opened or resolved, you'll receive an error message.

Adding files to your image

When you add files, you can either browse your host filesystem or select one or more files from a list of search paths:

Browse method
If you choose files by browsing, you'll probably want to configure the project to use an absolute path so that the IDE always finds the exact file you specified (provided you keep the file in the same location). Note that other users of your project would also have to reproduce your setup in order for the IDE to locate files.
Select method
Select files from a preconfigured list of search locations. We recommend that you use this option because it's more flexible and lets others easily reproduce your project on their hosts. You can add search paths to the list.

Note that the IDE saves only the filename. When you build your project, the IDE follows your search paths and uses the first file that matches your specified filename. If you specify a file that isn't in the search path, the build will be incomplete. To learn how to configure your search paths, see the section Configuring project properties in this chapter.

To add items to your image:

  1. In the Images pane, right-click the image and select Add Item, followed by the type of item you want to add:
  2. Select an item (e.g. Binary) from the list.
  3. Select either the Search using the project's search paths or the Use selected absolute path(s) option. (We recommend using search paths, because other users will be able to recreate your project more easily.)
  4. Click OK. The QNX System Builder adds the item to your image, as you can see in the Images pane.

Deleting files

To delete files:
In either the Images or Filesystem pane, right-click your file and select Delete.

Adding directories

To add a directory to your image:

  1. In the Filesystem pane, right-click the parent directory and select Add Item-->Directory.
  2. Specify the directory name, path, and image name. Some fields are filled in automatically.
  3. Click OK. Your directory appears in the Filesystem pane.

Note: You can also add a directory by specifying the path for an item in the Location In Image field in the Properties view. The IDE includes the specified directory as long as the item remains in your image.

Deleting directories

To delete directories:
In either the Images or Filesystem pane, right-click your directory and select Delete.

Note: A deleted directory persists if it still contains items. To completely remove the directory, delete the reference to the directory in the Location In Image field in the Properties view for all the items in the directory.

Configuring image properties

The Properties view lets you see and edit the properties of an image or any of its items. Note that the properties associated with IFS and EFS images differ slightly. For an IFS image, right-click on the image name and click Show Properties to see these properties:

System Builder properties for an IFS image

If you right-click on the libc.so item under Shared Libraries, you'll see these properties:

General properties for libc.so

For an EFS image, you'll see these properties:

System Builder properties for an EFS image

To change the properties of an image or item:

  1. In the Images or Filesystem pane, select an image or one of its items.
  2. In the Properties view, select an entry in the Value column. The value is highlighted; for some fields (e.g. CPU Type), a dropdown menu appears.
  3. Type a new value or select one from the dropdown menu.
  4. Press Enter.
  5. Save your changes.
  6. Rebuild your project.

Image and item properties

Different properties appear for images and for the items in an image:

Image properties

Combine

These settings control how images are combined with your System Builder project. For example, you can control how the EFS is aligned, what format the resulting image is, the location of the IPL, its image offset, and whether or not the IPL is padded to a certain size or not.

IPL file
The fully qualified name of a file that is concatenated to the front of an IFS image.
Pad IPL to
The amount of padding that is required for the IPL file you want to append to the front of an IFS image. If you need to accommodate an IPL file, the IPL plus the padding amount will provide the start of the IFS image.
Align file system to
Indicates the sector size that you want to align the file system to. Use this setting if you want to combine an EFS image. This image must be aligned to a sector size for the hardware (NOR flash).
Offset
A hexadecimal amount that indicates the distance (displacement) from the beginning of the image up until the IFS image starts.
ROM size
A numerical value for the size of the ROM. To determine the amount of ROM you'll require, you can compile the code to create a hexadecimal file of the code, and then the size of the hexadecimal file is the size of the ROM you require.
Combined image format
Indicates the type of image format. If you want to download to the target, the resulting file will be copied to the type specified here.
Images to combine with
A list of the fully-qualified file names for the IFS and EFS images. The IFS and EFS images are appended in the order specified in this comma-separated list.
Mount unbootable IFSs?
Indicates whether you want any specified IFS images mounted when they are unbootable. For advanced situations, if you might have multiple IFS filesystems, and because only the ones with a startup are bootable, you might want any secondary IFSs mounted, regardless if they are not bootable.

Directories

These settings control the default permissions for directories that you add to the image, as well as for any directories that the tools create when you build your system. For example, if you add /usr/bin/ksh to your system, the IDE automatically creates the usr and bin directories. (For more information on permissions, see the Managing User Accounts chapter in the Neutrino User's Guide and the chmod entry in the Utilities Reference.)

Note that the values for permissions are given in octal (e.g. 777, which means the read, write, and execute bits are set for the user, group, and other categories).

General

Create Image
If Yes, the IDE builds this image when you build your project.
Remove File Time Stamps?
If Yes, file timestamps are replaced by the current date/time.
Image Name
Name of the .ifs file saved in the Images directory during a build.
CPU Type
Your target's processor (e.g. armle).
Page Align Image?
If Yes, files in the image are aligned on page boundaries.
Image Mount Point
The path where the filesystem is mounted in the filesystem. By default, the location is /proc/boot.
Default Target Location
The default path where the filesystem is located when the boot process completes. By default, the location is /proc/boot.
Compressed (.ifs only)
If set to something other than No, the QNX System Builder compresses the directory structure (image filesystem) section of the image. The directory structure includes procnto, the boot script, and files. You might enable compression if you want to save on flash space or if the BIOS/ROM monitor limits the size of your image.
Boot Script (.ifs only)
Name of the file that contains the boot script portion of a buildfile. Boot script files have a .bsh extension (e.g. prpmc800.bsh).

System (.ifs)

Auto Link Shared Libs?
If Yes, shared libraries referenced by the image's binaries are automatically included in the image.
Create startup sym file?
If Yes, include the system startup code. The default is No.
Create proc sym file
If Yes, include debugging symbol files for procnto. The default is No.
Procnto
Which procnto binary to use (e.g. procnto-600, procnto-600-smp, etc.).
Procnto Arguments
Command-line arguments for procnto.
Procnto $PATH
Path(s) where procnto should look for executables. Separate the paths with a colon (:).
Procnto $LD_LIBRARY_PATH
Path(s) where procnto should look for shared libraries. Separate the paths with a colon (:).
Image Address
The base address where the image is copied to at boot time. For execute-in-place (XIP), set this to the same location as your image file on flash memory and specify the read/write memory address with the RAM Address value, described below.
Use APS?
If Yes, the System Builder adds the aps module to the invocation of procnto in the OS image. You need this module if you want to use adaptive partitioning on the target system.

To create partitions and run programs in them at boot time, add the appropriate commands to the image's .bsh file. For more information, see Boot script earlier in this chapter.

Startup
Which startup binary to use (e.g. startup-bios, startup-rpx-lite, etc.).
Startup Arguments
Command-line arguments for the startup program.
Boot File
The image filter that the QNX System Builder uses (e.g. srec, elf) to perform further processing on the image file. For example, srec converts the image to the Motorola S-Record format. (For more about image filters, see mkifs in the Utilities Reference.)
RAM Address
The location of your read/write memory. For XIP, set the address; otherwise, set the value to Default. (Note that RAM Address is the ram attribute in the mkifs utility.)

System (.efs)

These settings control the format and size of your flash filesystem image. Unless otherwise specified, the values are in bytes, but you can use the suffixes K, M, or G (e.g. 800, 16K, 2M, 4G). The IDE immediately rejects invalid entries.

Block Size
The size of the blocks on your flash.
Filesystem Type
The type of flash filesystem to create. Use the default (ffs3) unless you specifically need compatibility with older software that requires ffs2 format images.
Filter
A filter you can use with this image, called deflate, compresses files for flash filesystems. (The mkefs utility calls deflate.) Use any valid command-line argument, such as deflate -t1.
Maximum Image Size
The limit for the size of the generated image. If the image exceeds the maximum size, mkefs fails and reports an error in the System Builder Console view. The default setting of 4 GB accommodates most images.
Minimum Image Size
The minimum size of the embedded filesystem. If the size of the filesystem is less than this size after all the specified files have been added, then the filesystem is padded to the required size. The default is 0 (i.e. no padding occurs).
Spare Blocks
The number of spare blocks to be used by the embedded filesystem. If you want the embedded filesystem to be able to reclaim the space taken up by deleted files, set the number of spare blocks to 1 or more. The default is 1.

Item properties

General

Absolute Location on Host
The absolute location for this item's data on the host. By default, if you add a binary from the workspace or filesystem, the absolute path for the file automatically shows in the Absolute Location on Host property. If you add a binary devc-serpsc from QNX_TARGET where the BSP is installed, the absolute path would show as QNX_TARGET/ppcbe/sbin, where QNX_TARGET is the default absolute path (i.e., for Windows it would be C:\QNX641\target\qnx6). If you add a binary using the default search path, the Absolute Location on Host field will be empty because the IDE already knows the location of the file. For more information, see Creating a project for an OS image.”
Include In Image
If Yes, the QNX System Builder includes this item when it builds the image.
Optional Item?
If Yes, this item is considered optional. It's excluded from the image if the image is too large to fit in the architecture-specific maximum image size.
Filename
The name of the file for this item (e.g. devc-ser8250). The filename property refers to the filename of the item in the target image. The default is the same as Filename on Host, but you can rename it.
Location In Image
The directory where the item lives. If you change this setting, the directory location shown in the Filesystem pane changes as well.

Note:

Symbolic links also have a Linked To field for the source file.

A deleted directory persists if it still contains items. To completely remove the directory, delete the reference to the directory in the Location In Image field in the Properties view for all the items in the directory.


Absolute Location on Host
The fully-qualified directory where the item resides. You browse to a directory to set this location.
Filename on host
The filename of the item on the host development system being included in the image.
Strip File
By default, mkifs strip debugging information from executable files that you include in the image. Doing this helps reduce the size of the image. To keep this information, select No. See mkifs (especially the +raw attribute) and strip in the Utilities Reference.

Memory

Use these two settings (which apply to .ifs files only) to specify whether a program's code and data segments should be used directly from the image filesystem (Use In Place) or copied when invoked (Copy). For more information, see the code attribute in the mkifs documentation.

Data Segment
Copy this item's data segment into main memory, or Use In Place to use it directly from the image.
Code Segment
Copy this item's code segment into main memory, or Use In Place to run the executable directly from the image.

Permissions

Use these settings to specify the read/write/execute permissions (in octal) assigned to each item, as well as the item's group and user IDs.

File Permissions
A three digit octal number that specifies the read, write, and execute permissions assigned to files.
Group ID
The ID of the group. The /etc/password file contains the mapping information for the name (the corresponding group name and group number). The root is always 0.
User ID
The ID associated with a user. The /etc/group file contains the mapping information for the user ID (the corresponding user name, user number, and group number). The root is always 0.

Configuring project properties

The Properties dialog for your QNX System Builder project (right-click the project, and then select Properties) lets you view and change the overall properties of your project. For example, you can add dependent projects and configure search paths.

The dialog includes the following sections:


Note: For information on external tools, follow these links in the Eclipse Workbench User Guide: Tasks-->Building resources-->Running external tools.

Search Paths

The Search Paths pane lets you configure where the IDE looks for the files you specified in your project.bld file:

Properties dialog; Search Paths

The IDE provides separately configurable search paths for:

To add a search path:

  1. In the Navigator or System Builder Projects view, right-click your project and select Properties.
  2. In the left pane, select Search Paths.
  3. In the right pane, select one of the following tabs:
  4. Click one of the following buttons:

    Another dialog appears.

  5. Select your path or project and click OK. The IDE adds your path to the end of the list.

To manage your search paths:

  1. In the Search Path section of the Properties dialog, select one of the following tabs:
  2. Select a path, then click one of these buttons:

    Caution: The Overrides/image_name and Overrides directories must be first ones in the list. The Reductions/image_name and Reductions directories, which are listed in the Shared Libraries tab, must be next in the list.

    Changing the order of the Overrides or Reductions directories may cause unexpected behavior.


  3. Click OK.

Search path variables

You can use any of the following environment variables in your search paths; these are replaced by their values during processing:

Optimizing your system

Since “less is better” is the rule of thumb for embedded systems, the QNX System Builder's System Optimizer and the Dietician help you optimize your final system by:


Caution: If you reduce a shared library, and your image subsequently needs to access binaries on a filesystem (disk, network, etc.) that isn't managed by the QNX System Builder, then the functions required by those unmanaged binaries may not be present. This causes those binaries to fail on execution.

In general, shared-library optimizers such as the Dietician are truly useful only in the case of a finite number of users of the shared libraries, as you would find in a closed system (i.e. a typical embedded system).

If you have only a small number of unmanaged binaries, one workaround is to create a dummy flash filesystem image and add to this image the binaries you need to access. This dummy image is built with the rest of the images, but it can be ignored. This technique lets the Dietician be aware of the requirements of your runtime system.


Optimizing all libraries in your image

To optimize all the libraries in an image:

  1. In the Navigator or System Builder Projects view, double-click your project's project.bld file.
  2. In the toolbar, click the Optimize System button (Icon: Optimize System).
  3. In the System Optimizer, select the optimizations that you want to make:
    Remove unused libraries
    When you select this option, the Dietician inspects your entire builder project and ensures that all shared libraries in the system are required for proper operation. If the QNX System Builder finds libraries that no component in your project actually needs, you'll be prompted to remove those libraries from your project.
    Add missing libraries
    This option causes the Dietician to inspect your entire project for missing libraries. If any binaries, DLLs, or shared libraries haven't met load-time library requirements, you'll be prompted to add these libraries to your project.
    Apply diet(s) system wide
    This option runs the Dietician on all the libraries selected. The diets are applied in the proper order so that runtime dependencies aren't broken. If you were to do this by hand, it's possible that the dieting of one shared library could render a previously dieted shared library nonfunctional. The order of operations is key!

    Note: To ensure that your image works and is as efficient as possible, you should select all three options.

  4. Click Next. On the next three pages, you'll see a list of the libraries scheduled to be removed, added, or put on a diet. Uncheck the libraries that you don't want included in the operation, then move to the next page.
  5. Click Finish. The System Optimizer optimizes your libraries; the reduced libraries appear in your project's Reductions/image_name directory.

Optimizing a single library

Optimizing a single library doesn't reduce the library as effectively as optimizing all libraries simultaneously, because the System Optimizer accounts for dependencies.

To reduce a library such as libc using the Dietician, you must iteratively optimize each individual library in your project between two and five times (depending on the number of dependency levels).

You can reduce a single library to its optimum size if it has no dependencies.

To optimize a single library in an image:

  1. If your project isn't already open, double-click its project.bld file in the Navigator or System Builder Projects view.
  2. In the QNX System Builder editor, expand the Shared Libraries list and select the library you want to optimize.
  3. In the toolbar, click the Optimize System button (Icon:  Optimize System).
  4. In the System Optimizer, select the Apply diet(s) system wide option.
  5. Click Next. In the next few pages, the Dietician shows the unnecessary libraries, any additional needed libraries, and the libraries that can be optimized.
  6. Click Finish. The Dietician removes unused libraries, adds the additional required libraries, and generates new, reduced libraries. Reduced libraries are added to your project's Reductions/image_name directory.

Restoring a slimmed-down library

If after reducing a library, you notice that your resulting image is too “slim,” you can manually remove the reduced library from the Reductions directory, and then rebuild your image using a standard, “full-weight” shared library.

To restore a library to its original state:

  1. In the Navigator or System Builder Projects view, open the Reductions directory in your project. This directory contains the reduced versions of your libraries.
  2. Right-click the library you want to remove and select Delete. Click OK to confirm your selection. The IDE deletes the unwanted library; when you rebuild your project, the IDE uses the original version of the library.

Moving files between the host and target

The IDE's Target File System Navigator view lets you easily move files between your host and a filesystem residing on your target.


Note: If you haven't yet created a target system, you can do so right from within the Target File System Navigator view.
To create a target system:
Right-click anywhere in the view, then select Add New Target.

Note that the Target File System Navigator view isn't part of the default QNX System Builder perspective; you must manually bring the view into your current perspective.

To see the Target File System Navigator view:

  1. From the main menu, select Window-->Show View-->Other….
  2. Select QNX Targets, then double-click Target File System Navigator.

The view shows the target and directory tree in the left pane, and the contents of the selected directory in the right pane:

Target File System Navigator view


Note: If the Target File System Navigator view has only one pane, click the dropdown menu button (Icon: Dropdown menu) in the title bar, then select Show table. You can also customize the view by selecting Table Parameters or Show files in tree.

Moving files to the target

You can move files from your host machine to your target using copy-and-paste or drag-and-drop methods.

To copy files from your host filesystem and paste them on your target's filesystem:

  1. In a file-manager utility on your host (e.g. Windows Explorer), select your files, then select Copy from the context menu.
  2. In the left pane of the Target File System Navigator view, right-click your destination directory and select Paste.

Note: To convert files from DOS to Neutrino (or Unix) format, use the textto -l filename command. For more information, see textto in the Utilities Reference.

To drag and drop files to your target:
Drag your selected files from any program that supports drag-and-drop (e.g. Windows Explorer), then drop them in the Target File System Navigator view.

Moving files from the target to the host

To copy files from your target machine and paste them to your host's filesystem:

  1. In the Target File System Navigator view, right-click a file, then select Copy to-->File System. The Browse For Folder dialog appears.

    Note: To import files directly into your workspace, select Copy to-->Workspace. The Select Target Folder dialog appears.

  2. Select your desired destination directory and click OK.
To move files to the host machine using drag-and-drop:
Drag your selected files from the Target File System Navigator view and drop them in the Navigator or System Builder Projects view.