Distribution Guide Device drivers Graphics/video drivers

Graphics/video drivers

The ST Linux 2.0 distribution provides drivers and standard applications that enable the use of graphics and video display capabilities for a number of STMicroelectronics' SoCs. Framebuffer and V4L2 output drivers are available for the STi5528, STm8000 and STb7100.

The following sections provide documentation on the various components:

• Framebuffer driver,

• Using fbset,

• Virtual terminal drivers,

• V4L2 output driver.

Framebuffer driver

The framebuffer driver supports mode change, vertical panning and virtual terminals. Additionally it supports the use of the framebuffer based X11 server and DirectFB. The driver presents a memory-mapped truecolor graphics framebuffer which supports 16-, 24- and 32-bit color depths.

Kernel prerequisites

The framebuffer driver consists of a number of kernel modules. Before these can be used the kernel must have been built with the option CONFIG_FB set. Bring up the Linux Kernel Configuration screen (as described in Kernel configuration) and enter:

Device Drivers ---> Graphics Support ---> Support for framebuffer drivers

As the ST graphics devices use system memory for display buffers, in order to allocate the required large contiguous memory regions required it is necessary to set CONFIG_BIGPHYS_AREA. This can be done in the kernel configuration in:

System type---> Big Physical Area

When booting the kernel, a kernel command line option is required to reserve a number of (4 Kbyte) memory pages for bigphysarea; for example bigphysarea=4000 reserves 16 Mbytes.

To control the SCART A/V switch present on platforms such as the Espresso, the I²C subsystem and ST40 I²C bit banging driver must be configured into the kernel. This is described in Configuring the kernel.

In addition the "Virtual terminal" (CONFIG_VT) option may be selected:

Device Drivers ---> Character Devices ---> Virtual Terminal

If this is done, it is necessary to turn off the "VGA text console" option (CONFIG_VGA_CONSOLE):

Device Drivers ---> Graphics Support ---> VGA text console

and turn on the "Framebuffer console support" option (CONFIG_FRAMEBUFFER_CONSOLE).

Device Drivers ---> Graphics Support ---> Framebuffer console support

Building the kernel modules

The kernel modules are supplied in source code to allow them to be built against the kernel which is being used on the target system. To build them, simply copy the source files into a local directory, and invoke the Makefile, specifying the location of the built kernel tree. For example:

host% cp -a /opt/STM/STLinux-2.0/devkit/kernel/stgfb-0.1_20060405 .
host% cd stgfb-0.1_20060405/Linux
host% make KERNELDIR=<path to kernel>

If the directory in which object files should be placed (by the kernel build process) has been specified (using the make option O=<directory>), then the same option must be specified when building the graphics modules.

When building for the STb7100 it is necessary to specify which display pipeline is to be used. By default the auxiliary (standard definition) pipeline will be used; to build for the main HD pipeline, add CONFIG_STG_HD=y to the make line above.

To install the modules (into the root file system<path to target fs>), execute the following as root:

host# make KERNELDIR=<path to kernel> \
            INSTALL_MOD_PATH=<path to targer fs> \
            INSTALL_MOD_DIR=stgfb \
            modules_install

Inserting the kernel modules

Four modules, cfbcopyarea, cfbfillrect, cfbimgblt and stmfb-<socname>, are required to start the framebuffer. These are found in: /lib/modules/<kernel_version_string>/extras in the target file system. For example, to install them for version 2.6.11 on the STm8000, use the commands:

target# cd /lib/modules/2.6.11/extras
target# insmod cfbcopyarea.ko
target# insmod cfbfillrect.ko
target# insmod cfbimgblt.ko
target# insmod stmfb-stm8000.ko

The cfb*.ko modules are generic software implementations of console drawing operations that are currently not accelerated by the driver. The order in which these are installed is not important, but they must be installed before the stmfb-<socname>.ko driver module. However, as all of the modules are built with the correct dependencies, it is also possible to use the standard depmod and modprobe commands to load all of the modules at once.

Default display mode

