Working with a BSP

In this chapter...

• Overview
• Build procedure for a BSP
• Transferring an OS image onto your board
• Testing Neutrino on your board
• Getting Photon on your board
• Where do I go from here?
• Filename conventions

Overview

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:

• IPL
• Startup
• default Neutrino microkernel and process manager (procnto)
• default buildfile
• networking support
• suite of device drivers, system managers, utilities, etc.

The directory tree structure looks like this:

BSP directory tree.

Build procedure for a BSP

You can build a BSP from the source code or the binary components contained in the BSP package. A BSP package is available for QNX Neutrino, Windows, Solaris, or Linux hosts.

Building a BSP OS image from source

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

• use the command line
• import the source code within the IDE

Building from the command line

After your BSP is installed, you'll find the .zip file here:

$QNX_TARGET/usr/src/archives/qnx

To build a BSP OS image from the source code using the command line:

1. Change the directory to where you want to extract the BSP (e.g. /home/joe).

   ---

   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

   There will be a script in the BSP root named "setenv.sh" which will configure your environment to build the BSP.

   ---

   On Windows, you must run the Bash shell (bash.exe) before you run . ./setenv.sh.

   ---

3. Run the following script:

   . ./setenv.sh

   Now you're ready to make the BSP.

4. Type:

   make

Building 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.

   ---

   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.

   ---

   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:

• the command line
• the IDE

Building from the command line

After your BSP is installed, 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 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 (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 ().
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.

Using the BSP

Every BSP includes a buildfile that generates an OS image that will run on the board it was written for. By default the buildfile resides in the startup source directory and is named build. After you make the BSP, the buildfile is copied into the images directory.

All boards will have some devices, whether they're input, serial, flash, or PCI. This example lists some of the devices supported on a SystemH board and the command lines needed to start them:

BSP root directory

The BSP is contained in an archive named after the industry-recognized name of the board and/or reference platform supported by the BSP. In our documentation, we refer to the directory where this archive has been installed as the bsp_working_dir.

This directory contains the "meat" of the BSP -- the source hierarchy. The following sub-directories must exist here:

• images
• prebuilt
• install
• src

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:

• Custom buildfiles (for flash, etc.)
• EFS buildfiles
• IPL build scripts

prebuilt subdirectory

Once 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 layout of the prebuilt directory is as follows:

# cd /bsp_working_dir
# ls prebuilt/
.        ..       ppcbe    usr

The "root" of the prebuilt directory requires the same structure as the system root. Recursing into the ppcbe and usr directories mirrors that of /.

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

For this example, we'll look at the ppcbe directory:

# ls prebuilt/ppcbe/
.       ..      lib     sbin
# ls prebuilt/ppcbe/lib/
.                  libdrvrS.a
..                 libstartup.a
# ls prebuilt/ppcbe/sbin
.            ..           devb-eide
# ls prebuilt/usr
.          ..         include
# ls prebuilt/usr/include/
.       ..      drvr    ppc     sys
# ls prebuilt/usr/include/drvr
.            ..           eth.h        mdi.h        support.h
# ls prebuilt/usr/include/ppc
.          ..         util.ah
# ls prebuilt/usr/include/sys
.                  dcmd_io-net.h      platform.h
..                 nic.h              types.h

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. For example, suppose you want to build the network source for the Camelot-Biscayne BSP. Initially, you must build everything from the root of the BSP, like this:

Correct way (for initial build)

cd bsp_working_dir/sh/biscayne
make

This will build everything under ./src and will set up the ./install directory correctly.

After this initial build is complete, you should then be able to build any of the sources individually.

Remember that if you change a library or header, make sure it gets copied to your ./install directory.

src subdirectory

The source to all components in the BSP is stored here.

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.)

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:

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 boards and mtd-flash directories under bsp_working_dir/src/hardware/flash.
• QNX Neutrino OS docs (devf-* entries in Utilities Reference).
• the QNX Software Systems website (www.qnx.com).

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
• flash filesystem partitions

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

In the case of the flash filesystem source, typing make 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.

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.

