Synthetic Target Framebuffer Device

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.