Subversion Repositories openrisc

    Overview

    Overview

    eCos Support for Framebuffer Devices

Framebuffer devices are the most common way for a computer system to

display graphical output to users. There are immense variations in the

implementations of such devices. CYGPKG_IO_FRAMEBUF

provides an abstraction layer for use by application code and other

packages. It defines an API for manipulating framebuffers, mapping

this API on to functionality provided by the appropriate device

driver. It also defines the interface which such device drivers should

implement. For simple hardware it provides default implementations of

much of this interface, greatly reducing the effort needed to write a

device driver.

This package does not constitute a graphics library. It does not

implement functionality like drawing text or arbitrary lines, let

alone any kind of windowing system. Instead it operates at the lower

level of individual pixels and blocks of pixels, in addition to

control operations such as hardware initialization. Some applications

may use the framebuffer API directly. Others will instead use a

higher-level graphics library, and it is that library which uses the

framebuffer API.

It is assumed that users are already familiar with the fundamentals of

computer graphics, and no attempt is made here to explain terms like

display depth, palette or pixel.

This package is work-in-progress. The support for 1bpp, 2bpp and 4bpp

display depths is incomplete. For double-buffered displays the code

does not yet maintain a bounding box of the updated parts of the

display. The package has also been designed to allow for

expansion with new

functionality.

CYGPKG_IO_FRAMEBUF only contains

hardware-independent code. It should be complemented by one or more

framebuffer device drivers appropriate for the target platform. These

drivers may be specific to the platform, or they may be more generic

with platform-specific details such as the framebuffer memory base

address provided by the platform HAL. When creating a configuration

for a given target the device driver(s) will always be included

automatically (assuming one has been written or ported). However by

default this driver will be inactive and will not get built, so does

not add any unnecessary size overhead for applications which do not

require graphics. To activate the device driver

CYGPKG_IO_FRAMEBUF must be added explicitly to the

configuration, for example using

ecosconfig add framebuf. After this the

full framebuffer API will be available to other packages and to

application code.

This package contains very few configuration options. Instead it is

left to device drivers or higher-level code to provide appropriate

configurability. One option,

CYGFUN_IO_FRAMEBUF_INSTALL_DEFAULT_PALETTE, relates

to the initialization of 

linkend="framebuf-colour-palette">paletted displays.

There are a number of calculated and inferred configuration options

and a number of interfaces. These provide information such as whether

or not there is a backlight. The most important one is

CYGDAT_IO_FRAMEBUF_DEVICES, which holds a list of

framebuffer identifiers for use with the 

linkend="framebuf-api">macro-based API. If there is a single

framebuffer device driver which supports one display in either

landscape or portrait mode, the configuration option may hold a value

like  240x320x8 320x240x8r90.

Framebuffer devices require a difficult choice between flexibility and

performance. On the one hand the API should be able to support

multiple devices driving separate displays, or a single device

operating in different modes at different times. On the other hand

graphics tends to involve very large amounts of I/O: even something as

simple as drawing a background image can involve setting many

thousands of pixels. Efficiency requires avoiding all possible

overheads including function calls. Instead the API should make

extensive use of macros or inline functions. Ideally details of the

framebuffer device such as the stride would be known constants at

compile-time, giving the compiler as much opportunity as possible to

optimize the code. Clearly this is difficult if multiple framebuffer

devices are in use or if the device mode may get changed at run-time.

To meet the conflicting requirements the generic framebuffer package

provides two APIs: a fast macro API which requires selecting a single

framebuffer device at compile or configure time; and a slower function

API without this limitation. The two are very similar, for example:

#include <cyg/io/framebuf.h>

void

clear_screen(cyg_fb* fb, cyg_fb_colour colour)

{

    cyg_fb_fill_block(fb, 0, 0,

                      fb->fb_width, fb->fb_height,

                      colour);

}

or the equivalent macro version:

#include <cyg/io/framebuf.h>

#define FRAMEBUF 240x320x8

void

clear_screen(cyg_fb_colour colour)

{

    CYG_FB_FILL_BLOCK(FRAMEBUF, 0, 0,

                      CYG_FB_WIDTH(FRAMEBUF), CYG_FB_HEIGHT(FRAMEBUF),

                      colour);

}

The function-based API works in terms of

cyg_fb structures, containing all the

information needed to manipulate the device. Each framebuffer device

driver will export one or more of these structures, for example

cyg_alaia_fb_240x320x8, and the driver

documentation should list the variable names. The macro API works in

terms of identifiers such as 240x320x8, and by a

