Connecting Hardware

This chapter includes:

Introduction

When you boot a Neutrino desktop system, it starts a device enumerator, a manager that detects most hardware devices. The enumerator loads a set of configuration files from /etc/system/enum/devices that define what your system should do (e.g. start a specific driver) when you add or remove hardware.

You can edit the enumerator's configuration files, if necessary. For more information, see Controlling How Neutrino Starts in this guide, and enum-devices in the Utilities Reference.

An embedded Neutrino system typically has specific hardware, so when the system boots, it's likely to explicitly start the appropriate drivers.

You can find a list of currently supported hardware in the Community area of our website, http://www.qnx.com. The website lists the chipsets and hardware that we've tested with Neutrino. However, many times there are slight variants of chipsets that will work with the drivers even if they aren't listed. It's often worth trying these chipsets to see if the driver will work with your hardware, but note that the hardware might not behave as expected.


Note: Neutrino doesn't currently support tapes.

You'll use the information in this chapter if the enumerator can't detect your system's devices, or if you want to manually configure static devices in an embedded system.


Note:
  • You need to be logged in as root to start any drivers.
  • Make sure that PnP-aware OS is disabled in the BIOS before you run Neutrino.

PCI/AGP devices

If you don't know what type of controller you're using, you can use the pci utility to identify it:

pci -vvv | less

The output from this command looks something like this:

Class          = Mass Storage (IDE)
Vendor ID      = 8086h, Intel Corporation
Device ID      = 7111h, 82371AB/EB PIIX4 IDE Controller  
PCI index      = 0h
Class Codes    = 010180h
Revision ID    = 1h
Bus number     = 0
Device number  = 4
Function num   = 1  
Status Reg     = 280h
Command Reg    = 5h
        I/O space access enabled
        Memory space access disabled
        Bus Master enabled
        Special Cycle operations ignored
        Memory Write and Invalidate disabled
        Palette Snooping disabled
        Parity Checking disabled
        Data/Address stepping disabled
        SERR# driver disabled
        Fast back-to-back transactions to different agents disabled  
Header type    = 0h Single-function
BIST           = 0h Build-in-self-test not supported
Latency Timer  = 20h
Cache Line Size= 0h
PCI IO Address = d800h length 16 enabled
Max Lat        = 0ns
Min Gnt        = 0ns
PCI Int Pin    = NC
Interrupt line = 0
Device Dependent Registers:
0x40: 07 c0 03 80 00 00 00 00 05 00 02 02 00 00 00 00  
0x50: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
0x60: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
0x70: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
0x80: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
0x90: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
0xA0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
0xB0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
0xC0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
0xD0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
0xE0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
0xF0: 00 00 00 00 00 00 00 00 30 0f 00 00 00 00 00 00

Find the entry for the device you want to locate and it'll give you the details on the manufacturer/vendor ID and device ID. You may need to search for keywords (e.g. Audio) in order to identify your device.

You can search the manufacturer's website for information, or use the vendor and device IDs to cross-reference with /usr/include/hw/pci_devices.h. You can also search http://www.pcidatabase.com//.

CD-ROMs

You usually attach CD drives to a SCSI or EIDE(ATA) bus; which driver you use depends on the bus. Ensure that the hardware is set up correctly and that the BIOS detects the hardware properly. If you attached the CD drive to an EIDE bus, simply use the devb-eide driver. If the drive is on a SCSI bus, you need to determine the proper driver for your SCSI interface; see "Hard disks," below.

The cam-cdrom.so shared object provides a common access method for CD-ROM devices. The drivers load the cam-cdrom.so and fs-cd.so shared objects by default.

CD-ROM devices support the ISO-9660 filesystem, and appear in the /dev directory as /dev/cdx, where x is the number of the drive, starting at 0. Simply mount the drive using the mount utility, specifying cd as the type of filesystem:

mount -tcd /dev/cd1 /fs/cdrom

You don't need to remount the drive when you change CDs. For information about specific options (e.g. disabling audio extensions, disabling multisession support), see cam-cdrom.so and fs-cd.so in the Utilities Reference.

DVDs

Neutrino supports DVD ROMs and RAMs:

DVD ROM
You can treat DVD drives like CD-ROM drives. However, Neutrino currently doesn't support UDF format (DVD disks). You can use DVD drives to read CDs, and the setup for a DVD ROM is the same as for a CD-ROM. For more details, see "CD-ROMs," above.
DVD RAM
You can treat DVD RAM drives like hard disks. They appear in the /dev directory as a CD, but you can mount and treat them just like a hard disk -- see "Hard disks," below.

Floppy disks

The driver for a floppy drive is devb-fdc. In order to use a floppy disk, you need to ensure that the floppy controller is enabled in the BIOS, and that the BIOS is configured to recognize the correct type of floppy drive (e.g. 1.44MB/2.88MB). The driver uses these locations as default:

If your controller is located at a different address, you can change these locations in the driver's options.


Note: The default cache size specified by io-blk.so is 15% of system memory, which is excessive for devb-fdc. You'll probably want to reduce it to something more reasonable:
devb-fdc blk cache=128K &

The driver creates a /dev/fdx entry, where x is the number of the floppy drive, starting at 0. If no entry appears, the BIOS settings might be incorrect, or there could be a problem with the controller. Check the output from sloginfo for clues.

Once you have an entry in the /dev directory, you need to mount the floppy disk. The mount command detects the type of filesystem you're using (e.g. DOS, QNX 4), but you can also specify it on the command line.

You don't need to remount the drive when you change floppy disks.


Note: Don't remove a floppy while the driver is still reading or writing data; floppies are quite a bit slower than hard disks, so it can take a while. Make sure the drive light is off.

Hard disks

A self-hosted system, by default, detects the disk controller that's installed on the system, and then starts the appropriate driver for it.

On a self-hosted system, the diskboot utility in the OS image starts the block I/O drivers. If you want to change the way that the driver is started, you'll need to change the startup image and the options to diskboot. For example:

diskboot -o devb-eide,blk cache=30m

For more information, see Controlling How Neutrino Starts, and diskboot in the Utilities Reference.

EIDE

EIDE interfaces use the devb-eide driver, which by default automatically detects the interface and devices attached to it. This driver includes support for UDMA (Ultra Direct Memory Access) modes, along with the generic PIO (Programmed Input/Output) modes. The supported hardware list includes adapters and their supported features; see the introduction to this chapter.

You can start the devb-eide driver without any options and, by default, it automatically detects the EIDE controller on the system:

devb-eide &

When the driver starts, it detects all EIDE devices attached to the chain. For each device, the driver creates an entry in the /dev directory (e.g. a hard drive appears as hdx, where x is the number of the drive, starting from 0).

For example, suppose a system has two hard drives installed. The driver creates the following entries in the /dev directory:

/dev/hd0
Usually the primary master.
/dev/hd1
Usually the primary slave, or the next drive on the system (the secondary master).

If the system has one hard drive and a CD-ROM, the entries are:

/dev/hd0
The primary master.
/dev/cd0
The CD-ROM drive.

Note: A slave drive must have a master drive.