The following example applies specifically to the 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 the following entry under /dev:

   /dev/fs0p0

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:

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

This section covers the following:

• Introduction
• Step 1. Export the PHOTON_PATH environment variable
• Step 2. Start the Photon server
• Step 3. Start the input (mouse, keyboard, touchscreen, etc.) driver
• Step 4. Start the font manager
• Step 5. Start the graphics driver
• Step 6. Start the window manager
• Step 7. Start your application
• Caveats
• An example of an x86 buildfile in Photon

Introduction

Before you configure Photon to run on your embedded system, we recommend that you use the information provided at the end of this section to construct a trial embedded Photon environment on a self-hosted PC.

At the end of the section, you'll find sample files that you can use. If your PC doesn't have a standard keyboard, msoft mouse, or a video card supported by the drivers used in these examples, you'll have to modify the examples so that they'll work in your environment.

When you run Photon in a desktop environment, you simply type ph to run a script that does all the work for you. This script:

• starts Photon
• determines your input hardware
• starts the input driver
• determines your graphics hardware
• starts the graphics driver and initializes the video hardware to the appropriate mode
• starts the font manager with the fonts you need
• starts the window manager
• starts the various desktop service applications (such as the shelf manager, background manager, etc).

Once Photon is started, you run the applications you want using either the window manager or Photon shelf manager.

In an embedded environment, you'll need to perform all these steps yourself manually. This has many benefits, because it lets you predefine the minimum files needed for your system and exactly how each driver/application will start.

Booting into Photon

Here's an outline of the steps required to boot directly into Photon with your application(s) running.

1. Export the PHOTON_PATH environment variable.
2. Start the Photon server.
3. Start the input (mouse, keyboard, touchscreen, etc.) driver.
4. Start the font manager.
5. Start the graphics driver.
6. Start the window manager (optional).
7. Start your application.

Each of these steps requires certain files to be installed in your target system. By predetermining exactly what graphics hardware you have and what fonts your application needs, you can keep the number of files (and required disk space) to an absolute minimum.

We'll go through all the steps in detail and discuss the files needed for each step. At the end of this process, you should know exactly what Photon files you'll need to run your embedded application.

Step 1. Export the PHOTON_PATH environment variable

The PHOTON_PATH environment variable is intended to hold the base directory of the installation. By default, this directory is /usr/photon. This location is expected to hold at least the following subdirectories:

bin

Photon executables

font_repository

Photon font files and config files (platform-independent)

palette

graphics palettes (platform-independent)

translations

Photon language translations (platform-independent)

You should set the PHOTON_PATH environment variable:

export PHOTON_PATH=/usr/photon

Step 2. Start the Photon server

If you don't need to pass any command-line arguments to the Photon server, you can start it as follows:

Photon &

If your embedded environment has a touchscreen or pen input device, you can adjust the input values for pointer events by specifying the -D, -R, and -U options. For example, to prevent random changes in position because the size of a finger press is larger than a pixel, specify the -U option. For more information, see Photon in the QNX Neutrino Utilities Reference.

The server must be located in the current PATH and you must define the path before running the command. In QNX Neutrino, this path is /usr/photon/bin. For example:

export PATH=:/bin:/usr/bin:/usr/photon/bin

If your boot image is too large because you've included Photon or other executables, you can mount a filesystem, wait for it to appear, and then load the executables from a filesystem at boot time. For more information, see mkifs in the QNX Neutrino Utilities Reference. If you do include any of the Photon executables in your boot image, you must also include /usr/photon/bin in MKIFS_PATH.

Files needed

/usr/photon/bin/Photon

Step 3. Start the input driver

Normally in a desktop environment, you use the inputtrap utility to automatically generate the correct command line and to invoke the appropriate devi-* driver. For example:

kbd fd -d/dev/kbd msoft

is the output from the inputtrap command which identifies the input device as a Microsoft keyboard and invokes the command to run the correct device driver.

You typically run inputtrap because you don't know in advance what the appropriate command line should be.