series of substitutions the main macro gets expanded to the

appropriate device-specific code, usually inline. Again the device

driver documentation should list the supported identifiers. In

addition the configuration option

CYGDAT_IO_FRAMEBUF_DEVICES will contain the full

list. By convention the identifier will be specified by a

#define'd symbol such as

FRAMEBUF, or in the case of graphics libraries by a

configuration option.

If a platform has multiple framebuffer devices connected to different

displays then there will be separate cyg_fb

structures and macro identifiers for each one. In addition some

devices can operate in multiple modes. For example a PC VGA card can

operate in a monochome 640x480 mode, an 8bpp 320x200 mode, and many

other modes, but only one of these can be active at a time. The

different modes are also represented by different

cyg_fb structures and identifiers,

effectively treating the modes as separate devices. It is the

responsibility of higher-level code to ensure that only one mode is in

use at a time.

It is possible to use the macro API with more than one device,

basically by compiling the code twice with different values of

FRAMEBUF, taking appropriate care to avoid

identifier name clashes. This gives the higher performance of the

macros at the cost of increased code size.

All of the framebuffer API, including exports of the device-specific

cyg_fb structures, is available through a

single header file <cyg/io/framebuf.h>. The

API follows a number of conventions. Coordinates (0,0) correspond to

the top-left corner of the display. All functions and macros which

take a pair of coordinates have x first, y second. For block

operations these coordinates are followed by width, then height.

Coordinates and dimensions use cyg_ucount16 variables,

which for any processor should be the most efficient unsigned data

type with at least 16 bits - usually plain unsigned integers. Colours

are identified by cyg_fb_colour variables, again usually

unsigned integers.

To allow for the different variants of the English language, the API

allows for a number of alternate spellings. Colour and color can be

used interchangeably, so there are data types

cyg_fb_colour and cyg_fb_color, and

functions cyg_fb_make_colour and

cyg_fb_make_color. Similarly gray is accepted as

a variant of grey so the predefined colours

CYG_FB_DEFAULT_PALETTE_LIGHTGREY and

CYG_FB_DEFAULT_PALETTE_LIGHTGRAY are equivalent.

The API is split into the following categories:

        parameters

getting information about a given framebuffer device such as width,

height and depth. Colours management is complicated so has its own

category.

        control

operations such as switching the display on and off, and more

device-specific ones such as manipulating the backlight.

        colours

determining the colour format (monochrome, paletted, &hellip),

manipulating the palette, or constructing true colours.

        drawing

primitives for manipulating pixels and blocks of pixels.

        iteration

efficiently iterating over blocks of pixels.

The framebuffer API never performs any locking so is not thread-safe.

Instead it assumes that higher-level code such as a graphics library

performs any locking that may be needed. Adding a mutex lock and

unlock around every drawing primitive, including pixel writes, would

be prohibitively expensive.

It is also assumed that the framebuffer will only be updated from

thread context. With most hardware it will also be possible to access

a framebuffer from DSR or ISR context, but this should be avoided in

portable code.

    Framebuffer Parameters

    Parameters

    determining framebuffer capabilities

#include <cyg/io/framebuf.h>

typedef struct cyg_fb {

    cyg_ucount16    fb_depth;

    cyg_ucount16    fb_format;

    cyg_ucount16    fb_width;

    cyg_ucount16    fb_height;

#ifdef CYGHWR_IO_FRAMEBUF_FUNCTIONALITY_VIEWPORT

    cyg_ucount16    fb_viewport_width;

    cyg_ucount16    fb_viewport_height;

#endif

    void*           fb_base;

    cyg_ucount16    fb_stride;

    cyg_uint32      fb_flags0;

    …

} cyg_fb;

        cyg_fb* CYG_FB_STRUCT

        FRAMEBUF

        cyg_ucount16 CYG_FB_DEPTH

        FRAMEBUF

        cyg_ucount16 CYG_FB_FORMAT

        FRAMEBUF

        cyg_ucount16 CYG_FB_WIDTH

        FRAMEBUF

        cyg_ucount16 CYG_FB_HEIGHT

        FRAMEBUF

        cyg_ucount16 CYG_FB_VIEWPORT_WIDTH

        FRAMEBUF

        cyg_ucount16 CYG_FB_VIEWPORT_HEIGHT

        FRAMEBUF

        void* CYG_FB_BASE

        FRAMEBUF

        cyg_ucount16 CYG_FB_STRIDE

        FRAMEBUF

        cyg_uint32 CYG_FB_FLAGS0

        FRAMEBUF

When developing an application for a specific platform the various

