`io-display`

Graphics framework graphics server

You must be root to start this manager.

Syntax:

io-display [-vf] [-d device] [-c config_file]

Options:

-d device

Load the graphics driver specified by the device. These options must match an entry in the io-display configuration file (see below).

The format of the device string is: vid=[0x]vendor_id,did=[0x]device_id[,deviceindex=index]

Where:

vendor_id: The vendor ID of the graphics device.
device_id: The device ID of the graphics device.
device_index: The index of the graphics device. If not specified, the default is 0.

For PCI devices, you can use the pci utility to display PCI information about installed graphics devices on a machine running Neutrino.

-v

Be verbose.

-f

Ignore requests to wait for vertical synchronization coming from the application. This is useful when measuring frame rates for benchmarking purposes.

-c

Specify a path to the configuration file. The default is /etc/system/config/display.conf. See below for the configuration file format.

Description:

The io-display manager provides support for direct rendering to graphics devices using the Graphics Framework and OpenGL-ES by loading the driver specified by the -d option.

Once io-display has started, applications can use the Graphics Framework library (libgf) and OpenGL ES libraries to acquire a graphics context and render to the device.

Graphics Framework applications must be privileged in order to run, since they directly access the graphics hardware when rendering. This means they either have to be run by root, or by a member of the "display" group. Applications that are a member of the "display" group can directly access the graphics hardware, without having supervisor (root) privileges.

There is one restriction however, which currently only applies to x86 systems. Some drivers for older video devices may need to perform accesses to I/O mapped registers when rendering. In this case, the thread performing the rendering will need to have I/O privity. In order to obtain I/O privity, the process must run as root. A process with I/O privity on an x86 system does not have full superuser privileges, however, so the extra requirement to run as root with some graphics devices introduces minimal risk.

The `io-display` configuration file

By default, the io-display configuration file is located in /etc/system/config/display.conf, but you can put it in a different location by using the -c option.

This file specifies global options, device-specific options, and display-specific options. The file follows these conventions:

one option per line
options are specified as name=value
the file layout is hierarchical, with each section containing zero or more options, and zero or more subsections
subsections are contained within curly braces.

The top-level section is device, which describes a graphics device. It has these options and sub-sections:

drivername -- a string describing the devg-* driver that io-display loads for this device. The string must match the name of the driver. For example, "radeon" matches devg-radeon.so.
vid -- the vendor ID, in hexadecimal. In the case of a PCI device, this is the PCI vendor ID.
did -- the device ID, in hexadecimal. In the case of a PCI device, this is the PCI device ID.
deviceindex -- the device index.
modeopts -- a string passed directly to the driver. For example, in the case of the Coral driver, it can specify a configuration file with additional hardware-specific settings.
display -- a sub-section that describes one or more displays supported by the device. This sub-section as the following options:
- xres -- the horizontal resolution of the display.
- yres -- the vertical resolution of the display.
- refresh -- the refresh rate of the display, in Hz.
- pixel_format -- The pixel format of the display. Possible pixel formats are:
  - pal8 -- 8 bpp
  - argb1555 -- 15 bpp
  - rgb565 -- 16 bpp
  - rgb888 -- 24 bpp
  - argb8888 -- 32 bpp

Here is an example file:

device {
        drivername=radeon
        vid=0x1002
        did=0x514c
        deviceindex=0
        display {
                xres=640
                yres=480
                refresh=60
                pixel_format=argb8888
        }
}
device {
        drivername=radeon
        vid=0x1002
        did=0x5961
        deviceindex=0
        display {
                xres=1280
                yres=1024
                refresh=75
                pixel_format=argb8888
        }
}

Examples:

Start io-display, and load and initialize the driver for the Fujitsu Coral PA chipset:

io-display -dvid=0x10cf,did=0x201e

This example assumes the contents of the config file are as follows:

device {
        drivername=coral
        vid=0x10cf
        did=0x201e
        deviceindex=0
        modeopts=/etc/system/config/coral.conf
        display {
                xres=640
                yres=480
                refresh=60
                bpp=15
        }
}

The driver devg-coral.so is loaded by io-display, and the initial display resolution would be 640x480x15 at 60Hz.

io-display