In an embedded system, the input devices are often found at unusual locations, are incapable of PnP identification, or are simply not supported by an existing devi-* driver. In addition, the inputtrap utility tends to be quite large and could waste precious storage and memory in a constrained environment. For these reasons, you typically specify the command line to the devi-* driver manually. (You can temporarily install inputtrap and use it to generate the correct command line.)

You can customize the input drivers by using the Input Driver Development Kit (Input DDK). For example, you can change the size of the memory footprint, or you can create a custom module to support new devices.

Files needed

The appropriate devi- driver in /usr/photon/bin

Step 4. Start the font manager

When building an embedded system, you need to make several decisions about the level of font support, including which fonts you need, and whether or not you need scalable fonts.

The first step is to decide which fonts you need:

• You're very likely to need the cursor font, phcursor.phf.
• If your embedded system includes pterm, you need the PC Terminal (pcterm*.phf), PC Serif (pcs*.phf), and/or PC Sanserif (pcss*.phf) font families. You probably also need a $HOME/.photon/pterm.rc file, or a $PHOTON_PATH/config/pterm.rc file to configure the terminal font.
• Most widget-based applications expect these aliases:
  • TextFont
  • MenuFont
  • FixedFont
  • BalloonFont
  • TitleFont
  to be defined by being appropriately mapped in the fontmap file.
• A web browser requires these types of fonts:
  • body font (e.g. PrimaSans BT, Dutch 801 Rm BT, etc.)
  • heading font (e.g. Swis721 BT, etc.)
  • nonproportional font (e.g. Courier10 BT, PrimaSansMono BT, etc.)

  Check the browser's configuration to see which fonts are expected, and use those fonts, modifying the configuration to reflect what you have installed, or use the fontmap file to map them at runtime.

You can map, or substitute, font names by using the fontmap file, or the Mappings section of the fontadmin. For more information, see those entries in the Utilities Reference.

Configuring fonts

You can configure the fonts on the embedded system itself, but it's easier to use the development system to configure the fonts for the embedded system and assemble the font data and configuration files in the appropriate Embedded File System (EFS) build image directory.

You should use the phfont.so io-graphics plugin for font manager services. This plugin offers better performance, with no noticeable impact on system resources.

For example, suppose the root directory of this image is /usr/phembed (the real pathname depends on your development environment).

Change your current directory to be the root of your build subdirectory:

export PHEMBED_DIR=/usr/phembed
cd /usr/phembed

Copy /etc/system/config/font-traplist to the same location in the embedded system:

cp /etc/system/config/font-traplist etc/system/config/font-traplist

Create a font repository for your embedded system. The phfont.so plugin requires that the font repository reside in /usr/photon/font_repository. For example:

mkdir -p /usr/photon/font_repository

Copy the necessary font files into the build image framework for collection by mkefs:

cp font_filename usr/photon/font_repository  

(Repeat for each font)

cp /usr/photon/font_repository/font* usr/photon/font_repository
cp /usr/photon/font_repository/mappings usr/photon/font_repository

This example creates an initial configuration and copies any font files into the specified target directory. Options may be supplied through the fontopt configuration file. For information about the format of this configuration file, see the documentation for phfont.

To change mappings, invoke fontadmin:

fontadmin -c usr/photon/font_repository -d usr/photon/font_repository

Run the embed_font script to copy the font system binaries and associated shared libraries:

embed_font   /usr/phembed

If the target fails to start the font manager:

• Check that /lib and /lib/dll are in the LD_LIBRARY_PATH environment variable and the privileged _CS_LIBPATH.
• Check the output of sloginfo for error messages.

Step 5. Start the graphics driver

The Photon graphics subsystem is started by running io-graphics. Here are some sample invocations:

io-graphics -g640x480x8 -dldevg-vga.so -P/usr/photon/palette/vga4.pal
io-graphics -g1024x768x16 -dldevg-vesabios.so
io-graphics -g1024x768x16 -dldevg-rage.so -d0x1002,0x4755 -I0

Here's what the options mean:

-g