framebuffer parameters such as width and height are known, and the

code can be written accordingly. However when writing code that should

work on many platforms with different framebuffer devices, for example

a graphics library, the code must be able to get these parameters and

adapt.

Code using the function API can extract the parameters from the

cyg_fb structures at run-time. The macro API

provides dedicated macros for each parameter. These do not follow the

usual eCos convention where the result is provided via an extra

argument. Instead the result is returned as normal, and is guaranteed

to be a compile-time constant. This allows code like the following:

#if CYG_FB_DEPTH(FRAMEBUF) < 8

    …

#else

    …

#endif

or alternatively:

    if (CYG_FB_DEPTH(FRAMEBUF) < 8) {

        …

    } else {

        …

    }

or:

    switch (CYG_FB_DEPTH(FRAMEBUF)) {

        case  1 : … break;

        case  2 : … break;

        case  4 : … break;

        case  8 : … break;

        case 16 : … break;

        case 32 : … break;

    }

In terms of the code actually generated by the compiler these

approaches have much the same effect. The macros expand to a

compile-time constant so unnecessary code can be easily eliminated.

The available parameters are as follows:

        depth

The number of bits per pixel or bpp. The common depths are 1, 2, 4, 8,

16 and 32.

        format

How the pixel values are mapped on to visible 

linkend="framebuf-colour">colours, for example true colour

or paletted or greyscale.

        width

        height

The number of framebuffer pixels horizontally and vertically.

        viewport width

        viewport height

With some devices the framebuffer height and/or width are greater than

what the display can actually show. The display is said to offer a

viewport into the larger framebuffer. The number of visible pixels is

determined from the viewport width and height. The position of the

viewport is controlled via an 

linkend="framebuf-control-ioctl-viewport">ioctl.

Within a cyg_fb structure these fields are

only present if

CYGHWR_IO_FRAMEBUF_FUNCTIONALITY_VIEWPORT

is defined, to avoid wasting data space on fields that are unnecessary

for the current platform. For the macro API the viewport macros should only be used

if CYG_FB_FLAGS0_VIEWPORT is set for the framebuffer:

#if (CYG_FB_FLAGS0(FRAMEBUF) & CYG_FB_FLAGS0_VIEWPORT)

    …

#endif

        base

        stride

For linear

framebuffers these parameters provide the information needed to access

framebuffer memory. The stride is in bytes.

        flags0

This gives further information about the hardware capabilities.

Some of this overlaps with other parameters, especially when it comes

to colour, because it is often easier to test for a single flag than

for a range of colour modes. The current flags are:

            CYG_FB_FLAGS0_LINEAR_FRAMEBUFFER

Framebuffer memory is organized in a conventional fashion and can be

accessed directly by

higher-level code using the base and stride parameters.

            CYG_FB_FLAGS0_LE

This flag is only relevant for 1bpp, 2bpp and 4bpp devices and

controls how the pixels are organized within each byte. If the flag is

set then the layout is little-endian: for a 1bpp device pixel (0,0)

occupies bit 0 of the first byte of framebuffer memory. The more

common layout is big-endian where pixel (0,0) occupies bit 7 of the

first byte.

            CYG_FB_FLAGS0_TRUE_COLOUR

The framebuffer uses a true colour format where the value of each

pixel directly encodes the red, green and blue intensities. This is

common for 16bpp and 32bpp devices, and is occasionally used for 8bpp

devices.

            CYG_FB_FLAGS0_PALETTE

The framebuffer uses a palette. A pixel value does not directly encode

the colours, but instead acts as an index into a separate table of

colour values. That table may be read-only or read-write. Paletted

displays are common for 8bpp and some 4bpp displays.

            CYG_FB_FLAGS0_WRITEABLE_PALETTE

The palette is read-write.

            CYG_FB_FLAGS0_DELAYED_PALETTE_UPDATE

Palette updates can be synchronized to a vertical blank, in other

words a brief time period when the display is not being updated,

by using CYG_FB_UPDATE_VERTICAL_RETRACE as the last

argument to cyg_fb_write_palette or

CYG_FB_WRITE_PALETTE. With some hardware updating

the palette in the middle of a screen update may result in visual noise.

            CYG_FB_FLAGS0_VIEWPORT

The framebuffer contains more pixels than can be shown on the display.

Instead the display provides a viewport into the framebuffer. An

ioctl

can be used to move the viewport.

            CYG_FB_FLAGS0_DOUBLE_BUFFER

The display does not show the current contents of the framebuffer, so

the results of drawing into the framebuffer are not immediately