When the driver starts, it displays on the console the type of detected hardware, along with other debugging information that gets sent to the system logger, slogger. To view the system log, run sloginfo.


Note: When you view the output from sloginfo, there will likely be a number of ASC_MEDIA_NOT_PRESENT entries. The driver logs these messages if there isn't a CD in the CD-ROM drive. You can generally ignore them.

Troubleshooting for devb-eide

If the driver doesn't detect the interface or drives attached to it:

Here are some other problems that you might encounter and what you should try:

If the drives are detected, but they're running slowly:

SCSI devices

A SCSI (Small Computer Systems Interface) bus is simply another bus that you can attach multiple peripherals to. Neutrino supports many brands and varieties of SCSI adapters; see "Block-oriented drivers (devb-*)" in the Summary chapter of the Utilities Reference.

When the SCSI driver starts up, it scans the bus for attached devices. When the driver finds a supported device, it creates an entry in the /dev directory (e.g. a hard drive is hdx, where x is the number of the drive, starting from 0).

If the driver doesn't find any devices, it might not know the device ID of the adapter. Passing the device ID and vendor ID to the driver often corrects this problem. On a self-hosted system, you can pass these options to the driver via diskboot; see Controlling How Neutrino Starts.

In the following example, the driver automatically scans for SCSI devices on the chain and adds them into the /dev directory as they're found. For example, if the system has four hard drives in it, the entries in the /dev directory are as follows:

When the driver starts, it sends debugging information to the system log, which you can view using sloginfo. This information is often very helpful when you're trying to debug a problem with a SCSI adapter or device.

If the driver doesn't correctly detect a device, check the following:


Note: Under QNX 4, the SCSI drivers didn't support any device that had an ID greater than 6. This isn't a problem under Neutrino.

The maximum rate given for a SCSI device is the maximum theoretical burst interface throughput. Sustained throughput depends on many factors.


SCSI RAID

Currently, Neutrino supports only hardware RAID (Redundant Arrays of Independent Disks) devices. There are many third-party solutions for SCSI RAID available for Neutrino; search for them on the Internet.

LS-120

LS-120 is a SuperDisk drive that uses new technology to greatly improve head alignment, enabling a much greater storage capacity (120 MB) than conventional 3.5-inch disks. Neutrino treats an LS-120 drive like an EIDE drive.

ORB

An ORB drive is a fast, large-capacity, removable storage disk drive that uses 3.5" storage media and attaches to the EIDE (ATA) chain. Ensure that the hardware is set up correctly and that the BIOS detects the hardware properly. An ORB drive is simple to set up, and appears in the /dev directory as a hard disk. For example:

To mount an ORB drive:

mount /dev/hd1 /fs/orb_drive

You don't need to remount the drive when you change disks.

Zip and Jaz disks

Zip and Jaz disks are large-capacity removable storage disks, used for backing up hard disks and for transporting large files. These disks attach to the EIDE(ATA) chain. Before you attempt to use them, ensure that the hardware is set up correctly and that the BIOS detects the hardware properly. These drives are simple to set up, and they appear in the /dev directory as a hard disk. For example:

To mount the drive, type:

mount /dev/hd1 /fs/zip_drive

You don't need to remount the drive when you change disks.

Magnetic optical drives

Magnetic optical (MO) drives are usually attached to a SCSI or EIDE (ATA) bus. Before you attempt to use the drive, ensure that the hardware is set up correctly and that the BIOS detects the hardware properly.

The driver that you need depends on whether the drive is attached to a SCSI or EIDE interface. If it's SCSI, you'll need to determine the proper driver for your SCSI interface. If it's EIDE, simply use the devb-eide driver. For more information, see "Hard disks," above.

The MO drive should appear in your /dev directory as /dev/mox, where x is the number of the drive, starting at 0.

To mount the drive, type:

mount /dev/mo0 /fs/mo_drive

You don't need to remount the drive when you change disks.

Input devices

The devi-* set of drivers handles input under Photon. The type of input device attached to your system determines which driver you need to use. Photon input can consist of a single mouse, a mouse and a keyboard, or many mice at the same time (provided you have the space).

The inputtrap utility automatically detects basic input devices (non-USB keyboards and mice). The Photon startup script invokes this utility after starting the graphics adapters.

You can override the automatic detection by creating an input trap file, /etc/system/trap/input.hostname. (This is the default location; you can change it if you want to.) Each line of this file invokes a driver:

Mice and keyboards

Mice and keyboards both use the devi-hirun driver. The type of mouse attached to your system determines which options you need to use. For a serial mouse, you need to specify the correct protocol (e.g. the Microsoft Mouse protocol).

Keyboards are detected on these interfaces:

If inputtrap detects a serial Microsoft mouse and a keyboard interfaced through the file descriptor provided by opening /dev/kbd, it invokes devi-hirun like this:

devi-hirun kbd fd -d/dev/kbd msoft fd &

If inputtrap detects a PS/2 mouse interfaced through the auxiliary port on the keyboard controller (mousedev) and a keyboard interfaced through the primary keyboard port on the keyboard controller (kbddev), it invokes devi-hirun like this:

devi-hirun kbddev ps2 mousedev &

Once the mouse has been started, you can change the behavior of the mouse by using the Photon Input configuration utility. You can start it by typing input-cfg on the command line, by selecting Mouse in the shelf, or by choosing Launch-->Configure-->Mouse.

Currently, there's no support for USB keyboards in text mode, but Intel machines can use BIOS emulation to support them. Photon supports USB mice and keyboards; for more information, see "USB devices" later in this chapter.

Touchscreens

Neutrino supports various touchscreens; check the list of supported hardware on our website to determine which driver to use for yours. See also "Input drivers (devi-*)" in the Summary chapter of the Utilities Reference. Determine which options are appropriate for your setup, and then start the driver. For example, here's how to start the driver for a Dynapro SC4 touchscreen:

devi-dyna dyna -4 fd -d/dev/ser1 &

This command starts the driver, devi-dyna, using the SC4 protocol (-4), and a file descriptor that's attached to serial port 1 (fd -d/dev/ser1).

When you start the driver for the first time, it returns an error stating that it can't read the calibration file. To calibrate the touch screen, use the calib utility, while running Photon.

Audio cards

By default, the operating system detects your audio card. The enumerators identify the card and use io-audio to start it. Audio drivers in Neutrino are very simple to initialize. When you use io-audio, you can use the -d option to pass the driver:

io-audio -vv -d audiopc &

To see what other options you can use, see the documentation for io-audio in the Utilities Reference and for your specific card.

If the operating system doesn't detect your card properly, you can manually start the driver. In order to do this, you need to identify the card. You can find a list of supported hardware on our website; see the introduction to this chapter.

ISA cards

ISA cards are either Plug-and-Play or not. You typically have to manually set up non-PnP ISA devices. In order to identify your device, you need to have the manual for your device or have a way to contact your device's manufacturer (e.g. via their website). There isn't currently a Neutrino utility that lists the ISA devices that are installed on a system.

Non-PnP-based