Specifies the resolution and color depth of the desired video mode. Note that the VGA driver pretends to io-graphics that is has an 8-bit color depth, even though it sets a 4-bit video mode for performance reasons.

-dl

Specifies the name of the graphics-driver shared object to load, in order to control the graphics hardware.

-d

Required for drivers that identify the graphics hardware by its PCI vendor and device ID.

-I

Specifies the instance of the PCI device to attach to, in case there's more than one graphics device in the system, with the same vendor and device IDs.

-P

Specifies the palette file to use; vga4.pal is a palette designed for use with a 16-color video mode.

For more information about io-graphics, see its entry in the QNX Neutrino Utilities Reference.

Components needed

io-graphics

Launches the graphics subsystem.

devg-*

Hardware-level graphics drivers.

libdisputil.so.2

The library of utility routines that the devg* drivers use. Most graphics drivers are linked against this library.

libffb.so.2

The library of rasterization routines that the devg* drivers use. Most graphics drivers are linked against this library.

gri-photon.so

The Photon draw event handler.

libgri.so.2

The Photon drawstream-processing DLL.

libphrender.so

The software rendering routines.

Step 6. Start the window manager

This step is optional if only a single application is used, or if your embedded system doesn't require the services provided by the window manager. The workspace configuration file ($HOME/.ph/wm/wm.cfg) may be modified dynamically using the pwmopts. Alternatively, nondefault options may be set with command-line options or through the PHWMOPTS environment variable.

The personalized PWM menu ($HOME/.photon/wm/wm.menu), if used, may pose a problem if commands are given as absolute pathnames (unqualified command names should be portable across systems, provided that the PHOTON_PATH environment variable is consistent). The standard PWM menu invokes all commands from $PHOTON_PATH/bin. For embedded systems, note that you can disable this menu completely by using the -W option to pwm.

Files needed

/usr/photon/bin/pwm

Step 7. Start your application

If your application is a single executable and doesn't require the window manager, then you can link your application static -- you won't need the Photon shared library.

If you need the window manager or have more than one Photon program running, then it's best to use the Photon shared library.

Files needed

Your application files.

If your application needs the Photon shared library:

/usr/lib/libph.so

The libraries in /usr/photon/lib are provided for runtime compatibility with Photon for QNX Neutrino 6.0 (x86 only). The libraries for QNX Neutrino 6.1 and newer are located in /usr/lib.

Caveats

The following are observations that some customers have encountered when moving Photon to an embedded system.

mkifs

By default, mkifs strips Photon resource names from executable files. To prevent this, specify the +raw attribute for all Photon Application Builder applications.

Flash filesystems

The following flash filesystem properties will affect how you configure Photon:

Compression and Speed

Since the flash filesystem is slower when it's seeking in a compressed file, you'll probably want to keep the resource records in a separate file, instead of including them at the end of the binary. To do this, change the makefile so that the resources are bound to a separate file. For example, change the following dependency:

$(ABOBJ) $(MYOBJ)
$(LD) $(LDFLAGS) $(ABOBJ) $(MYOBJ) -M -o mine
usemsg mine ../Usemsg
phabbind mine $(ABMOD)

to:

$(ABOBJ) $(MYOBJ)
$(LD) $(LDFLAGS) $(ABOBJ) $(MYOBJ) -M -o mine
usemsg mine ../Usemsg
phabbind mine.res $(ABMOD)

You'll also need to export the AB_RESOVRD path variable if the resource records aren't in the same directory as the executables. This avoids searching the directory containing the executables.

Seeks

The flash filesystem has limitations on seeking and writing. Your code must disallow writes to the middle of a file.

---

The config file routines aren't compatible with the flash filesystem.

---

Graphics

Many embedded systems lack components that are typical on a desktop machine. Here are a few items to watch for:

BIOS ROMs

Because many of the modeswitchers supported by Photon require a video BIOS to allow them to switch graphics modes, you may need a BIOS on the board. Check with QNX Software Systems to see if a non-BIOS version is available.

Text mode