visible. Instead higher-level code needs to perform an explicit

synch operation to

update the display.

            CYG_FB_FLAGS0_PAGE_FLIPPING

The hardware supports two or more pages, each of width*height pixels,

only one of which is visible on the display. This allows higher-level

code to update one page without disturbing what is currently visible.

An 

linkend="framebuf-control-ioctl-pageflip">ioctl

is used to switch the visible page.

            CYG_FB_FLAGS0_BLANK

The display can be blanked

without affecting the framebuffer contents or settings.

            CYG_FB_FLAGS0_BACKLIGHT

There is a backlight which can be 

linkend="framebuf-control-ioctl-backlight">switched

on or off. Some hardware provides finer-grained control over the

backlight intensity.

            CYG_FB_FLAGS0_MUST_BE_ON

Often it is desirable to perform some initialization such as clearing

the screen or setting the palette before the display is 

linkend="framebuf-control-onoff">switched on, to avoid visual

noise. However not all hardware allows this. If this flag is set then

it is possible to access framebuffer memory and the palette before the

cyg_fb_on or CYG_FB_ON

operation. It may also be possible to perform some other operations

such as activating the backlight, but that is implementation-defined.

To allow for future expansion there are also flags1, flags2, and

flags3 fields. These may get used for encoding additional

ioctl functionality, support for hardware

acceleration, and similar features.

There are drawing primitives for writing and reading individual

pixels. However these involve a certain amount of arithmetic each time

to get from a position to an address within the frame buffer, plus

function call overhead if the function API is used, and this will slow

down graphics operations.

When the framebuffer device is known at compile-time and the macro API

is used then there are additional macros specifically for 

linkend="framebuf-iterating">iterating over parts of the frame

buffer. These should prove very efficient for many graphics

operations. However if the device is selected at run-time then the

macros are not appropriate and code may want to manipulate framebuffer

memory directly. This is possible if two conditions are satisfied:

The CYG_FB_FLAGS0_LINEAR_FRAMEBUFFER flag must be

set. Otherwise framebuffer memory is either not directly accessible or

has a non-linear layout.

The CYG_FB_FLAGS0_DOUBLE_BUFFER flag must be clear.

An efficient double buffer synch operation requires knowing what part

of the framebuffer have been updated, and the various drawing

primitives will keep track of this. If higher-level code then starts

manipulating the framebuffer directly the synch operation may perform

only a partial update.

The base, stride, depth, width and height parameters, plus the

CYG_FB_FLAGS0_LE flag for 1bpp, 2bpp and 4bpp

devices, provide all the information needed to access framebuffer

memory. A linear framebuffer has pixel (0,0) at the base address.

Incrementing y means adding stride bytes to the pointer.

The base and stride parameters may be set even if

CYG_FB_FLAGS0_LINEAR_FRAMEBUFFER is clear. This can

be useful if for example the display is rotated in software from

landscape to portrait mode. However the meaning of these parameters

for non-linear framebuffers is implementation-defined.

    Framebuffer Control Operations

    Control Operations

    managing a framebuffer

#include <cyg/io/framebuf.h>

        int cyg_fb_on

        cyg_fb* fbdev

        int cyg_fb_off

        cyg_fb* fbdev

        int cyg_fb_ioctl

        cyg_fb* fbdev

        cyg_uint16 key

        void* data

        size_t* len

        int CYG_FB_ON

        FRAMEBUF

        int CYG_FB_OFF

        FRAMEBUF

        int CYG_FB_IOCTL

        FRAMEBUF

        cyg_uint16 key

        void* data

        size_t* len

The main operations on a framebuffer are drawing and colour

management. However on most hardware it is also necessary to switch

the display on before the

user can see anything, and application code should be able to control

when this happens. There are also miscellaneous operations such as

manipulating the backlight or moving the viewpoint. These do not

warrant dedicated functions, especially since the functionality will

only be available on some hardware, so an 

linkend="framebuf-control-ioctl">ioctl

interface is used.

With most hardware nothing will be visible until there is a call to

cyg_fb_on or an invocation of the

CYG_FB_ON macro. This will initialize the

framebuffer control circuitry, start sending the data signals to the

display unit, and switch on the display if necessary. The exact

initialization semantics are left to the framebuffer device driver. In

some cases the hardware may already be partially or fully initialized

by a static constructor or by boot code that ran before eCos.

There are some circumstances in which initialization can fail, and

this is indicated by a POSIX error code such as

ENODEV. An example would be plug and play hardware

where the framebuffer device is not detected at run-time. Another