With non-PnP cards, you can manually start the driver and specify the I/O port, IRQ, and DMA channel. For example, this command starts the Sound Blaster driver:

io-audio -dsb ioport=port,irq=req,dma=ch,dma1=ch &

To find out what to set the I/O port and IRQ to, manually open the system and look at the card. Then, start the driver using the configuration settings that the card is set to.

Ensure that the I/O port and IRQ are reserved in the BIOS for non-PCI devices. If you're using a Sound Blaster card, check the following:

PnP-based

The device enumerator should configure and start ISA PnP cards. If it doesn't, you might need to obtain a copy of isapnp, which is used to initialize ISA PnP cards. Neutrino doesn't supply this utility, but it's freely available on the Internet and has been ported to Neutrino.

PCI Cards

The device enumerator should start PCI cards correctly. If your PCI card doesn't work, swap PCI slots. Sometimes the IRQ that's assigned to the particular slot doesn't work well with the card.

For additional information about the card, use the pci utility. For a list of supported hardware, see our website, as described in the introduction to this chapter.

PCCARD and PCMCIA cards

Neutrino supports PCMCIA 1.0/2.0 and CardBUS type cards. By default, the driver detects the ISA/PCI based controller. If an adapter isn't detected, check the supported hardware page to ensure that your PC Card adapter's chipset is supported. Currently the driver doesn't let you specify the adapter's I/O port and IRQ, but you can specify the card's I/O port and IRQ.

If the driver fails to start:

To display PC Card information, use the pin utility. The output that appears on your screen should look like this:

# pin
Sock    Func    Type          Flags          PID  Base   Size    IRQ
1               Empty       -----MF------    None
1               Empty       -----MF------    None
2       0       Network     C---I-+------    None 0x300  32        7
2               Empty       ----MF---------  None

Each socket has two entries because the driver (devp-pccard) supports combination cards that give room for two functions in each slot. The categories displayed in the output example above are:

Sock
The slot where the PC Card is attached. In the example above, the Network card appears in slot 2.
Func
Used when the card is a multifunction PC Card.
Type
A label for the PC Card's function. If the card is a Network card, the Type column displays Network.
Flags
Flags that aren't set are marked as -. The following table lists possible set flags:
This flag: Has a set value of:
C Card in
B Battery low
R Scheduled to be configured
N Not enough resources to configure card
I or M I/O card or memory card
F Not configured
+ Window is part of previous configuration
U Window is an unlockable window
T Window is a temporary window
B Machine booted from this device
X or W Locked exclusive / locked read/write
R Locked read-only
L Level-mode IRQs
S Shared IRQs
A Attribute memory
W Wide (16-bit) memory access
PID
The process ID of the process attached to the PC Card driver (devp-pccard).
Base
The base address of the PC Card. This information is useful for starting device drivers.
Size
The number of bytes in the I/O port range.
IRQ
The PC Card's IRQ. This information is useful when starting the driver manually.

USB devices

A Universal Serial Bus (USB) provides a hot-swappable, common interface for USB devices (e.g network, input, character I/O, audio, and hubs). For more information on USB, USB specifications, and a list of frequently asked questions, see www.usb.org.

If you don't know what kind of USB device you're using, you can use the usb utility to identify it:

usb -vvv | less

The output from this command looks like this:

Device Address             : 1
Vendor                     : 0x05c7 (QTRONIX)
Product                    : 0x2011 (USB Keyboard and Mouse)
Device Release             : r1.12
USB Spec Release           : v1.00
Serial Number              : N/A
Class                      : 0x00 (Independent per interface)
Max PacketSize0            : 8
Languages                  : 0x0409 (English)
Current Frame              : 511 (1024 bytes)
Configurations             : 1
  Configuration            : 1
    Attributes             : 0xa0 (Bus-powered, Remote-wakeup)
    Max Power              : 50 mA
    Interfaces             : 2
      Interface            : 0 / 0
        Class              : 0x03 (HID)
        Subclass           : 0x01 (Boot interface)
        Protocol           : 0x01 (Keyboard)
        Endpoints          : Control + 1
          Endpoint         : 0
            Attributes     : Control
            Max Packet Size: 8
          Endpoint         : 1
            Attributes     : Interrupt/IN
            Max Packet Size: 8
            Interval       : 20 ms
      Interface            : 1 / 0
        Class              : 0x03 (HID)
        Subclass           : 0x01 (Boot interface)
        Protocol           : 0x02 (Mouse)
        Endpoints          : Control + 1
          Endpoint         : 0
            Attributes     : Control
            Max Packet Size: 8 

The vendor and product fields indicate the type of device, and possibly what chipset it uses.

The common types of USB controllers are:

UHCI
Universal Host Controller Interface.
EHCI
Enhanced Host Controller Interface.
OHCI
Open Host Controller Interface (made by others).

Note: The EHCI controller supports high speed signalling only. Either a OHCI or UHCI controller(s) should be present to support low- or full-speed devices. If your system doesn't have an EHCI controller, the device will work at the slower speed.

The operating system needs to run the stack in order to know how to interact with USB devices and controllers.

To start the USB stack, you need to:
  1. Identify your controller.

    The documentation for the hardware should describe the type of controller (OHCI, UHCI, or EHCI). If you don't know what type of controller you're using, you can identify it using:

    pci -vvv

    Find the entry for the USB controller to determine the manufacturer/vendor ID and device ID. You can either find the information on the manufacturer's website (www.usb.org), or use the vendor and device IDs to cross-reference it at http://www.pcidatabase.com//.

    The class codes that appear in the output from pci -vvv are:

    Class Code Controller Type
    0c0300 UHCI
    0c0310 OHCI
    0c0320 EHCI

    There might be multiple chips and therefore multiple drivers that you need to load.

    You can also try running just one of the USB stacks; if it fails, try running another stack.

  2. Log in as root and start the io-usb stack with the appropriate module:

    This should create an entry in /dev called /dev/io-usb/io-usb.


    Note: If you're starting the USB stack and a driver in your startup scripts, make sure that you use the waitfor command to make sure that /dev/io-usb/io-usb has appeared before you start the driver. For example:
    io-usb -dohci
    waitfor /dev/io-usb/io-usb
    devu-prn

  3. When the stack is running, start the device drivers, as described below.

    Note: USB hubs don't need a driver; the stack itself supports them.

Printers

For a USB printer, start the USB stack, and then devu-prn. For example:

io-usb -dohci
waitfor /dev/io-usb/io-usb
devu-prn

Mice and keyboards

Currently, there's no support for USB keyboards in text mode, but Intel machines can use BIOS emulation to support them. Photon supports USB Human-Interface Devices (HID) such as keyboards and mice.

To connect USB HIDs:
  1. Start the USB stack, as described above.
  2. Start io-hid, loading the devh-usb.so module:
    io-hid -dusb
      

    If your system also uses serial or PS/2 input devices, you can load the devh-ps2ser.so module as well.

  3. After starting Photon, start devi-hid for the USB HID devices as follows:
    devi-hid kbd [-u USB_device_number] mouse
      

