[Previous] [Contents] [Index] [Next]

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

Working with a BSP

In this chapter...

Once you've installed the QNX Momentics development suite, you can download processor-specific Board Support Packages (BSPs) from our website, http://www.qnx.com/. These BSPs are designed to help you get Neutrino running on certain platforms.

A BSP typically includes the following:

The BSP is contained in an archive named after the industry-recognized name of the board and/or reference platform that the BSP supports. BSP packages are available for QNX Neutrino, Windows, Solaris, or Linux hosts. If your board includes flash, you'll also need the Flash Filesystem & Embedding Technology Development Kit (TDK).

You can build a BSP from the source code or the binary components contained in the BSP package.

Proprietary and simplified packaging for BSPs

We provide BSP packages in both proprietary and simplified styles.

Here's how to determine which style a BSP is:

The sections that follow point out any other differences between the styles.

Installing proprietary BSP source code

When you install a proprietary BSP, the binaries are copied to the appropriate directory under $QNX_TARGET, potentially overwriting binaries placed there by other BSPs.

The source code (if included) is a zip file that's placed in $QNX_TARGET/usr/src/archives/qnx. To install the source for a proprietary BSP, you must manually expand its directory structure from this archive.

If you aren't using the IDE and you want to manually install a BSP archive, we recommend that you create a default directory with the same name as your BSP and unzip the archive from there:

  1. Change the directory to where you want to extract the BSP (e.g. /home/joe).
    Note: The archive will extract to the current directory, so you should create a directory specifically for your BSP.

    For example:

    mkdir /home/joe/bspname

  2. In the directory you've just created, extract the BSP:
    unzip $QNX_TARGET/usr/src/archives/qnx/bspname.zip

Each BSP is rooted in whatever directory you copy it to. If you type make within this directory, you'll generate all of the buildable entities within that BSP no matter where you move the directory.

Proprietary BSPs include a setenv script that you must run so that typing make or make install doesn't affect the host system. If you use this script, all binaries are placed in an install area within the BSP directory that mimics the layout of a target system.

When you build a BSP, everything it needs, aside from standard system headers, is pulled in from within its own directory. Nothing that's built is installed outside of the BSP's directory. The makefiles shipped with the BSPs copy the contents of the prebuilt directory into the install directory. The binaries are built from the source using include files and link libraries in the install directory.

Structure of a BSP

If you install a simplified BSP, or a proprietary BSP that includes source code, the resulting directory structure looks like this:


BSP directory tree


BSP directory structure.


In our documentation, we refer to the directory where you've installed a BSP (e.g. /home/myID/my_BSPs/integrator) as the bsp_working_dir. Depending on what's shipped in the BSP, this directory could include the following subdirectories:

docs subdirectory (simplified BSPs only)

The docs subdirectory contains the documentation for the BSP. The setupbsp script copies the documentation to $QNX_TARGET/usr/help/product, so that it will automatically appear in the Photon helpviewer.

images subdirectory

The images subdirectory is where the resultant boot images are placed. It contains (as a minimum) the Makefile needed to build the image(s). Other files that could reside in this directory include:

prebuilt subdirectory

The prebuilt subdirectory contains the binaries, system binaries, buildfiles, libraries, and header files that are shipped with the BSP.

Before the BSP is built, all of the files from the prebuilt directory are copied into the install directory, maintaining the path structure.

In order to handle dependencies, the libraries, headers, and other files found in the ./prebuilt directory need to be copied correctly to your ./install directory. To do this, you'll need to run make at the bsp_working_dir directory level.

The "root" of the prebuilt directory requires the same structure as the system root. The target-specific and usr directories mirror the structure of /.


Note: All processor-specific binaries are located under the directory named for that processor type.

For example, the prebuilt directory might look like this:


Sample prebuilt directory


A sample prebuilt directory.


install subdirectory

The install directory gets populated at the beginning of the BSP build process. All the files in the prebuilt directory are copied, then all generated binaries are installed here as they're compiled. The files stored in the install directory are taken first when mkifs executes.

Before you make any components for your particular board, you must first make the BSP sources at the top level:

cd bsp_working_dir
make

This builds everything under ./src and sets up the ./install directory correctly.

After this initial build is complete, you can build any of the source files individually.


Note: If you change a library or header, be sure to run make install to rebuild the source and copy the changes to your ./install directory.

src subdirectory

If the BSP includes source code, it's stored in this directory. The hardware directory contains separate directories for character, flash, and network drivers, IPL, startup code, and so on, depending on the BSP.


