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

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
Caution: This utility is intended for debugging purposes; running it on an active system may cause some devices to hang.

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 and DVDs

You usually attach CD and DVD 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 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.

By default, the drivers load the cam-cdrom.so shared object, which provides a common access method for CD-ROM devices. Depending on how you start the driver, it also loads one of the following:

Note: We've deprecated fs-cd.so in favor of fs-udf.so.

CD-ROM and DVD-ROM devices both 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 or udf as the type of filesystem. For example: 

mount -t cd /dev/cd0 /fs/cdrom
mount -t udf /dev/cd0 /fs/dvdrom

You don't need to remount the drive when you change disks. For information about specific options, see cam-cdrom.so, fs-cd.so, and fs-udf.so in the Utilities Reference.

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 RAM, which is excessive for devb-fdc. You'll probably want to reduce it to something more reasonable: 
    devb-fdc blk cache=512K &
  • The device enumerator (see “Device enumeration” in the Controlling How Neutrino Starts chapter) doesn't start devb-fdc by default. If your system has a floppy drive, you can start the driver manually or uncomment the devb-fdc lines in the /etc/system/enum/devices/block file.

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. The drivers for hard disks load the cam-disk.so shared object, which provides a common access method for hard disks.

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 the devb-* (block-oriented) drivers in 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 drivers for optical disks load the cam-optical.so shared object, which provides a common access method for optical disks.

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.

RAM disks

A RAM disk is a storage area that exists only in memory but looks like a hard disk. You can add one to your system by using devb-ram, but this is a RAM disk with the overhead of a block filesystem; by default, it's initialized and formatted for an fs-qnx4.so filesystem (unless you specify the ram nodinit option).

Note: By default, io-blk.so allocates 15% of system RAM for cache. The devb-ram system looks like a disk drive to io-blk.so, so it doesn't know that the cache is unnecessary. You should use the blk cache=512k option to reduce the cache size to the minimum.

A better way of creating a RAM disk is to use the blk ramdisk=... option, which creates an internal RAM disk that io-blk.so does know is RAM and doesn't need to be copied via cache. It uses a 4 KB sector size.

If you already have any other devb-* driver running, then you can simply piggyback the RAM disk on it (by adding, for example, blk ramdisk=10m to the invocation of that devb- driver).

If you really want a separate devb-ram, then it can be the container for an internal RAM disk too, with an invocation like this: 

devb-ram disk name=ram ram capacity=0,nodinit blk ramdisk=10m,cache=0,vnode=256

Ignore the 0-sized /dev/ram1 that devb-ram creates, and use the /dev/ram0, which is from io-blk.so. You need to manually dinit it and mount it first. For example: 

dinit /dev/ram0
mount -tqnx4 /dev/ram0

This approach has superior performance because it eliminates the memory-to-memory copies of devb-ram, it bypasses cache lookups, and the 4 KB sectors have smaller overheads.

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.