You can start io-hid in your rc.local file, but not devi-hid, because Photon hasn't started when your system runs rc.local. Instead, add the devi-hid command to the input trap file; see inputtrap in the Utilities Reference.

In Photon, once the devices are running, you can use the input-cfg utility to configure the mouse. From the shelf, click Launch-->Configure-->Mouse. You can use the hidview utility to get information about the human-interface devices.

Touchscreens

For USB touchscreens, start the USB stack, then io-hid, loading the devh-usb.so driver. Then, start devi-microtouch:

io-hid -dusb
devi-microtouch microtouch touchusb

Ethernet adapters

For Ethernet adapters, start the USB stack, then io-net, loading the appropriate driver. For example, to start the driver for a Kawasaki-based USB Ethernet adapter, do the following:

io-usb -dohci
waitfor /dev/io-usb/io-usb
io-net -dklsi [options]

Mass-storage devices

The devb-umass driver supports devices that follow the Mass Storage Class Specification. You can determine that the device is suitable by looking for the following information in the output from usb -vv:

Mass Storage Class  08h

SubClass Code    Command Block Specification
     01h            Reduced Block Command (RBC)
     02h            SFF-8020i, MMC-2 (ATAPI)
     04h            UFI
     05h            SFF-8070i
     06h            SCSI transparent

Protocol Code    Protocol Implementation
     00h            Control/Bulk/Interrupt
                      (with command completion interrupt)
     01h            Control/Bulk/Interrupt
                      (with no command completion interrupt)
     50h            Bulk-Only Transport

To use a USB mass-storage device on a Neutrino system, start io-usb as described above, then the devb-umass driver. By default, this driver creates an entry for disk-based devices in /dev in the form /dev/hdn, where n is the drive number. Once you've started the driver, you can treat the device like a disk.

For example, for a mass-storage device that uses the UHCI controller, type:

io-usb -d uhci
devb-umass cam pnp

Troubleshooting

No device is created in /dev.
The device might not conform to the Mass Storage Class Specification. Check the output from usb -vv.
No fdn device was created in /dev for a floppy drive.
The default name is /dev/hdn. You can use the name command-line option to cam-disk.so to override the prefix.

Character devices

General serial adapters

By default, a serial port driver automatically detects the I/O port and IRQ. A standard PC system uses the devc-ser8250 driver; the BSP documentation indicates the drivers specific to your target hardware.

If the driver doesn't detect all the serial ports, ensure that the ports are enabled in the BIOS. If the ports are enabled, try specifying the I/O port and IRQ of the ports when you start the driver. Use a comma to separate the I/O port and the IRQ; use a space to separate each port-IRQ pair in the command. For example:

devc-ser8250 3f8,4 2f8,3

Note: If you start a serial driver for a UART or modem when another serial driver is already running, you need to use the -u option to give the new driver a number to append to the device name so that it doesn't conflict with any existing /dev/ser entry.

The standard devc-ser8250 driver supports only the RS-232 protocol. The Character Driver Development Kit (DDK) includes the source to devc-ser8250, which you can use to implement any additional protocols or features.

The serial drivers support software and hardware flow control:


Note: In edited mode (-e), flow control is disabled. Don't enable software and hardware flow control at the same time.

Heavy serial port usage can be very taxing on some systems; by default, the serial adapter triggers an interrupt for each character transmitted or received. You can use these options to reduce the number of interrupts:

-T number
Enable the transmit FIFO and set the number of characters to be transmitted at each TX interrupt to 1, 4, 8, or 14. The default is 0 (FIFO disabled).
-t number
Enable the receive FIFO and set its threshold to 1, 4, 8, or 14 characters. The default is 0 (trigger disabled).

A receive timeout guarantees that the characters won't remain buffered too long. For example, imagine that the device receives:

This sentence is coming across the serial port.

By default, the system has to service 47 interrupts to receive this sentence. If you set the receive trigger level to 14, the number of interrupts is reduced to four. This helps the overall system performance, but you're trading off reliability; the higher the receive trigger (-t), the higher the possibility of losing data.

Multiport serial adapters

For multiple serial adapters, you may need to specify the I/O port and IRQs manually in the driver for each port (see "General serial adapters" for examples). By default, the driver should detect the ports and IRQs, but with some multiport adapters, the enumerators don't detect the ports correctly.

You can edit the enumerators to detect your multiport card and have it set up each port for you. You need to edit the /etc/system/enum/devices/overrides file; see the Controlling How Neutrino Starts chapter in this guide, and enum-devices in the Utilities Reference.

Parallel ports

On a standard PC and some x86 systems, parallel ports use the devc-par driver; see the BSP documentation for the driver for your target hardware.

By default, the driver detects the parallel port. If you need to, you can use the -p option to specify the location of the parallel port.

If the driver fails to detect your parallel port, ensure that the port is enabled in the BIOS. If that fails, try specifying the I/O port when you start the driver.

Terminals

On a standard PC and some x86 systems, the devc-con or devc-con-hid driver controls the physical console, which consists of the display adapter, the screen, and the system keyboard. By default, the driver is configured for up to four virtual consoles, /dev/con1 .../dev/con4. The devc-con driver is also the keyboard driver for non-USB keyboards in text mode. You can start the driver with this command:

devc-con &

The devc-con-hid manager is similar to devc-con, but works in conjunction with io-hid and supports PS2, USB, and all other human-interface devices.

For more information, see devc-con and devc-con-hid in the Utilities Reference.

I/O attributes

To set or display the I/O attributes for a character device (tty), use the stty utility. For more information about setting up your terminal, see "Terminal support" in Using the Command Line.

Network adapters

The main steps in setting up a network adapter are:

Identify your NIC

The documentation for the hardware should describe the type of chipset used.

If you don't know what type of chipset you're using, you can identify it using pci -vvv.

Find the entry for the Network controller and it'll give you details on the manufacturer/vendor ID and device ID. Either find the information on the manufacturer's website, or use the vendor ID and device ID to cross-reference it with this online site:

http://www.pcidatabase.com//.

With the information you get from that site, you can visit the QNX supported hardware site; see the introduction to this chapter.

In the Network section, locate your chipset and its associated driver.

Start the driver

Once you've located the correct driver for your hardware, use io-net to start the driver. You can either start the driver as an option to io-net, or you can mount the driver into an already running copy of io-net. For example, to start io-net with the devn-el900.so (3Com 905) module, type:

io-net -d el900 -t tcpip &

To mount the module, type:

io-net -t tcpip &
mount -T io-net devn-el900.so

Note: The driver automatically detects similar network adapters for multiple networks. You can use the mount utility to mount different adapters.

Make sure the driver is communicating properly with the hardware

Use the nicinfo utility to check if you're receiving and sending packets. If you aren't receiving packets on a high-traffic network, the driver and the hardware might not be communicating. Here's some typical output from this command:

