QNX Technical Articles

Date of this edition: January 05, 2005

Target OS: QNX^® Neutrino^® 6.3.0 SP1

Host OS: Microsoft Windows XP SP1 or SP2; Microsoft Windows 2000 SP4; Sun Solaris 7/8; QNX^® Neutrino^® 6.3.0 SP1; Linux (Red Hat 8/9)

Boards supported: Freescale Lite5200 EVB Rev2 and Total5200 Rev1 and Rev2

You need to have installed the QNX Momentics 6.3.0 SP1 before installing this BSP. For information on installing this BSP, see the installation note. If you install SP1, you should also install the latest version of the QNX Momentics Character Driver Development Kit (DDK), if you installed an earlier version of it. Significant changes have been made to this DDK; please see the Character DDK Release Notes. For the most up-to-date version of these release notes, log into your myQNX account, and then go to the Download Center area of www.qnx.com.

Contents

• What's in this BSP?
  • Binary components
  • Source code
  • Documentation
• Location of source and documentation
• Fixed issues
• Known issues for this BSP
  • Audio concerns
• Technical support

Throughout this document, you may see reference numbers associated with particular issues, changes, etc. When corresponding with our Technical Support staff about a given issue, please quote the relevant reference number. You might also find the reference numbers useful for tracking issues as they become fixed.

What's in this BSP?

This BSP contains:

• Binary components
• Source code
• Documentation.

The source code requires a BSP Source License.

Binary components

• IPL
• Startup
• PCI server
• Serial driver
• Network driver
• Bestcomm DMA library
• Bestcomm utility
• USB support
• EIDE driver
• Audio driver (Total5200 only)
• Graphics driver (Total5200 only)
• SPI driver (Total5200 only)
• I2C driver (Total5200 only)
• Touchscreen (Total5200 only).

Source code

• IPL
• Startup
• PCI server
• Serial driver
• Network driver
• Audio driver (Total5200 only)
• Graphics driver (Total5200 only)
• SPI driver (Total5200 only)
• I2C driver (Total5200 only)
• Touchscreen (Total5200 only)
• Flash driver.

The flash filesystem library is included in the separately available Flash Filesystem & Embedding Technology Development Kit (TDK).

Documentation

• Freescale Total5200 / Lite5200EVB BSP readme (HTML)

Each BSP guide contains board-specific information and instructions on building an OS image for that particular board. The procedure for building BSPs has changed since QNX Momentics 6.2.1. For instance, you must now run the . ./setenv.sh script before compiling your BSP source. If you fail to run this shell script prior to building the BSP, you can overwrite existing binaries or libs that are installed in $QNX_TARGET. For details, see the chapter "Working with a BSP" in the Building Embedded Systems manual (in the Documentation Roadmap page under the QNX Neutrino RTOS section).

Location of source and documentation

When you install BSPs, you'll find the source code and documentation in the following locations:

Windows hosts

QNX Neutrino, Linux, and Solaris hosts

To extract the source from the archive, use any application that supports the ZIP format (e.g. WinZIP). For more information, see the chapter "Working with a BSP" in the Building Embedded Systems manual. The "roadmap" page (e.g. from the Windows XP start menu: Release notes-->All Programs-->QNX Momentics 6.3.0-->Documentation) contains links to the various HTML booksets that accompany the OS: System Architecture, Building Embedded Systems, Programmer's Guide, Library Reference, Utilities Reference, etc.

Binaries, buildfiles, IPLs, and other files

Depending on the particular BSP and type of driver, you'll find the files in these locations:

Windows hosts

QNX Neutrino, Linux, and Solaris hosts

Fixed issues