Support for text mode isn't required by Photon, so you can eliminate any setup associated with text mode.

Video area

RAM memory can be made contiguous because Photon drivers aren't restrictive about the location of the video area (e.g. 0xa000). You may place the video buffer anywhere in memory.

Miscellaneous

Here are some miscellaneous considerations:

CPU speed

For some embedded systems, the CPU performance will be slower than the desktop. You'll want to consider this when you design your Photon applications for the embedded environment.

Scrolling

If the scrolling area pages down more than one page at a time when you click in the trough, try increasing the value of the mouse repeat-delay option in Photon. For example:

Photon -D1000 &
  

Input

You can set the throttling parameters on both the Input and the Photon Server. By reducing the speed at which mouse events are emitted, you can reduce the traffic through the Photon system. On slower 386 and 486 platforms, it's common practice to lower the throttling on input to 10 or 20 ms.

Phindows and Phditto

If your target application needs to support remote diagnostics from either Phindows or phditto, you'll also need to install phrelay, a render library, and the services configuration file.

Example of Photon on an embedded device

The example described below is of an x86 buildfile in Photon. Note that you can also import a buildfile into the System Builder in the IDE. See the IDE User's Guide for more detail. A Photon system can be built with the following minimal capabilities:

• scalable TrueType fonts
• graphics for a Banshee chipset
• mouse and keyboard support
• Photon Application Builder support
• Photon Terminal (pterm) support

Embedding Photon requires defining the required:

• binaries
• libraries
• fonts
• configuration files
• buildfile

Required binaries

The following binaries are required:

• Photon -- the Photon server
• io-graphics -- graphics system IO manager
• devi-hirun -- input driver for mouse and keyboard
• pwm -- window manager (optional) used to simplify user interaction
• pterm -- Photon Terminal application
• phcalc -- Photon Application Builder sample application
• devc-pty -- need to allow pterm to function
• pidin -- useful utility for debugging

Required libraries

The following libraries are required for the binaries listed above: (Note that libc.so is not listed.)

• Photon -- no libraries needed
• io-graphics:
  • /lib/dll/devg-vesabios.so (used for this example only; the entry will change for other systems)
  • /usr/lib/libffb.so
  • /usr/lib/libdisputil.so
  • /usr/lib/libgri.so
  • /usr/lib/libphrender.so
  • /lib/dll/gri-photon.so
  • /lib/dll/phfont.so (loaded by io-graphics for font services)
  • /usr/lib/libFF-T2K-cache.so
  • /usr/lib/libFF-T2K-fm.so
  • /usr/lib/libFF-T2K.so
  • /usr/lib/libblkcache.so
• devi-hirun:
  • /usr/lib/libph.so.2
• pwm:
  • /usr/lib/ph.so.2
  • /usr/lib/phexlib.so.2
• pterm:
  • /usr/lib/libm.so.2
  • /usr/lib/libph.so.2
  • /usr/lib/libphrender.so.2
  • /usr/lib/libAp.so.2
  • /usr/lib/phexlib.so.2
• phcalc:
  • /usr/lib/libm.so.2
  • /usr/lib/libph.so.2
  • /usr/lib/libphrender.so.2
  • /usr/lib/libAp.so.2
  • /usr/lib/phexlib/so.2

Required fonts

Some applications explicitly load a font in the source code. When this is the case, you'll need to install the font on your target system. If the application standardizes on a certain family/style of fonts, then the number of fonts needed can be reduced and possibly mapped to other fonts.

You can create a custom font directory for an embedded system that has no particular font needs. The process is as follows:

1. Create a temporary directory to store the fonts:

   mkdir /tmp/font_repository 
   cd /tmp/font_repository