Note: The src directory contains a buildfile, src/hardware/startup/boards/board/build, that overrides the one in the prebuilt directory.

Building a BSP OS image from source

If you're building the BSP OS image from source code on the host, you can:


Note: When you build a BSP from the source code, you may occasionally observe warnings from some of the tools used to generate the BSP, such as:
  • objcopy: Warning: Output file cannot represent architecture UNKNOWN!
  • ntosh-ld: Warning: could not find any targets that match endianness requirement

These warnings result when information that's contained in one particular file format (endianness, CPU architecture, etc.) can't be retained when converting that file to a different format, or when the originating file format doesn't contain information that the tool doing the conversion expects. These warnings are normal and expected, and are no cause for concern.


Building source from the command line

In order to build a BSP from the command line, you must go to the root directory for the BSP.


Note: Building the source is similar for proprietary and simplified BSPs, except that for a proprietary BSP, you must run the setenv.sh script in the BSP's root directory. This script configures your environment to build the BSP. On Windows, you must run the Bash shell (bash.exe) before you run setenv.sh.

Run the setenv.sh script as a "dot" file, so that it configures your current shell:

. ./setenv.sh

Simplified BSPs don't include setenv.sh; we've included it in the Makefile.


Use the make command to build the source code. The Makefile defines the following targets:

all
Invokes the install, links, and images targets.
prebuilt
This recursively copies the prebuilt directory's contents (including a buildfile) to the install directory.
install
Invokes the prebuilt target. If the BSP includes the source code, this target then performs the following in the src directory:
links
Creates a symbolic link (a copy on Windows) from install/cpu/boot/build/board.build to images/board.build.
images
Changes to the images directory and runs the Makefile there. This Makefile creates an IFS file based on the buildfile linked in during the make links target. Any extra work required (e.g. IPL padding, conversion to an alternate format) is also handled from within this Makefile.

If you don't specify a target, make invokes the all target.


Note: We recommend that you use make to build the OS image. If you use mkifs directly, you need to use the -r option to specify where to find the binaries. For more information, see the entry for mkifs in the Utilities Reference.

Building source within the IDE

To build a BSP, you must first import the source code into the IDE. When you import the BSP source, the IDE creates a System Builder project.

To import the BSP source code:

  1. Select File-->Import.
  2. Select QNX Board Support Package from the list. Click Next.
  3. Choose the BSP you want. You'll see a description of the BSP you've chosen.
  4. Click Next.
    Note: If you want to add more packages to the list, click the Select Package... button and select the .zip archive you want.

  5. Uncheck the entries you don't want. (By default all the entries are selected.)
  6. Click Next.
  7. Select a working set. Default names are provided for the Working Set Name and the Project Name Prefix that you can override if you choose.
  8. Click Finish. All the projects will be created and the sources brought from the archive. You'll then be asked if you want to build all the projects you've imported.

    If you answer Yes, the IDE will start the build process. If you decide to build at a later time, you can do a Rebuild All from the main Project menu when you're ready to build.


    Note: When you import a QNX BSP, the IDE opens the QNX BSP Perspective. This perspective combines the minimum elements from the C\C++ Development Perspective and the System Builder Perspective.

    For more information, see the IDE User's Guide in your documentation set. (Within the IDE itself, go to: Help-->Help Contents-->QNX Documentation Roadmap).


Building a BSP OS image from the binary components

If you're building a BSP OS image from the binary components on the host, you can use:

Building an image from the command line (simplified BSPs)

Once you've installed a simplified binary-only BSP, you can build it by using the same make targets as for one with source code; see "Building source from the command line," earlier in this chapter.

Building an image from the command line (proprietary BSPs)

After you've installed a proprietary binary-only BSP, you can build the BSP OS image from the command line:

  1. Change directories to:

    $QNX_TARGET/processor_type/boot/build

    where processor_type is the BSP board type, e.g. ppcbe.

  2. Enter:
    mkifs -vvvv BSP-buildfile-name OS-image-name

    For example:

    mkifs -vvvv integrator.build integrator.ifs

    Note that after you enter the command, the BSP OS image is generated, and the contents of the buildfile appear in the display terminal.

Building an image in the IDE

To build a BSP OS image from the binary components in the IDE:

  1. Start the IDE.
  2. Select File-->New-->Project.
  3. Select QNX in the left column, then QNX System Builder Project in the right column. Click Next.
  4. Name your project (e.g. Integrator) and click Next.
  5. Leave the default location as it is (e.g. workspace/Integrator).
  6. Click Next.
  7. Choose Import Existing Buildfile.
  8. Click Browse to locate and select the buildfile to import (e.g. integrator.build).
  9. Click Finish. The BSP OS image is automatically generated and your project (e.g. "Integrator") appears within the QNX System Builder window.