example is hardware which can operate in several modes, with separate

cyg_fb structures for each mode, if the

hardware is already in use for a different mode. A return value of 0

indicates success.

Some but not all hardware allows the framebuffer memory and, if

present, the palette to be manipulated before the device is switched

on. That way the user does not see random noise on the screen during

system startup. The flag CYG_FB_FLAGS0_MUST_BE_ON

should be checked:

static void

init_screen(cyg_fb_colour background)

{

    int result;

#if (! (CYG_FB_FLAGS0(FRAMEBUF) & CYG_FB_FLAGS0_MUST_BE_ON))

    CYG_FB_FILL_BLOCK(FRAMEBUF, 0, 0,

                      CYG_FB_WIDTH(FRAMEBUF), CYG_FB_HEIGHT(FRAMEBUF),

                      background);

#endif

    result = CYG_FB_ON(FRAMEBUF);

    if (0 != result) {

        <handle unusual error condition>

    }

#if (CYG_FB_FLAGS0(FRAMEBUF) & CYG_FB_FLAGS0_MUST_BE_ON)

    CYG_FB_FILL_BLOCK(FRAMEBUF, 0, 0,

                      CYG_FB_WIDTH(FRAMEBUF), CYG_FB_HEIGHT(FRAMEBUF),

                      background);

#endif

}

Obviously if the application has already manipulated framebuffer

memory or the palette but then the cyg_fb_on

operation fails, the system is left in an undefined state.

It is also possible to switch a framebuffer device off, using the

function cyg_fb_off or the macro

CYG_FB_OFF, although this functionality is rarely

used in embedded systems. The exact semantics of switching a device

off are implementation-defined, but typically it involves shutting

down the display, stopping the data signals to the display, and

halting the control circuitry. The framebuffer memory and the palette

are left in an undefined state, and application code should assume

that both need full reinitializing when the device is switched back

on. Some hardware may also provide a 

linkend="framebuf-control-ioctl-blank">blank operation which

typically just manipulates the display, not the whole framebuffer

device. Normally cyg_fb_on returns 0. The API

allows for a POSIX error code as with cyg_fb_on,

but switching a device off is not an operation that is likely to fail.

If a framebuffer device can operate in several modes, represented by

several cyg_fb structures and macro

identifiers, then switching modes requires turning the current device

off before turning the next one one.

Some hardware functionality such as an LCD panel backlight is common

but not universal. Supporting these does not warrant dedicated

functions. Instead a catch-all ioctl interface is

provided, with the arguments just passed straight to the device

driver. This approach also allows for future expansion and for

device-specific operations. cyg_fb_ioctl and

CYG_FB_IOCTL take four arguments: a

cyg_fb structure or framebuffer identifier; a

key that specifies the operation to be performed; an arbitrary

pointer, which should usually be a pointer to a data structure

specific to the key; and a length field. Key values from 0 to 0x7fff

are generic. Key values from 0x8000 onwards are reserved for the

individual framebuffer device drivers, for device-specific

functionality. The length field should be set to the size of the data

structure, and may get updated by the device driver.

With most ioctl operations the device can indicate whether or not it

supports the functionality by one of the flags, for example:

void

backlight_off(cyg_fb* fb)

{

    if (fb->fb_flags0 & CYG_FB_FLAGS0_BACKLIGHT) {

        cyg_fb_ioctl_backlight  new_setting;

        size_t                  len = sizeof(cyg_fb_ioctl_backlight);

        int                     result;

        new_setting.fbbl_current = 0;

        result = cyg_fb_ioctl(fb, CYG_FB_IOCTL_BACKLIGHT_SET,

                              &new_setting, &len);

        if (0 != result) {

            …

        }

    }

}

The operation returns zero for success or a POSIX error code on

failure, for example ENOSYS if the device driver

does not implement the requested functionality.

# define CYG_FB_IOCTL_VIEWPORT_GET_POSITION     0x0100

# define CYG_FB_IOCTL_VIEWPORT_SET_POSITION     0x0101

typedef struct cyg_fb_ioctl_viewport {

    cyg_ucount16    fbvp_x;     // position of top-left corner of the viewport within

    cyg_ucount16    fbvp_y;     // the framebuffer

    cyg_ucount16    fbvp_when;  // set-only, now or vert retrace

} cyg_fb_ioctl_viewport;

On some targets the framebuffer device has a higher resolution than

the display. Only a subset of the pixels, the viewport, is currently

visible. Application code can exploit this functionality to achieve

certain effects, for example smooth scrolling. Framebuffers which

support this functionality will have the