The devc-con-hid driver supports USB keyboards in text mode (devc-con doesn't). 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 the devi-* input drivers in 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

Once you've done this, follow the instructions in the Printing chapter in this guide.

Mice and keyboards

The devc-con-hid driver supports USB keyboards in text mode (devc-con doesn't). 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-pkt*, 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-pkt-v4 -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-pkt* to start the driver. You can either start the driver as an option to io-pkt*, or you can mount the driver into an already running copy of io-pkt*. For example, to start io-pkt-v4-hc with the devn-el900.so (3Com 905) module, type: 

io-pkt-v4-hc -d el900 -t tcpip &

To mount the module, type: 

io-pkt-v4-hc -t tcpip &
mount -T io-pkt 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.

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 Display from the shelf, or by choosing Launch-->Configure-->Display.

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 disable the hardware cursor.

Refer to the phgrafx chapter for information about changing the command line that is used to start the display adapter.

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. Edit your /etc/system/config/display.conf configuration file according to your hardware specifications. For more information about configuring a graphic device driver, see “The io-display configuration file”.
    Note: At this point, you can simply restart your system for the configuration changes to take affect. The following steps describe the process of manually stopping and restarting your graphics driver.
  3. In text mode, slay io-display, and ensure that the process has stopped.
    Note: Photon must not be running when you perform this step.
  4. Run io-display -dvid=0xVVVV,did=0xDDDD where VVVV is the vender ID, and DDDD is the device ID of the graphic card.
  5. Restart photon by running /usr/bin/ph.

For information about the options, see the devg-* graphics drivers in the Utilities Reference, as well as the entry for io-display.

Setting up multiple displays

You can use the io-display 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.

GF

In order to support multiple displays in GF, you must manually create a display.conf configuration file before running io-display.

The following example shows a configuration file that is set up to enable dual displays using the poulsbo graphics driver: 

device {
            drivername=poulsbo
            vid=0x8086
            did=0x8108
            modeopts=/etc/system/config/poulsbo.conf
            deviceindex=0
            display {
                        xres=800
                        yres=480
                        refresh=60
                        pixel_format=argb8888
            }

            display {
                        xres=800
                        yres=480
                        refresh=60
                        pixel_format=argb8888
            }


}

Photon

The following examples describe how to configure multiple displays using Photon.

Configuring multiple displays with multiple video cards

When multiple video devices are available, a configuration file that contains entries for each supported device is automatically generated at bootup. The video card with the display value of index 0 is enabled by default. You must run phgrafx, and check Enable for a given device driver in order to enable multiple displays. You can also use phgrafx to configure the region settings and display mode for each display device.

In the following configuration file example, a Radeon and an ATI-rage128 video card are configured to enable your computer to output to dual displays: 

device {
     photon {
       driver {
          drivername=svga
          modeopts=
          }
          driver {
            drivername=ati_rage128
            modeopts=
          }
        driver {
            drivername=vesabios
            modeopts=
        }
     }
    drivername=ati_rage128
    modeopts=
    vid=0x1002
    did=0x5050
    deviceindex=0x0
    display {
        xres=640
        yres=480
        refresh=60
        pixel_format=argb1555
        photon {
            enabled=1
            xoffset=1024
            yoffset=0
            cursor=hardware
            input_group=1
        }
    }
}

device {
     photon {
        driver {
            drivername=svga
            modeopts=
        }
        driver {
            drivername=radeon
            modeopts=
        }
        driver {
            drivername=vesabios
            modeopts=
        }
    }
    drivername=radeon
    modeopts=
    vid=0x1002
    did=0x4966
    deviceindex=0x0
    display {
        xres=1024
        yres=768
        refresh=60
        pixel_format=argb8888
        photon {
            enabled=1
            xoffset=0
            yoffset=0
            cursor=hardware
            input_group=1
        }
    }
}

Configuring multiple displays using a single video device

You can also enable multiple displays using a single graphic card (assuming the graphic card supports multiple outputs). To enable multiple displays, you must manually create any additional display sections in the device configuration section of your configuration file. Remember to reboot your computer and restart Photon in order for the new changes to take effect.

The following example shows a configuration file for a Matroxg video card with dual displays enabled. 

device {
     photon {
       driver {
            drivername=svga
            modeopts=
        }
        driver {
            drivername=matroxg
            modeopts=
        }
        driver {
            drivername=vesabios
            modeopts=
        }
    }
    drivername=matroxg
    modeopts=
    vid=0x102b
    did=0x525
    deviceindex=0x0
    display {
        xres=1024
        yres=768
        refresh=60
        pixel_format=rgb565
        photon {
            enabled=1
            xoffset=0
            yoffset=0
            cursor=hardware
            input_group=1
        }
    }
    display {
        xres=640
        yres=480
        refresh=60
        pixel_format=rgb565
        photon {
            enabled=1
            xoffset=0
            yoffset=0
            cursor=hardware
            input_group=1
        }
    }

}
Note: By default, in an auto-generated configuration file, a graphic card with multiple outputs will output the same video signal to each display, since the default generated configuration file defines only a single display section.

You can modify the video settings of each display directly in the configuration file, or use phgrafx to configure each display.

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

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