Physical Node ID ........................... 000102 C510D4
Current Physical Node ID ................... 000102 C510D4
Current Operation Rate ..................... 100.00 Mb/s full-duplex
Active Interface Type ...................... MII
Active PHY Address ......................... 3
Power Management State ..................... Active
Maximum Transmittable data Unit ............ 1514
Maximum Receivable data Unit ............... 1514
Receive Checksumming Enabled ............... TCPv6
Transmit Checksumming Enabled .............. TCPv6
Hardware Interrupt ......................... 0x5
DMA Channel ................................ 0
I/O Aperture ............................... 0xd400 - 0xd47f
ROM Aperture ............................... 0
Memory Aperture ............................ 0xe6000000 - 0xe6000FFF
Promiscuous Mode ........................... Off
Multicast Support .......................... Enabled

Packets Transmitted OK ..................... 104
Bytes Transmitted OK ....................... 10067
Broadcast Packets Transmitted OK ........... 6
Multicast Packets Transmitted OK ........... 1
Memory Allocation Failures on Transmit ..... 0

Packets Received OK ........................ 1443
Bytes Received OK .......................... 168393
Broadcast Packets Received OK .............. 427970
Multicast Packets Received OK .............. 37596
Memory Allocation Failures on Receive ...... 0

Single Collisions on Transmit .............. 0
Multiple Collisions on Transmit ............ 0
Deferred Transmits ......................... 0
Late Collision on Transmit errors .......... 0
Transmits aborted (excessive collisions) ... 0
Transmits aborted (excessive deferrals) .... 0
Transmit Underruns ......................... 0
No Carrier on Transmit ..................... 0
Jabber detected ............................ 0
Receive Alignment errors ................... 0
Received packets with CRC errors ........... 0
Packets Dropped on receive ................. 0
Ethernet Headers out of range .............. 0
Oversized Packets received ................. 0
Frames with Dribble Bits ................... 0
Total Frames experiencing Collision(s) ..... 0

Note: The output from nicinfo depends on what the driver supports; not all fields are included for all drivers. However, the output always includes information about the bytes and packets that were transmitted and received.

The categories shown in the above example are described below. When dealing with a network problem, start with these:

Physical Node ID

The physical node ID is also known as the Media Access Control (MAC) address. This value is unique to every network card, although some models do let you assign your own address. However, this is rare and generally found only on embedded systems.

If the value represented is FFFFFF FFFFFF or 000000 000000, there's likely something wrong with the setup of the hardware, or you need to assign a MAC address to the card. Check the hardware manual to see whether or not this is the case.


Note: If the hardware didn't get set up correctly, the MAC address may not always appear as shown above.

The first six digits of the MAC address are the vendor ID. Check the entries against the list at http://www.cavebear.com/CaveBear/Ethernet/vendor.html to see if the vendor ID is valid. Then check the card ID (the last 6 digits). The card ID should be something semi-random. A display similar to 444444 is likely incorrect.


Current Physical Node ID

The current physical node ID is shown if a card has been set up to "spoof" the ID of another card. Basically, a parameter is passed to the driver telling it that the node's ID is actually the value that appears. Depending on the card, some drivers will accept this. What spoofing does on a higher (software) level, is filter out the packets that were meant for this node ID. This method is considerably slower than if you let the card filter out the packets on a hardware level. Because the card is set in promiscuous mode, it has to accept all packets that come in and use a software mode to sort them.

Another way of thinking about this is to compare it to a postal system, where if we wanted to "pretend" to be someone else, we would accept all mail from the Post Office. However, we would then have to sort all the mail. This would take a much longer time compared with the amount of time the Post Office would take to presort the mail, and give us only the mail addressed to us. For more information, see "Promiscuous Mode," below.

Current Operation Rate

The media rate is the speed at which the network card operates. On most cards, it's either 10Mb/s or 100 Mb/s. This display also shows what form of duplex the card uses. Most cards run at half or full-duplex transmission:

The easiest way to illustrate this is to think of a road. If the road has two lanes, it's full-duplex, because cars can drive in both directions at the same time without obstructing the other lane. If the road has only a single lane, it's half-duplex, because there can be only one car on the road at a time.

When you examine the media rate, check the speed, the form of duplex, and what the hub supports. Not all hubs support full-duplex.

Active Interface Type

This is the type of interface used on the Ethernet adapter. This is usually UTP (unshielded twisted pair), STP (shielded twisted pair), Fiber, AUI (Attachment Unit Interface), MII, or BNC (coaxial).

Active PHY Address

This is an identifier that tells you which of the physical PHYs were used to interface to the network. The numbers range from 0 - 31 and change, depending on whether or not you specified a specific PHY or if you let the driver select the default (which varies from card to card).

Power Management State

This value tells you the NIC's current power status: Off, Standby, Idle, or Active. If you can't send or receive packets, make sure the status is Active; if it isn't, there may be a problem with power management on your system.

Maximum Transmittable data Unit

The Maximum Transmittable data Unit (MTU) is the size of the largest frame length that can be sent on a physical media. This isn't commonly used for debugging; however, it may be useful for optimizing a network application. A value of 0 is invalid and is a good indicator that the card isn't set up correctly. The default value is 1514.

Maximum Receivable data Unit

This is the MTU's complement; it affects the largest frame length that can be received. The default value is 1514.

Receive Checksumming Enabled, Transmit Checksumming Enabled

Not all cards support these options. If your adapter supports them, they tell your card which check-summing method to use: IPv4, TCPv4, UDPv4, TCPv6, or UDPv6.

Hardware Interrupt

The hardware interrupt is the network card's interrupt request line (IRQ). How an IRQ is assigned depends on whether the card is a PCI or an ISA card. In the case of a PCI card, pci-bios assigns the IRQ; for an ISA card, the IRQ is hard-wired.


Note: Two ISA devices can't share the same IRQ, but two PCI devices can.

DMA Channel

This is the DMA channel used for the card. This varies, depending on the card and on the channels it has available.

I/O Aperture

The I/O aperture is a hexadecimal value that shows the address in I/O space where the card resides. The I/O aperture uses the I/O address between the given values to locate and map the I/O ports. The range depends on the platform.

Memory Aperture

The memory aperture is a hexadecimal value that shows the address in memory where the card's memory is located. The memory aperture uses the memory address between the given values to locate and map memory. The range depends on the platform.

ROM Aperture

The ROM aperture is a hexadecimal range that shows the address of the card's ROM. The ROM aperture uses the memory address between the displayed values to locate and map memory.

Promiscuous Mode

When a card is placed in promiscuous mode, the card accepts every Ethernet packet sent on the network. This is quite taxing on the system but is a common practice for debugging purposes.

Also, when a card is placed in promiscuous mode, a network MAC address can be spoofed, i.e. the card accepts all packets whether they're addressed to it or not. Then on a higher (software) level, you can accept packets addressed to whomever you please. Promiscuous mode is disabled by default.

Multicast Support

When you enable multicast mode, you can mark a packet with a special destination, so that multiple nodes on the network may receive it. Multicast packets are also accepted.

Packets Transmitted OK

Before you look at this value, determine that some form of network transfer (ping, telnet, file transfer) was attempted. If a card isn't set up properly, the number of sent packets shown here is either very small or zero. If the card isn't displaying any sent packets, the cause is probably a driver problem. Check all the options you're passing to the driver; one or more may be incorrect.

Bytes Transmitted OK