Creating a working set

You can optionally create a working set in order to select from a list of BSP projects.

To create a working set:

  1. In the System Builder Projects view, click the menu dropdown button (Icon; menu dropdown).
  2. Click Select Working Set..., then click New.
  3. Select QNX Sources.
  4. Click Next.
  5. Enter a Working set name and check the entry for the Working set contents. Typically this will be the BSP you've just imported.
  6. Click Finish. Note that the Finish button is available only after you choose a Working set contents entry.
  7. Click OK.

Supporting additional devices

All boards have some devices, whether they're input, serial, flash, or PCI. Every BSP includes a buildfile that you can use to generate an OS image that will run on the board it was written for. The location of the buildfile depends on the type of BSP:

Proprietary BSPs with binaries only
$QNX_TARGET/target/boot/build/
Simplified BSPs with binaries only
bsp_working_dir/prebuilt/boot/build/
Proprietary and simplified BSPs with source and binaries
bsp_working_dir/src/hardware/startup/boards/board

When you make the BSP, the buildfile is copied into the images directory.

A BSP's buildfile typically contains the commands -- possibly commented out -- for starting the drivers associated with the devices. You might need to edit the buildfile to modify or uncomment these commands. For more information, see the documentation for each BSP as well as the buildfile itself; for general information about buildfiles, see the entry for mkifs in the Utilities Reference.

Once you've modified the buildfile, follow the instructions given earlier in this chapter for building an OS image.

Transferring an OS image onto your board

Once you've built an OS image, you'll need to transfer it to your board.

The IDE lets you communicate with your target and download your OS image using either a serial connection, or a network connection using the Trivial File Transfer Protocol (TFTP). 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).

Transferring an OS image

There are several ways to transfer an OS image:

To: Use the:
Load an image from your network (e.g. TFTP) Network
Load an image serially (e.g. COM1, COM2) ROM monitor
Burn both the IPL and the OS image into the flash boot ROM, then boot entirely from flash IPL and OS
Burn an IPL (Initial Program Loader) into the flash boot ROM, then load the OS image serially IPL and boot ROM
Generate a flash filesystem, and then place various files and utilities within it Flash filesystem

The method you use to transfer an OS image depends on what comes with the board. The BSP contains information describing the method that you can use for each particular board. Each board will have all or some of these options for you to use.

To load an image serially:

  1. Connect your target and host machine with a serial cable. Ensure that both machines properly recognize the connection.
  2. Specify the device (e.g.COM1) and the communications settings (e.g. the baud rate, parity, data bits, stop bits, and flow control) to match your target machine's capabilities. You can now interact with your target by typing in the view.

To transfer a file using the Serial Terminal view:

  1. Using either the serial terminal view or another method (outside the IDE), configure your target so that it's ready to receive an image.
  2. In the serial terminal view, click Send File.
  3. In the Select File to Send dialog, enter the name or your file (or click Browse).
  4. Select a protocol (e.g. sendnto).
  5. Click OK. The Builder transmits your file over the serial connection.

Working with a flash filesystem

The flash filesystem drivers implement a POSIX-like filesystem on NOR flash memory devices. The flash filesystem drivers are standalone executables that contain both the flash filesystem code and the flash device code. There are versions of the flash filesystem driver for different embedded systems hardware as well as PCMCIA memory cards.

The naming convention for the drivers is devf-system, where system describes the embedded system. For example, the devf-800fads driver is for the 800FADS PowerPC evaluation board.

To find out what flash devices we currently support, please refer to the following sources:

The flash filesystem drivers support one or more logical flash drives. Each logical drive is called a socket, which consists of a contiguous and homogeneous region of flash memory. For example, in a system containing two different types of flash device at different addresses, where one flash device is used for the boot image and the other for the flash filesystem, each flash device would appear in a different socket.

Each socket may be divided into one or more partitions. Two types of partitions are supported:

Raw partitions

A raw partition in the socket is any partition that doesn't contain a flash filesystem. The flash filesystem driver doesn't recognize any filesystem types other than the flash filesystem. A raw partition may contain an image filesystem or some application-specific data.

The flash filesystem uses a raw mountpoint to provide access to any partitions on the flash that aren't flash filesystem partitions. Note that the flash filesystem partitions are available as raw partitions as well.

Flash filesystem partitions