2. Copy all necessary fonts and all the configuration files into the temporary directory. Keep in mind that the cursor (phcursor.ph) and terminal (pcterm*.phf) fonts are always good to use for debugging. For this example, the following fonts are required:

   cp /usr/photon/font_repository/phcursor.phf ./
   cp /usr/photon/font_repository/pcterm*.phf ./
   cp /usr/photon/font_repository/tt2001m_.ttf ./
   cp /usr/photon/font_repository/tt2002m_.ttf ./
   cp /usr/photon/font_repository/tt2003m_.ttf ./
   cp /usr/photon/font_repository/tt2004m_.ttf ./
   cp /usr/photon/font_repository/tt2009m_.ttf ./
   cp /usr/photon/font_repository/tt2011m_.ttf ./
   cp /usr/photon/font_repository/font* ./
   cp /usr/photon/font_repository/mappings ./

3. Modify the configuration files to reflect the new fontlist:

   mkfontdir -d ./

   ---

   Some versions of Photon have a bug in the fontdir file. You may have to edit the fontdir file manually. Make sure the phcursor line is as follows: phcursor,.phf,Photon Cursor,0,,E900-E921,Np,32x32,3K

   ---

4. Edit the font mapping file to reflect the new fonts. The file is called "fontmap", and should look like this:

   term = pcterm
   ? = primasansbts

   This command maps the terminal fonts to pcterm and maps all other fonts to the primasansbts command included in the fontdir file.
5. Remove the fontdynamic file from the font mapping file. It's not needed because you won't be supporting dynamic addition of system fonts.

Required configuration files

You'll also need configuration files in your system to allow the devi-hirun input driver to function. At a minimum you'll need the following directory and configuration file for mapping an English keyboard:

/usr/photon/keyboard/en_US_101.kbd

If you require other languages, you can find entries for them in the supported keyboard files:

/usr/photon/keyboard

Buildfile

Now that all the pieces are ready, you can create a boot image capable of running Photon. Note that the font repository you created is included in this image as:

/usr/photon/font_repository

This image also contains some debug services that enable you to access the system via a serial port.

Here's an example of an x86 buildfile in Photon

The easiest way to test the image generated from this build file is to install it as /.altboot on an x86 QNX Neutrino 6.3 self-hosted installation.

For details on how this file was generated and how it may be further optimized, please refer to the Photon in Embedded Systems appendix to the Photon microGUI for QNX Neutrino Programmer's Guide section in the QNX Momentics Help Documentation.

For details on how buildfiles work, please refer to the help documentation for mkifs in the QNX Neutrino Utilities Reference in the QNX Momentics Help Documentation.

This embedded Photon 6.3 buildfile for x86 has a VESA2-compliant video card and is only an example of a working embedded Photon system.

In a real buildfile, you can't use a backslash (\) to break a long line into shorter pieces, but we've done that here, just to make the buildfile easier to read.

[virtual=x86,bios +compress] .bootstrap = {
    startup-bios -v
    PATH=:/proc/boot:/usr/bin:/bin:/usr/photon/bin 
    LD_LIBRARY_PATH=:/proc/boot:/usr/lib:/lib:/lib/dll \
PHOTON_PATH=/usr/photon procnto -v
}
[+script] .script = {
    procmgr_symlink ../../proc/boot/libc.so.2 /usr/lib/ldqnx.so.2

    display_msg Welcome to QNX Neutrino 6.3 on an x86 platform with Photon

    slogger &
    pipe &

    display_msg Starting PCI
    pci-bios
    waitfor /dev/pci 10

    display_msg Starting Serial
    devc-ser8250 -e &
    reopen /dev/ser1

    SYSNAME=nto
    TERM=qansi
    PHOTON=/dev/photon
    PATH=:/proc/boot:/usr/bin:/bin:/usr/photon/bin
    LD_LIBRARY_PATH=:/proc/boot:/usr/lib:/lib:/lib/dll
    PHOTON_PATH=/usr/photon
    PHOTON=/dev/photon
    PHFONT=/dev/phfont
    HOME=/

    display_msg Starting Photon
    Photon
    waitfor /dev/photon 10

    display_msg Starting Input
    devi-hirun kbd kbddev ps2 mousedev &

    display_msg Starting Graphics
    io-graphics -dvesabios photon,xres=1024,yres=768,bitpp=16,refresh=60 -pphoton
    waitfor /dev/phfont 10

    display_msg Starting Window Manager
    pwm &
    bkgdmgr &
    devc-pty &

    display_msg Starting Terminal
    pterm /proc/boot/ksh &

    # debug shell on /dev/ser1 at 57600
    [+session] ksh
}