This is the number of bytes of data sent on the network. This value increases with the number of packets transmitted on the network.

Total Packets Transmitted Bad

You can use this statistic to determine if you have faulty hardware. If all the sent packets are reported as bad, there's likely a hardware problem, but you might be using the wrong driver. Check the hardware for compatibility. If it looks as if it's hardware-related, try switching the hardware to see if the problem disappears.

Broadcast Packets Transmitted OK

This is the number of broadcast packets transmitted from the NIC.

Multicast Packets Transmitted OK

This is the number of multicast packets transmitted from the NIC.

Memory Allocation Failures on Transmit

Before transmitting data, the driver reserves system memory for a buffer to hold the data to be transmitted. Once the card is ready, the buffer is sent to it.

When a memory-allocation error occurs, the system is likely very low on memory. Make sure that there's sufficient memory on the system; if you continuously get this error, consider adding more memory. Another thing to check for is memory leaks on the system, which may be slowly consuming system memory.

Packets Received OK

This value states how many packets were successfully received from the network card. If a card is having problems receiving data, check the cables and the hub connection. Problems receiving data might be related to the driver. It's possible the driver can be properly set up and able to send data, but may not be able to receive. Usually when data is received but doesn't get sent, the driver is the cause. Check the driver's setup to make sure it's initialized correctly. Use sloginfo to check the system log for clues.

Bytes Received OK

This is the number of bytes of data received from the network. This value increases with the number of packets received.

Single Collisions on Transmit

This is the number of collisions that were encountered while trying to transmit frames.

The NIC checks for a carrier sense when it knows that the network hasn't been used for a while, and then starts to transmit a frame of data. The problem occurs when two network cards check for the carrier sense and start to transmit data at the same time. This error is more common on busy networks.

When the NICs detect a collision, they stop transmitting and wait for a random period of time. The time periods are different for each NIC, so in theory, when the wait time has expired, the other NIC will have already transmitted or will be still waiting for its time to expire, thus avoiding further collisions.

You can reduce this type of problem by introducing a full-duplex network.

Multiple Collisions on Transmit

This error is due to a attempted transmission that has had several collisions, despite backing off several times. This occurs more frequently on busy half-duplex networks. If there are a lot of these errors, try switching to a full-duplex network, or if the network is TCP/IP based, try introducing a few switches instead of hubs.

Deferred Transmits

Commonly found on half-duplex networks, this value doesn't mean that there are problems. It means that the card tried to send data on the network cable, but the network was busy with other data on the cable. So, it simply waited for a random amount of time. This number can get high if the network is very busy.

Late Collision on Transmit errors

Late-collision errors that occur when a card has transmitted enough of a frame that the rest of the network should be aware that the network is currently in use, yet another system on the network still started to transfer a frame onto the line. They're the same as regular collision errors, but were just detected too late.

Depending on the protocol, these types of errors can be detrimental to the protocol's overall throughput. For example, a 1% packet loss on the NFS protocol using the default retransmission timers is enough to slow the speed down by approximately 90%. If you experience low throughput with your networking, check to make sure that you aren't getting these types of errors. Typically, Ethernet adapters don't retransmit frames that have been lost to a late collision.

These errors are a sign that the time to propagate the signal across the network is longer than the time it takes for a network card to place an entire packet on the network. Thus, the offending system doesn't know that the network is currently in use, and it proceeds to place a new frame on the network.

The nodes that are trying to use the network at the same time detect the error after the first slot time of 64 bytes. This means that the NIC detects late collisions only when transmitting frames that are longer than 64 bytes. The problem with this is that, with frames smaller than 64 bytes, the NIC can't detect the error. Generally, if you experience late collisions with large frames on your network, you're very likely also experiencing late collisions with small frames.

These types of errors are generally caused by Ethernet cables that are longer than that allowed by the IEEE 802.3 specification, or are the maximum size permitted by the particular type of cable, or by an excessive amount of repeaters on the network between the two nodes.

Another thing to note is that these errors may actually be caused by a node on the network that has faulty hardware and is sending damaged frames that look like collision fragments. These damaged frames can sometimes appear to a network card to be a late collision.

Transmits aborted (excessive collisions)

This error occurs if there are excessive collisions on the network. The network card gives up on transmitting the frame after 16 collisions. This generally means that the network is jammed and is too busy.


Note: Routers also give up on transmitting a frame if they experience excessive collisions, but instead of alerting the original transmitter, routers simply discard the frame.

If these sort of errors are being experienced, see if the network can be reduced, or introduce a strategically placed switch into the network to help eliminate the number of packets that are being placed on the entire network. Switching to a full-duplex network also resolves these problems.

Transmits aborted (excessive deferrals)

Aborted transmissions due to excessive deferrals mean that the NIC gave up trying to send the frame, due to an extremely busy network. You can resolve this type of problem by switching to a full-duplex network.

Transmit Underruns

Chips with a DMA engine may see this error. The DMA engine copies packet data into a FIFO, from which the transmitter puts the data on the wire. On lower-grade hardware, the DMA might not be able to fill the FIFO as fast as the data is going on the wire, so an underrun occurs, and the transmit is aborted.

No Carrier on Transmit

When the NIC is about to transfer a frame, it checks first to make sure that it has carrier sense (much like before you dial the phone, you check to make sure you have a dial tone). While the NIC is transmitting the frame, it listens for possible collisions or any errors. These errors occur when a NIC is transmitting a frame on the network, and it notices that it doesn't see its own carrier wave (much like when you are dialing a number on the phone and you can hear the dial tones being pressed).

These errors are caused by plugging and unplugging cables on the network and by poor optical power supplied to the Fiber Optic Transceiver (FOT).

Jabber detected

You typically see this error only on a 10Mbit network. It means that a network card is continuing to transmit after a packet has been sent. This error shouldn't occur on faster networks, because they allow a larger frame size.

Receive Alignment errors

A receive-alignment error means that the card has received a damaged frame from the network. When one of these errors occurs, it also triggers an FCS (Frame Check Sequence) error. These errors occur if the received frame size isn't a multiple of eight bits (one byte).

These errors are commonly due to faulty wiring, cable runs that are out of the IEEE 802.3 specification, a faulty NIC, or possibly a faulty hub or switch. To narrow down this problem, do a binary division of the network to help eliminate the source.

Received packets with CRC errors

An entry in this field indicates the number of times, on a hardware level, the card received corrupt data. This corruption could be caused by a faulty hub, cable, or network card.

The best way to try to solve Cyclic Redundancy Check (CRC) errors is to do a binary division of the systems on the network to determine which system is sending bad data. Once you've done that, you can start replacing the hardware piece by piece. Because this error is on the receiving end, it's difficult to determine if the CRC is bad on a sent packet.

Packets Dropped on receive

This usually means you got an overrun while receiving a packet. This has to do with DMA and the FIFO, like a Transmit Underrun, except in this case, the DMA engine can't copy the packet into memory as fast as the data is coming from the network, and the packet gets dropped. Like the Transmit Underrun, this is generally due to poor hardware.

Ethernet Headers out of range