A flash filesystem partition contains the POSIX-like flash filesystem, which uses a QNX-proprietary format to store the filesystem data on the flash devices. This format isn't compatible with either the Microsoft FFS2 or PCMCIA FTL specification.

The flash filesystem allows files and directories to be freely created and deleted. It recovers space from deleted files using a reclaim mechanism similar to garbage collection.

The flash filesystem supports all the standard POSIX utilities such as ls, mkdir, rm, ln, mv, and cp. There are also some QNX Neutrino utilities for managing the flash filesystem:

flashctl
Erase, format, and mount flash partitions.
deflate
Compress files for flash filesystems.
mkefs
Create flash filesystem image files.

The flash filesystem supports all the standard POSIX I/O functions such as open(), close(), read(), and write(). Special functions such as erasing are supported using the devctl() function.

Flash filesystem source

Each BSP contains the binary and the source code for the appropriate flash filesystem driver, but the Flash Filesystem & Embedding TDK contains the associated header files and libraries.

Typing make in the bsp_working_dir generates the flash filesystem binary. Normally, you won't need to remake the flash filesystem driver unless you've changed the size or configuration of the flash on the board -- this can include the number of parts, size of parts, type of parts, interleave, etc.


Caution: When an IPL/IFS (image filesystem) image is combined, you'll need to offset the beginning of the flash filesystem by at least the size of the IPL and IFS. For example, if the combined IPL/IFS image is loaded at offset 0 on the flash, to avoid overwriting the IPL and IFS, the flash filesystem must begin at an offset of the IPL/IFS image size +1. If it doesn't begin at an offset of the IPL/IFS image size +1, you'll need to create a partition.

How do I create a partition?

Regardless of which BSP you're working with, the procedure requires that you:

  1. Start the flash filesystem driver.
  2. Erase the entire flash.
  3. Format the partition.
  4. Slay the flash filesystem driver.
  5. Restart the flash filesystem driver.

Note: The following example applies specifically to the Renesas Biscayne board, which can be booted from DMON or flash.

  1. To boot from DMON, enter the following command to start the flash filesystem driver:
    devf-generic -s0xe8000000,32M &
  2. To boot from flash, enter the following command to start the flash system driver:
    devf-generic -s0x0,32M

    You should now see an fs0p0 entry under /dev.

  3. To prepare the area for the partition, you must erase the entire flash. Enter the following command:
    flashctl -p/dev/fs0 -ev
  4. To format the partition, enter the following command:
    flashctl -p/dev/fs0p0 -f
  5. Now slay the flash filesystem driver:
    slay devf-generic
  6. Finally, restart the driver:
    devf-generic &

You should now see the following entries:

Entry Description
/dev/fs0p0 OS image (32 MB)
/dev/fs0p1 Flash filesystem partition (32 MB)

Testing Neutrino on your board

You can test Neutrino simply by executing any shell builtin command or any command residing within the OS image. For example, type:

ls

You'll see a directory listing, since the ls command has been provided in the default system image.

Getting Photon on your board

For instructions on adding the Photon microGUI to your embedded system, see the documentation for the particular BSP; the buildfile could include the specific commands (commented out) that you need to run. For even more details, see the "Photon in Embedded Systems" appendix in the Photon Programmer's Guide.

Where do I go from here?

Now that you have a better understanding of how BSPs work in an embedded system, you'll want to start working on your applications. The following table contains references to the QNX documentation that may help you find the information you'll need to get going.

For information on: Go to:
Writing "hello world" The section "A simple example" in the chapter Compiling and Debugging in the Neutrino Programmer's Guide, or the IDE User's Guide.
Debugging your programs The section "Debugging" in the chapter Compiling and Debugging in the Neutrino Programmer's Guide.
Setting up NFS The section "Complete example -- TCP/IP with network filesystem" in the appendix Sample Buildfiles in this manual. See also the fs-nfs2 utility page in the Utilities Reference.
Setting up an Ethernet driver The section "Complete example -- TCP/IP with network filesystem" in the appendix Sample Buildfiles in this manual. See also the various network drivers (devn*) in the Utilities Reference.
Writing device drivers and/or resource managers The chapter Writing a Resource Manager in the Neutrino Programmer's Guide.

If you need more information, see these chapters in this guide:

For more information on: Go to:
Building flash filesystems Customizing the Flash Filesystem
IPL Writing an IPL program
Startup Customizing Image Startup Programs

Filename conventions

In QNX Neutrino BSPs, we use the following conventions for naming files:

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

[Previous] [Contents] [Index] [Next]