The MGT5200 default buildfile has the correct io-usb arguments (i.e. io-usb -d ohci-mgt5200 ioport=0xf0001000,irq=70). The documentation is also up-to-date. (Ref# 19846) The MGT5200 default buildfile no longer has the PCI server commented-out. Graphics-intensive applications no longer interfere with the audio DMA channel. (Ref# 20872)

Known issues for this BSP

Please check the version of these release notes on the website for the most up-to-date information.

• The Silicon Motion PCI reference cards SMI501, SMI731, and SMI722 aren't supported on the Freescale Lite5200 rev2 board due to hardware incompatibility. A future release of the BSP will support the SMI712.
• If a FIFO error occurs while the audio driver is running (logged by slogger), the driver may need to be restarted to restore correct operation. See the section "Audio concerns" below for details.
• During audio playback and or capture, configuration changes such as volume changes may not take effect. See the section "Audio concerns" below for details.
• Only the top USB port works on the Total5200 board.
• In Microsoft Windows, certain programs (e.g. Norton Ghost) add directories inside double quotation marks (e.g. ...;"c:\Program Files\Norton Ghost\";...) to your PATH environment variable. This causes the Cygwin spawn() function to fail, which in turn causes cp to fail when called by ln-w. (Ref# 20046)

  Workaround: Modify your PATH environment variable and remove any quotation marks.

• In those instances where the the ROM monitor's MAC address is different from the one you pass in when running io-net, the host can cache the ROM monitor's address. This can result in a loss of connectivity.

  Workaround: If you need to specify a MAC address to io-net we recommend that you use the same mac address that the ROM monitor uses. This will ensure that if the host caches the ROM monitor's MAC address, you'll still be able to communicate with the target. Otherwise you might need to delete the target's arp entry on your host.

• Simply uncommenting the io-graphics line in the buildfile isn't enough to run Photon on the target; this line shows how to run the graphics driver only. For more information on embedding Photon on your board, see the Photon in Embedded Systems appendix of the Photon Programmer's Guide.

  To test or evaluate Photon on your target before embedding it you could make the Photon environment accessible to the target by simply mounting your host environment into the target. You'll need to use an NFS or CIFS client on the target depending on the type of server running on your host platform. This example shows how to create a basic Photon configuration using an NFS client.

  1. Uncomment the following sections from the build file: network, usb and graphics
  2. Add the following at the end of the network section:

           fs-nfs3 10.0.0.1:$QNX_TARGET/cpu/ /
                   10.0.0.1:$QNX_TARGET/etc /etc
                   10.0.0.1:$QNX_TARGET/usr/photon /usr/photon &
           
           waitfor /usr/bin
           waitfor /usr/photon
           waitfor /etc
     
           Where 10.0.0.1 is the server IP address
         

     ---

     The first three lines of the fs-nfs command comprise one command.

     ---

  3. You can now run the Photon drivers.

     To run the graphics driver:

           /usr/photon/bin/Photon &
           waitfor /dev/photon
           /usr/photon/bin/io-graphics -d...
          

     (See the "Devices supported" chapter in the BSP documentation for details on the graphics driver options).

     To use a usb mouse and keyboard:

           /sbin/io-hid -dusb
           /usr/photon/bin/devi-hid kbd mouse &
        

• If you specify the -d and -p options for io-graphics, you must put the -d option before the -p, or else io-graphics fails. (Ref# 22670)
• Hardware flow control doesn't currently work for the serial driver. (Ref# 21615)
• The TCP/IP stack obtains a timer from the process manager. This timer starts at 0. If the TCP/IP stack and a TCP/IP application that tries to connect to a remote host start executing too soon, the TCP/IP stack may apply a time of 0 seconds to ARP cache entry structures. If this occurs, you may end up with a permanent ARP entry (i.e. one that never times out). You can also end up with permanent, incomplete ARP entries that never time out, and that the TCP/IP stack doesn't attempt to resolve. If this happens, your host won't be able to communicate with one or (possibly) more remote hosts (i.e. the ones the TCP/IP application in the OS image is trying to reach).

  You can check for permanent ARP entries by running the arp -an command and examining the output. The only permanent entries listed should be for the IP addresses assigned to your host's interfaces; there shouldn't be any permanent, incomplete entries. If you find a permanent entry that isn't for the IP address of an interface on your host, and you didn't explicitly create a permanent entry, then you could be encountering this problem. (Ref# 21395)

  Workaround: In the buildfile for your OS image, delay the start of the TCP/IP stack or the first TCP/IP application by at least one second, by using the sleep command (e.g. sleep 1) or some other delay mechanism.

• The Freescale Lite5200 on-board USB driver occasionally fails to recognize USB devices connected via USB hubs.

  Workaround: The USB transceiver on the Lite5200 boards (version 2.0, Rev G) is sensitive to a resistor value that worked with the previous transceiver version. That resistor is R164. If you replace the R164 with a 0-Ohm resistor, or short it out with a wire, then the USB should work. (Ref# 17481)

• There are two different versions of the Freescale/Motorola Total5200 SDP. Among the changes from revision 1 to revision 2, the bus configuration of the eight 8250 UART ports has changed. On rev.1, a 32 bit data bus was used for these ports, and on rev. 2, an 8 bit bus is used.

  For rev. 1:

  The eight 8250-compatible UARTs are supported. However, on the Total5200 board (Rev1 only), the ports must be accessed via 32-bit reads and writes. Therefore, you'll need to generate a version of devc-ser8250 that uses 32-bit accesses.

  ---

  Rev 2 of the Total5200 board doesn't have this problem.

  ---

  1. Go to the source directory for devc-ser8250:

     cd bsp_working_dir/src/hardware/devc/ser8250/ppc/

  2. Add the mgt.be variant to the source tree:

     addvariant mgt.be

  3. In the mgt.be directory, create and save the following variant.h file:

     #ifndef write_8250
     #define write_8250(__port,__val)    out32(__port,__val)
     #endif
     
     #ifndef read_8250
     #define read_8250(__port)   in32(__port)
     #endif

  4. Now make this driver, and include it in your build image.

  To start the driver, use the appropriate command-line arguments:

  For this port:	Use this command:
  1	devc-ser8250-mgt -e -F -b115200 -c7372800 0x30000000^2,0
  2	devc-ser8250-mgt -e -F -b115200 -c7372800 0x30000020^2,0
  3	devc-ser8250-mgt -e -F -b115200 -c7372800 0x30000040^2,0
  4	devc-ser8250-mgt -e -F -b115200 -c7372800 0x30000060^2,0
  5	devc-ser8250-mgt -e -F -b115200 -c7372800 0x30000080^2,6
  6	devc-ser8250-mgt -e -F -b115200 -c7372800 0x300000a0^2,6
  7	devc-ser8250-mgt -e -F -b115200 -c7372800 0x300000c0^2,6
  8	devc-ser8250-mgt -e -F -b115200 -c7372800 0x300000e0^2,6

  For rev. 2 boards, a custom driver is no longer needed; however, the port offsets and bus width have changed.

  For this port:	Use this command:
  1	devc-ser8250 -e -F -b115200 -c7372800 0x30000000,0
  2	devc-ser8250 -e -F -b115200 -c7372800 0x30000008,0
  3	devc-ser8250 -e -F -b115200 -c7372800 0x30000010,0
  4	devc-ser8250 -e -F -b115200 -c7372800 0x30000010,0
  5	devc-ser8250 -e -F -b115200 -c7372800 0x30000020,6
  6	devc-ser8250 -e -F -b115200 -c7372800 0x30000028,6
  7	devc-ser8250 -e -F -b115200 -c7372800 0x30000030,6
  8	devc-ser8250 -e -F -b115200 -c7372800 0x30000038,6

  There is also an issue with the code which automatically detects the board revision in startup-mgt5200; it incorrectly reprograms the Chip Select configuration for this port, if you're using a rev. 2 board. If you have a rev. 2 board, and intend to use these UART ports, modify main.c of your startup code, to hardcode the board version, as follows:

  $BSP_ROOT_DIR/src/hardware/startup/boards/mgt5200/main.c

  change:

      detect_glacier();

  to:

      // detect_glacier();
      glacier2_found = 1;

  This will prevent the board detection routine from running and incorrectly reprogramming the CS3 configuration register.

Audio concerns

The MPC5200 has six Programmable Serial Controllers (PSCs), which can be used to stream audio data into and out of the MPC5200. Two of the PSCs have an operating mode designed to connect to AC'97 codecs. However, the AC'97 mode on the MPC5200 lacks a full implementation of an AC'97 physical interface. This can cause several significant failure modes of the audio driver.

• If the PSC FIFO becomes empty, framing with the codec will be lost. This may cause the audio to no longer be heard correctly and/or the codec interface may shutdown completely. In either case the driver will need to be restarted to clear this condition. The driver will put a message of "mpc5200: FiFo Interrupt (###,###,###,###)" into slogger if this condition occurs.
• In order to adjust the codec while audio playback is running the driver must inject codec commands into the frame stream of the PSC. With this technique it's possible for codec commands to fail. This means that a volume adjustment during playback may sometimes have no effect.

All applications using the MPC5200 AC'97 driver can be affected by these problems, with careful system design and integration the impact of these issues can be minimized. Some platform operations such as disabling interrupts for more then a few instructions will increase the likely hood of these problems occurring and therefore should be avoided during system design. In the same way having any processes or interrupt service routines that prevent the audio driver interrupt threads from executing on time intensify the chances of these issues occurring.

Before explaining these conditions in detail it's necessary to describe the basic workings of the AC'97 audio system. The system consists of two primary components:

• the codec -- is responsible for all analog signal control and for the analog to digital conversion (ADC) as well as the digital to analog conversion (DAC).
• the digital controller -- is responsible for transferring the digital PCM streams to the codec and for changing codec internal registers that control the codec operation.

The two components communicate via a bi-directional five wire serial TDM interface. The data flowing across this link is formatted as input and output frames that are transferred at the rate of 48000 frames per second. A simplified format of these frames is shown below:

PSC output (serial data out)

CODEC output (serial data in)

In this simplified view the codec provides the data and frame synchronization clock for the communication. The controller must detect the start of frame signal so that it can begin sending its output frame and begin decoding the input frame at the correct time.

The "Cmd" slots hold codec commands for reading and writing codec controls; the "Status" slots hold the results for the last command received, and the PCM slots hold the PCM data for the audio streams. The Tag slots are used to signal the validity of the other slots and for support of the Sample rate conversion in the codec. To achieve sample rates different from the frame rate (48 KHz) the codec uses the tag bits to control the data transfer.

The MPC5200 implements the AC'97 controller using a Programmable Serial Controller (PSC), but the limited functionality of the PSC can cause several issues for the device driver.

The first issue that can happen is random "Cmd" data being sent to the codec. This condition occurs if the DMA engine does not fill the PSC Transmit FIFO quickly enough. This situation causes the PSC to lose frame synchronization with the codec, so when the FIFO is later filled that data will be sent in any slot of the frame. This means that the PCM data can be sent in the "Cmd" slots. Since the PCM data can be any value, the effects on the codec are not defined.

The second issue is getting codec commands such as volume changes to occur in a timely manner. To accomplish this, the audio driver must inject these commands into the PSC data stream such that the commands are transferred to the codec in the earliest possible frame. To do this the driver needs to know with accuracy where in a DMA buffer the DMA engine is. There are issues with the current Bestcomm DMA implementation that may prevent this technique from working consistently.

The third issue is also caused by the PSC limited functionality; the PSC does not understand the AC'97 frame but simply transmits and receives data. This means it's not possible to use the sample rate converters in the codec. This feature of AC'97 is called Variable Rate Audio (VRA) and requires that the controller support "on demand" slot request bits. In short, the codec sets a slot request bit whenever it needs data.

As an example, for a playback rate of 44100 Hz the codec would set the slot requests bits in 441 of 480 frames transferred. Since the PSC does not interpret the request bits, this feature is not useable. The situation then requires the audio architecture or the application to perform rate conversion in software. This conversion requires CPU power to perform. As the quality of the conversion gets better, the CPU requires more power.

Technical support

If you have any questions, comments, or problems with a QNX product, please contact Technical Support. For more information, see the How to Get Help chapter of the Welcome to QNX Momentics guide or visit our website, www.qnx.com.