This entry indicates the number of packets whose Ethernet type/length field isn't valid.

Oversized Packets received

An oversized packet is simply a received packet that was too big to fit in the driver's Receive buffer.

Frames with Dribble Bits

Dribble bits are extra bits of data that were received after the Ethernet CRC. They're commonly caused by faulty hardware or by Ethernet cabling that doesn't conform to the 802.3 specifications.

Total Frames experiencing Collision(s)

This is the total number of frames that have experienced a collision while trying to transmit on the network. This can sometimes be high, depending on how busy the network is. A busy network experiences these types of errors more often than a quiet one.

Modems

You can have any of the following types:

Internal modems

Internal modems can be ISA and are either Plug-and-Play (PnP) or not. You have to manually set up non-PnP ISA devices.


Note: In order to identify your device, you need to have the documentation for the device, or be able to contact the device manufacturer to have it identified. Currently, there is no utility within Neutrino to obtain a list of ISA devices installed on your system.

ISA non-PnP

Configure the modem to use an I/O port and IRQ that don't conflict with anything else in the system.

The devc-ser8250 driver should autodetect the modem and it should appear in the /dev directory as serx, where x is an integer.


Note: There may be more than one entry under the name. Assume that the first two entries represent the comm ports of the system. Any additional entry is likely the modem. If in doubt, try all ser entries with qtalk. For more information, see "Testing Modems," below.

Entries will usually appear in this fashion:

Comm1 is enabled in the BIOS
Comm2 is disabled
Modem is configured to Comm2's ioport and IRQ

In the /dev directory you'll see:

ISA PnP

If you have an ISA PnP modem that can be manually assigned an IRQ and I/O port via jumpers, we recommend that you use the manual method rather than Plug-and-Play.

The devc-ser8250 driver should automatically detect the modem, which should appear in the /dev directory as serx, where x is an integer.


Note: There may be more than one entry in /dev under the name ser. Assume that the first two represent the comm ports of the system. Any additional entry is likely the modem. However, if in doubt, try all ser entries with qtalk. For more information, see "Testing Modems," below.

If the modem isn't detected, seek out the isapnp utility to configure the modem's I/O port and IRQ, and then specify them when you start devc-ser8250.


Note: If you start a serial driver for a UART or modem when another serial driver is already running, you need to use the -u option to give the new driver a number to append to the device name so that it doesn't conflict with any existing /dev/ser entry.

PCI-based modems

The devc-ser8250 driver should automatically detect the modem, which should appear in the /dev directory as serx, where x is an integer.

If no entry is created, check the output from pci -vvv and see what I/O port and IRQ are assigned to the modem. Use the correct I/O port and IRQ from pci -vvv to start devc-ser8250. When you use the appropriate I/O port and IRQ, the /dev directory entry gets created for you.

External modems

External modems are easy to set up. Look in the /dev directory for the serial port that the modem is attached to. You'll attach this at the back of the system. If you know the modem is attached to serial port 1, then look in the /dev directory for ser1.

Cable Modems / ISDN

We assume that your cable modem is attached to your system via a network card and that the driver for your card has been started and is running properly. If this isn't the case, see "Network adapters," earlier in this chapter.

To set your configuration:
  1. Start the TCP/IP configuration tool by typing phlip on the command line, by selecting Network from Photon's shelf, or by choosing Launch-->Configure-->Network.
  2. Go to the Devices tab and use these settings:
  3. Go to the Network tab and use these settings:
  4. Reboot your machine. DHCP will start automatically.

Testing modems

You can use qtalk to test your modem:

  1. Make sure the modem is plugged into the phone line.
  2. Use the stty command to set the modem's baud rate. For example, to set the speed of the modem on /dev/ser1 to 57600 (56K modems use this speed), type:
    stty baud=57600 < /dev/ser1
      
  3. Type qtalk -mdevice, where device is the name of the serial port (e.g. /dev/ser1).
  4. Type at. The modem should reply OK.

Troubleshooting modems

If you followed the instructions above, but the modem doesn't reply OK, check the following:

Video cards

Our website includes a list of the video cards Neutrino supports; see the introduction to this chapter.

Automatically detecting your card

By default, the operating system uses the crttrap utility to detect your video card.

We provide crttrap as a convenience utility; in a static hardware environment (embedded board), you shouldn't need it. Ensure you have a graphics-modes file or the correct command line in your startup scripts to start your video card.


Note: Don't run crttrap while you're running Photon.

The crttrap program queries the card to get all of its possible configurations and creates a file called /etc/system/config/graphics-modes that you can edit. The first line in this file is the one that io-graphics uses. For information about the different graphics options, see io-graphics in the Utilities Reference.

In an embedded system, you don't need to use crttrap to get the configuration, because it isn't likely to change. Instead, you can call io-graphics directly, specifying the appropriate options. For example:

io-graphics -dl devg-rage.so [options....]

Neutrino's default setup starts the graphics driver for you via the ph script located in /usr/bin.

Changing video modes in Photon

To change the video modes of your graphics adapter in Photon, use the Display Configuration tool. You can start it by typing phgrafx on the command line, by selecting Graphics from the shelf, or by choosing Launch-->Configure-->Graphics.

To change the video modes:
  1. Select the configuration that you want to use.
  2. Click Apply.

    The screen turns black, and then should go into the new mode. If the mode you selected didn't work properly, you can wait for 15 seconds, at which point the display automatically reverts to the previous settings, or you can press Esc or Enter.

  3. When the mode has changed and seems to be working properly, click Accept.

This utility also lets you change the driver, resolution, refresh rate, and palette (8-bit color mode only), and disable the hardware cursor.

If you want to edit the command line that's used to start the adapter, click the Advanced button. This is the same as editing the top line in the graphics-modes file.

Manually setting up your video card

To manually set up your video card:
  1. Identify your video adapter. The documentation for the hardware should describe the chipset used on your adapter.
  2. Identify which driver you should be using. Use the list of supported hardware to determine which driver is appropriate for your adapter; see the introduction to this chapter.
  3. Test the driver by using io-graphics to start it manually:
    io-graphics -drage \
    vid=0x1002,did=0x4755,index=0,xres=1024,photon,yres=768,bitpp=16,refresh=80 \
    -pphoton

    For information about the options, see "Graphics drivers (devg-*)" in the Utilities Summary in the Utilities Reference, as well as the entry for io-graphics.

    You'll also need to start Photon and other utilities to ensure that this is working correctly. The best thing to do is create a script that starts Photon. See the ph script for ideas and examples. You can also manually add this command to the graphics-modes file at the top line to test it out.

Setting up multiple displays

You can use the io-graphics configuration file to set up a dual- or multiple-monitor display. You can configure either two or more separate cards for multiple displays, or a single device to support multiple displays. These graphics device drivers support multiple displays:

devg-radeon.so
Graphics driver for ATI RADEON chipsets
devg-matroxg.so
Graphics driver for Matrox Millenium G-series chipsets

For specific chipsets and the number of displays supported, see the documentation for devg-radeon.so and devg-matroxg.so in the Utilities Reference.

