eCos Reference Manual
Prev |  | Next

# Synthetic Target Framebuffer Device

## Name

Synthetic Target Framebuffer Device -- Emulate framebuffer hardware in the synthetic target

## Overview

This package `CYGPKG_DEVS_FRAMEBUF_SYNTH` provides a framebuffer device driver for the eCos synthetic target.

The driver supports up to four framebuffer devices `fb0`, `fb1`, `fb2` and `fb3`. The width, height, depth, and display format of each framebuffer can be controlled via configuration options. It is also possible to set a viewport for each device and to enable page flipping.

To use the framebuffer support the eCos application must run inside an X session, not from the console, and it must be started with `--io` to enable the I/O auxiliary. The I/O auxiliary will start a separate instance of a host-side utility framebuf for each target-side framebuffer device. The framebuf utility can access the eCos framebuffer data via a shared memory region and draw it to the screen using X library calls. It needs the X server to run with a TrueColor visual and a display of depth of 24 or 32 bits per pixel.

## Installation

The synthetic target framebuffer driver depends on host-side support which must be built and installed. The relevant code resides in the `host` subdirectory of the synthetic target framebuffer package, and building it involves the standard configure, make and make install steps. This will build and install a utility program framebuf that does the actual drawing of the eCos framebuffer contents to the host-side X display. It will also install a Tcl script and some support files. framebuf is an X11 application so can only be built on Linux systems with the appropriate X11 development package or packages.

There are two main ways of building the host-side software. It is possible to build both the generic host-side software and all package-specific host-side software, including the framebuffer support, in a single build tree. This involves using the configure script at the toplevel of the eCos repository. For more information on this, see the `README.host` file at the top of the repository. Note that if you have an existing build tree which does not include the synthetic target framebuffer support then it will be necessary to rerun the toplevel configure script: the search for appropriate packages happens at configure time.

The alternative is to build just the host-side for this package. This requires a separate build directory, building directly in the source tree is disallowed. The configure options are much the same as for a build from the toplevel, and the `README.host` file can be consulted for more details. It is essential that the framebuffer support be configured with the same `--prefix` option as other eCos host-side software, especially the I/O auxiliary provided by the architectural synthetic target HAL package, otherwise the I/O auxiliary will be unable to locate the framebuffer support.

## Configuration

The package is loaded automatically when creating a configuration for the synthetic target. However it is inactive unless the generic framebuffer support `CYGPKG_IO_FRAMEBUF` is also added to the configuration, for example by `ecosconfig add framebuf`.

By default the package enables a single framebuffer device `fb0` with a corresponding `cyg_fb` data structure `cyg_synth_fb0`. The default settings for this device are 320 by 240 pixels, a depth of 8 bits per pixel, a paletted display, no viewport support, and no page flipping. All of these settings can be changed by configuration options inside the CDL component `CYGPKG_DEVS_FRAMEBUF_SYNTH_FB0`. The supported display formats are: 8 bpp paletted; 8bpp true colour 332; 16bpp true 565; 16bpp true 555; and 32bpp 0888. This allows the synthetic target to match the actual display capabilities of the hardware that is being emulated. If the actual hardware has more than one framebuffer device then this can be emulated by enabling additional components `CYGPKG_DEVS_FRAMEBUF_SYNTH_FB1` …, and setting the appropriate options.

## Customization

In addition to the target-side configurability it is possible to customize the host-side behaviour. For example, the default behaviour is for `fb0` to be drawn inside the I/O auxiliary's main window, if it is not too large. `fb1`, `fb2` and `fb3` will be drawn inside separate toplevel windows, as will `fb0` if that has been configured too large for embedding in the main window. This behaviour can be changed by providing a custom Tcl/Tk procedure that creates the containing frame for the framebuffer device.

Customization involves adding a `synth_device` `framebuf` section to the `.tdf` target definition file, usually `default.tdf` or `~/.ecos/synth/default.tdf`.

    proc my_framebuf_create_frame { … } {
        …
    }

    synth_device framebuf {
        fb2_magnification   2
        create_frame_proc   my_framebuf_create_frame
    }

The pixel size on the host display may be rather smaller than on the final hardware, causing a serious mismatch between the application's appearance when using synthetic target emulation and when using real hardware. To reduce this problem the host-side can magnify the target-side framebuffer devices. In the example above each target-side pixel in device `fb2` will be drawn using 2*2 pixels on the host side. Valid magnifications are 1, 2, 3 and 4. With a magnification of 4 an eCos framebuffer device of 320*240 pixels will be drawn in an X window of 1280*960 pixels.

The `create_frame_proc` entry can be used to specify a custom Tcl/Tk procedure that will create the containing Tk frames for the host-side displays. This procedure can be written for a specific configuration, but it is supplied with all the parameters associated with the framebuffer device so can be more generic. An example is supplied in the package's `misc` subdirectory:

1. Create a configuration for the synthetic target with the default template.

2. Import the `example.ecm` configuration fragment from the `misc` subdirectory. This will add the generic framebuffer support package, enable all four framebuffer devices, and configure each device. Build the resulting configuration.

3. Compile the `example.c` program and link it against the eCos configuration.

4. Incorporate the `example.tdf` fragment into the appropriate target definition file, typically `default.tdf` or `~/.ecos/synth/default.tdf`.

5. Run the example executable. The four framebuffer devices should get instantiated in a separate window in a single column. `FB0` just contains a static display. `FB1` supports two pages, one with vertical stripes and one with horizontal stripes, and the two pages are flipped at regular intervals. `FB2` has a static display similar to `FB0`, but is drawn in a viewport of only 160x120 pixels. However `example.tdf` magnifies this by 2 so it appears the same size as the other devices. The application moves the viewport around the underlying framebuffer device. `FB3` is also a static display, a simple set of vertical stripes. However this framebuffer is paletted and the palette is changed at regular intervals, causing apparent movement.

Prev | Home | Next
Synthetic Target Framebuffer Device | Up | AMD AM29xxxxx Flash Device Driver