When the framebuffer modules are installed a default display mode will be started. If no module parameters are specified the defaults are 720 x 576 @ 50 Hz interlaced, color standard PAL BDGHI, and a 16-bit RGB565 framebuffer format. If insufficient memory is available for the default display mode (specified via the bigphysarea interface) the load of the framebuffer driver will fail. This default mode can be altered using the module parameters shown in Table 1: Module parameters.

For example, to start the STm8000 with a default NTSC, 32-bit framebuffer with extra memory for panning/double buffering use:

target# insmod stmfb-stm8000.ko tvstandard=N bitdepth=32 fbsize=300000

The default NTSC mode timing is 720 x 480 @ 59.94 Hz interlaced. The S option selects 720 x 576 @ 50 Hz interlaced with the SECAM color standard. The H option selects 720p (1280 x 720 @ 60 Hz progressive); however this high definition mode is only available on the STb7100 when built with CONFIG_STG_HD=y.

If the fbsize parameter is not specified then the driver attempts to allocate the minimum amount of memory required for the default mode. If the fbsize parameter is given but the default mode requires more memory than the amount specified, the size is increased to satisfy the default mode.

Using fbset

The ST Linux distribution provides a standard application fbset which enables the framebuffer configuration to be interrogated and dynamic changes to be made after the framebuffer driver has been loaded. For example, to view the current display parameters use:

target# fbset -s
 
mode "720x576-50"
   # D: 13.500 MHz, H: 15.625 kHz, V: 50.000 Hz
   geometry 720 576 720 2083 16
   timings 74074 80 0 43 0 64 6
   laced true
   rgba 5/11,6/5,5/0,0/0
endmode

fbset can change the display mode, virtual vertical dimension, and color format. The full list of options for the version of fbset installed can be viewed using:

target# fbset --help

When the kernel does not have virtual terminal support enabled, fbset effectively controls the physical display. However, when virtual terminals are enabled, fbset controls the mode associated with the currently active virtual terminal. For more information, see Virtual terminal drivers.

Color formats

The color depth of the framebuffer can be changed using the -depth option, for example:

target# fbset -depth 32

This picks a default pixel format for the color depth. The actual pixel format can be specified as well, for example:

target# fbset -depth 16 -rgba 5,5,5,1

This selects format ARGB1555, instead of the default 16-bit format RGB565. The formats supported are given in Table 2: Supported color formats

Note: Two modes that are commonly available on other devices, the 16-bit mode RGBx555 and the 32-bit mode RGB888 (top byte unused), are not supported on ST SoCs.

Changing the color depth changes the amount of graphics memory required by the driver. If the new format cannot fit into the memory allocated when the driver module was loaded, then fbset returns an error. On STMicroelectronics' devices, changing the color depth of the framebuffer can be done without stopping and resetting the display system.

Changing display mode

fbset can also be used to change the display mode timings. This can be done using the individual options for size and pixel clock, or there is a more convenient method using the predefined modes listed in /etc/fb.modes. For example:

target# fbset 720x480-59i

selects the 720 x 480 @ 59.94 Hz interlaced mode. Note that the modes listed in /etc/fb.modes select the default 16-bit color format, however additional options can be given, for example:

target# fbset 720x576-50i -depth 32

fbset fails if there is insufficient framebuffer memory (as specified when the module is loaded) for the new configuration, and if the mode is unsupported (not all display modes are available on all platforms).

The framebuffer driver will refuse to change the display mode if another API, such as V4L2, has an active display surface (plane) visible on the display. On STMicroelectronics' devices there may be more than one API controlling different planes. These are combined to produce the final image seen on the screen. The framebuffer driver uses a single plane for the actual framebuffer surface.

The framebuffer driver determines the display timings to use from the X and Y resolution, the pixelclock and the "laced" (interlaced) flag. The margins and the horizontal and vertical synchronization parameters are not used in the timing, and the display positioning controls are not supported in this driver.

Broadcast color standards

The broadcast standard (PAL, NTSC or SECAM) is selected when the framebuffer driver is installed. The framebuffer API has no control over this, so the broadcast standard cannot be selected by programming. This can be a problem as the standards do not have unique timing modes. So when the display mode is changed the framebuffer driver switches the standard as defined in Table 4: Broadcast standard selection, based on the broadcast standard of the default mode.

Note: The PAL-N standard is not currently supported.