Building OS and Flash Images
|This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.|
You can select a topic from this diagram:
In this chapter:
- Introducing the QNX System Builder
- Overview of images
- Creating a project for an OS image
- Creating a project for a flash filesystem image
- Building an OS image
- Downloading an image to your target
- Configuring your QNX System Builder projects
- Optimizing your system
- Moving files between the host and target
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.
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 choice of importing/customizing an existing buildfile to generate an image or of creating one from scratch. The QNX System Builder editor lets you select which components (binaries, DLLs, libraries) 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, then the QNX System Builder knows to add libsocket.so in order to ensure that telnet can run. And when you select a binary, you'll see relevant information for that item, including its usage message, in the Binary Inspector view.
Using standard QNX embedding utilities (mkifs, mkefs), the QNX System Builder can generate configuration files for these tools that can be used outside of the IDE for scripted/automated system building. As you do a build, a Console view displays 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.
Here's what the QNX System Builder perspective looks like:
One of the main areas in the QNX System Builder is the editor, which presents two panes side by side:
- Shows all the images you're building. You can add or remove binaries and other components, view their properties, etc.
- Shows the components of your image arranged in a hierarchy, as they would appear in a filesystem on your target.
Above the Images and Filesystem panes in the editor you'll find several buttons for working with your image:
- Add a new binary.
- Add a new shared library.
- Add a new DLL.
- Add a new symbolic link.
- Add a new file.
- Add a new inline file (i.e. a file whose contents are specified in the buildfile).
- Add a new directory.
- Add a new image.
- Run the System Optimizer.
- Rebuild the current project.
- Merge two or more images into a single image.
Below the Images and Filesystem panes is the QNX Binary Inspector view, which shows the usage message for any binary you select:
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.
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.
|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.
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/remove items for the image you'll be building.
|As with most other tools in the IDE, you build your QNX System Builder projects using the standard Eclipse build mechanism via.|
You can use the QNX System Builder throughout your product-development cycle:
- At the outset -- to import a QNX BSP, generate a minimal OS image, and transfer the image to your board, just to make sure everything works.
- During development -- to create an image along with your suite of programs and download everything to your eval board.
- For your final product -- to strip out the extra utilities you needed during development, reduce libraries to their bare minimum size, and produce your final, customized, optimized embedded system.
|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.|
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
- Types of images you can create
- Project layout
- Overview of workflow
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.
|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:
- The IPL initializes the hardware, makes the OS image accessible, and then jumps into it.
- 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.
- The procnto module then runs the boot script, which performs any final setup required and runs your programs.
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.
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 as small as possible.
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.
|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 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.).
|If you're creating your own procnto variant, its name must start with procnto- or the QNX System Builder perspective won't recognize it.|
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:
- run a devf driver to access a flash filesystem image, and then run your program from that flash filesystem
- create adaptive partitions, run programs in them, and set their
# Create an adaptive partition named "Debugging" with a budget # of 20%: sched_aps Debugging 20 # Start qconn in the Debugging partition: [sched_aps=Debugging]/usr/sbin/qconn # Use the recommended security level for the partitions: aps modify -s recommended
For more information about these commands, see the Adaptive Partitioning User's Guide.
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.
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.
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|
|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.
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:
Generally, we recommend that you keep your OS image as small as possible to realize the following benefits:
- Memory conservation -- When the system boots, the entire OS image gets loaded into RAM. This image isn't unloaded from RAM, so extra programs and data built into the image require more memory than if your system loaded and unloaded them dynamically.
- Faster boot time -- Loading a large OS image into RAM can take longer to boot the system, especially if the image must be loaded via a network or serial connection.
- Stability -- Having a small OS image provides a more stable boot process. The fewer components you have in your OS image, the lower the probability that it fails to boot. The components that must go in your image (startup, procnto, a flash driver or network components, and a few shared objects) change rarely, so they're less subject to errors introduced during the development and maintenance cycles.
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 create a 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.
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:
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.
|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.
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.
|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.|
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.
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:
|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.|
Here are the main steps involved in using the IDE to get Neutrino up and running on your board:
- Creating a QNX System Builder project for an OS or a flash image for your board. The process is very simple if a BSP exists for your board. If an exact match isn't available, you may be able to modify an existing BSP to meet your needs.
- Building your project to create the image.
- Transferring the OS image to your board. You might do this initially to verify that the OS image runs on your hardware, and then again (and again) as you optimize your system.
- Configuring your projects.
- Optimizing your system by reducing the size of the libraries.
To create a new QNX System Builder Project:
- From the main menu, select .
- Expand QNX, then select QNX System Builder Project. Click Next.
- Name your project and click Next.
- At this point, you can either import an existing buildfile (as shipped with
your QNX BSPs) or select a generic type (e.g. "ppcbe").
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 drop-down list.
- Click Finish. The IDE creates your new project, which includes all the components that make up the OS image.
To create a flash filesystem project:
- From the main menu, select .
- Expand QNX, then select QNX System Builder EFS Project in the right. Click Next.
- Name your project and click Next.
- Specify your target hardware (e.g. "armle").
- 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.
- To build your QNX System Builder projects using the standard Eclipse build mechanism:
- From the main menu, select .
You can also build projects using the context menu:
- In the Navigator or System Builder Projects view, right-click the project.
- Select Build Project.
The System Builder Console view shows the output produced when you build your images:
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 ().
You can create a new image for your QNX System Builder project by using the Add New Image icon () in the System Builder editor's toolbar:
- Click the Add New Image icon in the toolbar.
The IDE displays the Create New Image dialog box:
- Use the Create New Image dialog to:
- Duplicate Selected Image -- create a duplicate of the currently selected image with the given name.
- Import Existing IFS Buildfile -- generate the new IFS image using an existing buildfile.
- Import Existing EFS Buildfile -- generate the new EFS image using an existing buildfile.
- Create Generic IFS image -- create an empty IFS for the specified platform.
- Create Generic EFS image -- create an empty EFS for the specified platform.
- Click OK to create the new image and add it to your project.
As mentioned earlier, the QNX System Builder lets you create a combined image. You use the Combine image(s) icon () to:
- add an IPL to the start of your image
- append an EFS to your image
- set the final format of your image
To add an IPL to the start of your image:
- In the Images view, select your image.
- Click the Combine image(s) icon ().
- In the Create New Image dialog box, check Add IPL.
- Enter the IPL filename (or select it by clicking the browse icon).
- In the Pad IPL to: field, select padding equal to
or greater than the size of your IPL.
If the padding is less than the size of the IPL, the image won't contain the complete IPL.
- Click OK.
|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, 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.
To append a flash filesystem to your image:
- In the Create New Image dialog, check Append Image(s).
- In the Align to field, select the granularity of the padding. The padding is a multiple of your selected alignment.
- Click OK.
You use the Final Processing section of the Create New Image dialog to set the final format for your image.
To change the final format of your OS image:
- In the Create New Image dialog, check the Final Processing box.
- In the Offset field, enter the board-specific offset. This setting is generally used for S-Record images.
- In the ROM size field, enter the size of the ROM.
- In the Format field, select the format from the dropdown menu (e.g. SREC, Intel hex records, binary.)
- Click OK.
For more information of the final processing of an OS image, see mkrec in the Utilities Reference.
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 two facilities you can use to communicate with your board:
- serial terminals (up to four)
- TFTP server
|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.|
With the QNX System Builder's built in serial terminals, 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.
The Terminal view implements a very basic serial terminal, supporting only the following control sequences: 0x00 (NUL), 0x07 (bell), 0x08 (backspace), 0x09 (horizontal tab), 0x0a (newline), and 0x0d (carriage return).
- To open a terminal:
- From the main menu, select , then select N (where N is 1 to 4).
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 over a serial connection:
- Connect your target and host machine with a serial cable.
- Specify the device (e.g. COM 2) and the communications
settings in the view's menu:
You can now interact with your target by typing in the view.
When a connection is made, the Send File button changes to its enabled state (), indicating that you can now transfer files to the target.
To transfer a file using the Serial Terminal view:
- Using either the Serial 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.
- In the Serial Terminal view, click the Send File button ().
- In the Select File to Send dialog, enter the name of your file (or click Browse).
- Select a protocol (e.g. sendnto).
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.
- Click OK. The QNX System Builder transmits your file over the serial connection.
|You can click the Cancel button to stop the file transfer:
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 fulfill them.
|Currently, the QNX System Builder's internal server supports only TFTP read requests; you can't use the server to write files from the target to the host development machine.|
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:
Each entry in the view shows:
- TFTP client IP address/hostname
- requested filename
- transfer progress bar
- transfer status message
To transfer a file using the TFTP Server view:
- Open the TFTP Server view. The internal TFTP server starts.
- Using either the QNX System Builder's serial terminal or another method, configure your target to request a file recognized by the TFTP server. (The TFTP Server view displays 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 ().
|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.|
|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:
- From the main menu, select .
- In the left pane of the Preferences dialog, select .
- Click New, and then select your directory from the Add New Search Path dialog.
- Click OK.
- Click OK. The TFTP server is now aware of the contents of your selected directory.
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:
- CompactFlash -- copy the image to a CompactFlash
card plugged into your host, then plug the card into your
board to access the image.
- Flash programmer -- manually program your flash
with an external programmer.
- JTAG/ICE/emulator -- use such a device to program and communicate with your board.
For more information, see the documentation that came with your board.
In order to use the QNX System Builder to produce your final embedded system, you'll likely need to:
- add/remove image items
- configure the properties of an image and its items
- configure the properties of the project itself
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:
The Images pane shows a tree of all the files in your image, sorted by type:
- shared libraries
- symbolic links
- other files
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:
- In the Images pane, right-click the image and select
Add Item, followed by the type of item you want to add:
- Shared Library
- Symbolic Link
- Inline File
- Select an item (e.g. Binary) from the list.
- 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 would be able to recreate your project more easily.)
- Click OK. The QNX System Builder adds the item to your image, as you can see in the Images pane.
- To delete files:
- In either the Images or Filesystem pane, right-click your file and select Delete.
To add a directory to your image:
- In the Filesystem pane, right-click the parent directory and select .
- Specify the directory name, path, and image name. Some fields are filled in automatically.
- Click OK. Your directory appears in the Filesystem pane.
|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.|
- To delete directories:
- In either the Images or Filesystem pane, right-click your directory and select Delete.
|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.|
The Properties view lets you see and edit the properties of an image or any of its items:
To change the properties of an image or item:
- In the Images or Filesystem pane, select an image or one of its items.
- 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.
- Type a new value or select one from the dropdown menu.
- Press Enter.
- Save your changes.
- Rebuild your project.
Different properties appear for images and for the items in an image:
- Image properties:
- Item properties:
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.
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).
- 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).
- 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.
- CPU Type
- Your target's processor (e.g. armle).
- Create Image
- If Yes, the IDE builds this image when you build your project.
- Default Target Location
- The default path where the filesystem is located when the boot process completes. By default, the location is /proc/boot.
- Image Mount Point
- The path where the filesystem is mounted in the filesystem. By default, the location is /proc/boot.
- Image Name
- Name of the .ifs file saved in the Images directory during a build.
- Page Align Image?
- If Yes, files in the image are aligned on page boundaries.
- Remove File Time Stamps?
- If Yes, file timestamps are replaced by the current date/time.
- Auto Link Shared Libs?
- If Yes, shared libraries referenced by the image's binaries are automatically included in the image.
- 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.)
- 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.
- Which procnto binary to use (e.g. procnto-600, procnto-600-smp, etc.).
- Procnto/Startup Symbol Files?
- If Yes, include debugging symbol files for procnto and the system startup code.
- Procnto $LD_LIBRARY_PATH
- Path(s) where procnto should look for shared libraries. Separate the paths with a colon (:).
- Procnto $PATH
- Path(s) where procnto should look for executables. Separate the paths with a colon (:).
- Procnto Arguments
- Command-line arguments for procnto.
- 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.)
- Which startup binary to use (e.g. startup-bios, startup-rpx-lite, etc.).
- Startup Arguments
- Command-line arguments for the startup program.
- 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.
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.
- The filter to use with this image, usually flashcmp. (The mkefs utility calls flashcmp.) You can use any valid command-line argument, such as flashcmp -t zip.
- 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.
- Absolute Location
- The offset in the image for this item's data, in bytes.
- The name of the file for this item (e.g. devc-ser8250).
- Image Name
- The name of the image in which this item resides.
- Include In Image
- If Yes, the QNX System Builder includes this item when it builds the image.
- 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.
Symbolic links also have a Linked To field for the source file.
- 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.
- Strip File
- By default, mkifs strips usage messages,
debugging information, and Photon resources 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.
Set this field to No if your image includes PhAB applications.
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.
- Code Segment
- Copy this item's code segment into main memory, or Use In Place to run the executable directly from the image.
- Data Segment
- Copy this item's data segment into main memory, or Use In Place to use it directly from the image.
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.
The Properties dialog for your QNX System Builder project (right-click the project, 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:
- Project Preferences
- Refactoring History
- Search Paths
|For information on external tools, follow these links in the Eclipse Workbench User Guide:.|
The Search Paths pane lets you configure where the IDE looks for the files you specified in your project.bld file:
The IDE provides separately configurable search paths for:
- shared libraries
- other files
- system files
To add a search path:
- In the Navigator or System Builder Projects view, right-click your project and select Properties.
- In the left pane, select Search Paths.
- In the right pane, select one of the following tabs:
- Shared Libraries
- Other Files
- System Files
- Click one of the following buttons:
- Add Absolute Path -- a hard-coded path
- Add QNX_TARGET Path -- a path with a $QNX_TARGET prefix
- Add Workspace Path -- a path with a $WORKSPACE prefix
- Add Project Path -- a path with a $WORKSPACE/projectName prefix
Another dialog appears.
- Select your path or project and click OK. The IDE adds your path to the end of the list.
To manage your search paths:
- In the Search Path section of the Properties
dialog, select one of the following tabs:
- Shared Libraries
- Other Files
- System Files
- Select a path, then click one of these buttons:
- Move Up
- Move Down
- Remove Selected
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.
- Click OK.
You can use any of the following environment variables in your search paths; these are replaced by their values during processing:
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:
- reducing the size of shared libraries for your image
- performing system-wide optimizations to remove unnecessary shared libraries, add required shared libraries, and reduce the size of all shared libraries in the system
|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
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.
To optimize all the libraries in an image:
- In the Navigator or System Builder Projects view, double-click your project's project.bld file.
- In the toolbar, click the Optimize System button ().
- 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!
To ensure that your image works and is as efficient as possible, you should select all three options.
- 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.
- Click Finish. The System Optimizer optimizes your libraries; the reduced libraries appear in your project's Reductions/image_name directory.
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:
- If your project isn't already open, double-click its project.bld file in the Navigator or System Builder Projects view.
- In the QNX System Builder editor, expand the Shared Libraries list and select the library you want to optimize.
- In the toolbar, click the Optimize System button ().
- In the System Optimizer, select the Apply diet(s) system wide option.
- Click Next. In the next few pages, the Dietician shows the unnecessary libraries, any additional needed libraries, and the libraries that can be optimized.
- 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.
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:
- In the Navigator or System Builder Projects view, open the Reductions directory in your project. This directory contains the reduced versions of your libraries.
- 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.
The IDE's Target File System Navigator view lets you easily move files between your host and a filesystem residing on your target.
|If you haven't yet created a target system, you can do so
right from within the Target File System Navigator view.
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:
- From the main menu, select .
- Select QNX Targets, then double-click Target File System Navigator.
The view displays the target and directory tree in the left pane, and the contents of the selected directory in the right pane:
|If the Target File System Navigator view has only one pane, click the dropdown menu button () in the title bar, then select Show table. You can also customize the view by selecting Table Parameters or Show files in tree.|
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:
- In a file-manager utility on your host (e.g. Windows Explorer), select your files, then select Copy from the context menu.
- In the left pane of the Target File System Navigator view, right-click your destination directory and select Paste.
|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.
Drag-and-drop is not supported on Neutrino hosts.
To copy files from your target machine and paste them to your host's filesystem:
- In the Target File System Navigator view, right-click a file,
To import files directly into your workspace, select. The Select Target Folder dialog appears.
. The Browse For Folder dialog appears.
- 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.
Drag-and-drop is not supported on Neutrino hosts.