For information about the io-graphics configuration file format and the options you can set, see "The io-graphics configuration file" in the documentation for io-graphics in the Utilities Reference.


Note:
  • You can use the phgrafx utility or io-graphics command line to configure only single displays, not multiple displays.
  • We don't guarantee support for arbitrary combinations of video cards.

To create a configuration file for a Radeon 9700 Pro video card for dual-headed display:
  1. Create the [GLOBAL] section. This has a single entry, devices, that lists all the video cards supported. In this example, there's one device:
    [GLOBAL]devices = radeon
  2. For each device, create a [DEVICE.name] section. This section configures the hardware-specific settings. In this example, we set the:
    [DEVICE.radeon]
    dllpath         = devg-radeon.so
    
    pci_vendor_id       = 0x1002
    pci_device_id       = 0x4e44
    pci_index           = 0
    
    displays            = 2
    
    plugins             = photon
    
    photon          =
  3. For each display, create a [DEVICE.name.number] section. These sections configure each display. In this example, each display has the same resolution (1024 * 768), color depth (16 bit color), and refresh rate (60 Hz). Notice that the second display Photon region is offset by 1024, the width of the first display.
    [DEVICE.radeon.0]
    xres =  1024
    yres =  768
    bitpp =  16
    refresh = 60
    
    [DEVICE.radeon.1]
    xres = 1024
    yres = 768
    bitpp = 16
    refresh = 60
    region_x = 1024
  4. For each plugin, create a [PLUGIN.name] section. In this example, we set the Photon plugin DLL:
    [PLUGIN.photon]dllpath             = gri-photon.so

Save the configuration file, in this case as /usr/photon/config/radeon.conf. Load the configuration file and start the graphics driver by using the -c option of io-graphics:

io-graphics -c/usr/photon/config/radeon.conf

Here's the complete example:

[GLOBAL]
devices = radeon

[DEVICE.radeon]
dllpath         = devg-radeon.so

pci_vendor_id       = 0x1002
pci_device_id       = 0x4e44
pci_index           = 0

displays            = 2

plugins             = photon

photon          =

[DEVICE.radeon.0]
xres =  1024
yres =  768
bitpp =  16
refresh = 60

[DEVICE.radeon.1]
xres = 1024
yres = 768
bitpp = 16
refresh = 60
region_x = 1024


[PLUGIN.photon]
dllpath             = gri-photon.so

Here's a second example that shows how to use two different devices for two displays:

[GLOBAL]
devices = banshee rage128

[DEVICE.banshee]
dllpath         = devg-banshee.so
pci_vendor_id   = 0x121a
pci_device_id   = 0x5
pci_index       = 0
plugins         = photon

photon =
xres = 1280
yres = 1024
bitpp = 32

[DEVICE.rage128]
dllpath     = devg-ati_rage128.so
pci_vendor_id   = 0x1002
pci_device_id   = 0x5050
pci_index   = 0
plugins     = photon

photon =
xres = 1024
yres = 768
bitpp = 16
region_x = 1280

[PLUGIN.photon]
dllpath             = gri-photon.so

Troubleshooting your video card

Here are some things to check if crttrap fails to detect your video card or has problems:

The display is slightly misaligned on the monitor.
Each monitor behaves differently in certain resolutions and refresh rates. If Photon seems to be slightly off center, you may need to use the controls on your monitor to adjust the display to properly align with the video mode. See your monitor's documentation for more information.
The refresh rate isn't correct, the display isn't centered, or (in the worst case) there's no display at all.
The timings set by drivers might not match the timings required by the monitor or LCD. You might have to edit /usr/photon/config/crtc-settings. This file contains the timing information required by many drivers to set the standard resolutions and refresh rates.

Note: Many older drivers, as well as the generic drivers, don't use this file, because they use the video BIOS to set the graphics mode.

If this file isn't present, the timings are calculated using a generic timing formula (GTF). The GTF isn't completely accurate; you can manually edit the crtc-settings file to set the exact timing for the resolution and refresh rate.

At least the following drivers use this file:

The modes detected are incorrect.
In some circumstances, a card's modes file doesn't list all the modes that the documentation for the card says it should. Sometimes there are variants of cards that are slightly different from what we have had internally or what the documentation describes. You can try manually setting up the card (see "Manually setting up your video card," above) to see if that helps. If it still fails, you may need to contact Technical Support.
The video mode changed to a mode that doesn't work.
If you've changed the video mode to a mode that either your monitor or graphics card doesn't support and that causes Photon to be displayed improperly, you can revert to a previous mode, as follows:
  1. Restart the system and boot into safe mode (don't start Photon).
  2. Clear the modes file. From the command line type: crttrap clear
  3. Restart your system and try to detect your video card again.
The crttrap program hangs.
If crttrap hangs (i.e. it doesn't start Photon and leaves you with a black screen), try the following:
  1. Restart the system and boot into safe mode (don't start Photon).
  2. Ensure that your graphics card is supported.
  3. Clear the modes file. From the command line type:
    crttrap clear
  4. Restart your system and try to detect your video card again.

If this fails, clear the modes file, but don't restart the system. Then run crttrap manually from the command line with the verbose option:

crttrap trap -VVVVV

If crttrap hangs again, you should be able to see where it failed or what the last adapter it tried to detect was. If you can determine the adapter that it failed to trap, remove it from the trap list by editing /etc/system/config/graphics-traplist.

The list that's generated comes from the enumerators, so you might have to change the enumerators so they no longer detect the card in your system, (e.g. if you have two video cards in your system). You can find the enumerators in /etc/system/enum/devices/graphics.

Once you've removed the offending device from the traplist, check to see if crttrap detects the card properly:

crttrap trap -VVVVV

If crttrap still hangs, try setting the mode manually by editing /etc/system/config/graphics-modes. Create this file it if it doesn't already exist.

For more information, see "Manually setting up your video card," above. Also keep in mind that you can always run the Vesa generic driver, devg-vesabios.so.

Your graphics card isn't detected.
If you have a card that you expect to work with one of our accelerated drivers, but you get only the generic drivers detected by crttrap, you might have a chipset that's missing from the graphics enumerator. Try the following:
  1. Look in /etc/system/enum/devices/graphics for the driver that you think you should run. For example, if you're using a Radeon card, look for devg-radeon.so.
  2. Edit /etc/system/enum/devices/overrides and add an entry for your card. You need to specify the PCI Vendor and Device ID of the chipset, which you can find by using the pci utility. Add a line after the last known PCI ID and before the line:
    cfg(fname, /etc/system/config/graphics-traplist')  
      
  3. Save the file and reboot the system. If you edited the enumerator correctly, there should be an entry in /etc/system/config/graphics-traplist with the driver you hope to run.
  4. Run:
    crttrap clear
    crttrap trap
      
  5. The driver you want should now have been used and detected.

Note: Sometimes this procedure works, other times it doesn't. If it doesn't work, use one of the generic drivers or contact us about adding support for your graphics chipset.

Even if this procedure works, we can't guarantee the driver will work as expected. If the device ID wasn't in the graphics enumerator, we haven't tried that hardware and therefore can't guarantee it will work properly.