[type=link] /bin/sh = /proc/boot/ksh
[type=link] /dev/console = /dev/ser1
[type=link] /tmp = /dev/shmem

# standard libs
libc.so
libm.so

# photon libs
libph.so
libAp.so
libphexlib.so
libphimg.so
libjpeg.so
pi_io_jpeg.so

# io-graphics libs
gri-photon.so
libphrender.so
libgri.so
libdisputil.so
libffb.so

# graphics driver
devg-vesabios.so
/etc/system/config/crtc-settings = /etc/system/config/crtc-settings
/usr/photon/palette/default.pal = /usr/photon/palette/default.pal

# font libs
/lib/dll/font/ttfFFcore.so = /lib/dll/font/ttfFFcore.so
/lib/dll/font/PHFcore.so = /lib/dll/font/PHFcore.so
libfontharnessutils.so
libfontutils.so
libblkcache.so
libFF-T2K.so
libFF-T2K-cache.so
libFF-T2K-fm.so
libfont.so
phfont.so

# font config
/usr/photon/font_repository/tt2009m_.ttf = /usr/photon/font_repository/tt2009m_.ttf
/usr/photon/font_repository/phcursor.phf = /usr/photon/font_repository/phcursor.phf
/usr/photon/font_repository/mappings = /usr/photon/font_repository/mappings
/usr/photon/font_repository/fontopts = /usr/photon/font_repository/fontopts
/usr/photon/font_repository/fontkey = /usr/photon/font_repository/fontkey

/usr/photon/font_repository/fontdir = {
;
; fontdir config file
;
phcursor,.phf,Photon Cursor,0,,E900-E921,Np,32x32,3K
primasansmonobts,0@tt2009m_.ttf,PrimaSansMono BT,0,,0020-F002,f,79x170,109K
}

/usr/photon/font_repository/fontext = {
;
; fontext config file
;
+normal = primasansmonobts, phcursor
}

/usr/photon/font_repository/fontmap = {
;
; fontmap config file
;
? = primasansmonobts
}

# input config
/usr/photon/keyboard/en_US_101.kbd = /usr/photon/keyboard/en_US_101.kbd

[data=c]
pci-bios
devc-pty
devc-ser8250

ls
ksh
cat
pipe
pidin
uname
slogger
sloginfo
slay

Photon
io-graphics
devi-hirun
pwm
[+raw] /usr/photon/bin/pterm = pterm
[+raw] /usr/photon/bin/phcalc_sm = phcalc_sm
[+raw] /usr/photon/bin/phshutdown = phshutdown
[+raw] /usr/photon/bin/bkgdmgr = bkgdmgr
[+raw] /usr/photon/bin/pwmopts = pwmopts
[+raw] /usr/photon/bin/phmenu = phmenu

# default image for bkgdmgr
[+raw] /usr/share/backdrops/1024x768/default.jpg = \
/usr/share/backdrops/1024x768/default.jpg

# pwm and bkgdmgr config
/usr/photon/config/wm/wm.cfg = /usr/photon/config/wm/wm.cfg

# The parts of each entry in the wm.menu file must be separated by tabs.
/usr/photon/config/wm/wm.menu = {
= Desktop Menu
Terminal    T   pterm
Calculator  a   phcalc_sm
-4
< Configure  C   C
Appearance  W   pwmopts
Desktop Menu    D   phmenu
> 
Shutdown... u   phshutdown
}

# allow pterm to save its configuration to RAM, if the user changes it.
[type=link] /.ph/pterm = /dev/shmem

# allow pwm and bkgdmgr to save their configuration to RAM, if the user changes it.
[type=link] /.ph/wm = /dev/shmem

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 -- these may help you find the information you'll need to get going.

The following table contains references to help you find more information if you require it.

Filename conventions

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