uFramebuffer Interface for MicroWindows
Version 0.03 - Mar 3, 2000

Purpose

This document defines the Micro FrameBuffer ( uFB ) interface for MicroWindows GUI engine. It is meant to be a simplification of the Linux's framebuffer, and it is target to embedded systems where some of the complexities of the Linux version, such as termminal switching, are not necessary.

System Overview

Before we go any further, let's give a little overview of the architecture of MicroWindows running under an embedded kernel such as RTEMS. For a complete description of Microwindows & RTEMS, please visit their web sites for more documentation.





Logical Layers



Application Code

This layer contains application specific code. It should be very portable and totally un-ware of the drivers being used at the lower layers.

MicroWindows Engine

For a complete description of MicroWindows, please see documentation at this location.

MicroWindows has a good coverage of drivers for Display, Keyboard and Mouse.
These drivers use "kernel services", and one of the goals of this document is to standarise the API needed by these drivers in an embedded environment.

This document will cover the interface that embedded kernels must provide for drawing devices. Another document will cover the input devices such as mouse and keyboard. See Specification here.

uFB Driver Interface

Graphics Libraries

These links contains very good information about graphics libraries, and they could be used as resources to anyone needing information about a driver for a particular chipset etc.

A simplified version of the Linux FrameBuffer will be used as the base for our interface. It'll be called Micro FrameBuffer ( uFB ).

Audio Libraries

Currently there are no support for audio devices under MicroWindows. This topic needs to be addresed later.

Reusability of Linux/FreeBSD drivers

One thing to keep in mind is reusability of device drivers, specially video and audio, due to the diversity of cards around. Keeping the model of the drivers similar to the ones defined to Linux and/or FreeBSD, most of the devices available on these open platforms could be easily portable to RTEMS.

Micro FrameBuffer Interface for Embedded Systems

This section describes the API of the uFB inteface. Also, a reference implementation is provided to guide new implementations.

uFB - API Wrapper

After a small debate on the MicroWindows mail-list, it was decided to use the idea behind framebuffer. A "micro" version of the FB interface would be implemented to fit the requirements of embedded systems, i.e. a very simple interface based on ioctls calls.

All complexity of the framebuffer interface, such as virtual consoles, terminal switching, has been dropped at this initial stage.

In order to make easier its understanding, a simple API wrapper around the ioctls calls is provided. All functions returns zero( 0 ) on success. Below a brief description of the uFB function calls:



/* Micro Framebuffer API Wrapper */

/* 
 * This function returns the information regarding the display.
 * It is called just after the driver be opened to get all needed
 * information about the driver. No change in the mode of operation
 * of the driver is done with this call.
 */
extern int ufb_get_screen_info( int fd, struct fb_screeninfo *info );


/* 
 * Returns the mode of the graphics subsystem 
 */
extern int ufb_get_mode( int fd, int *mode );


/* 
 * Returns the current color palette 
 */
extern int ufb_get_palette( int fd, struct fb_cmap *color );



/* 
 * Set the current collor palette 
 */
extern int ufb_set_palette( int fd, struct fb_cmap *color );

/* 
 * Does all necessary initialization to put the device in 
 * graphics mode 
 */
extern int ufb_enter_graphics( int fd, int mode );



/* 
 * Switch the device back to the default mode of operation.
 * In most cases it put the device back to plain text mode.
 */
extern int ufb_exit_graphics( int fd );



/* 
 * Tell the driver that the "virtual buffer" is dirty, and an update 
 * of it to the real device, maybe a serial/parallel LCD or whatever 
 * is required 
 */
extern int ufb_buffer_is_dirty( int fd );



/* 
 * This function maps the physical ( kernel mode ) address of the 
 * framebuffer device and maps it to the user space address.
 *
 */
 int ufb_mmap_to_user_space( int fd, void **fb_addr, 
                             void *physical_addr, unsigned long size );



/* 
 * This function unmaps memory of the FB from the user's space
 */
 int ufb_unmmap_from_user_space( int fd, void *addr );


Source Code - Reference Implementation

This section provides a reference implmentation of the uFB that has been implemented for RTEMS.

Call Sequence

Here we present a sequence diagram for the initialization of the graphical subsystem.



Init - Sequence Diagram



Output Devices x Consoles

On embedded systems sometimes the console and the "output device", such as a LCD screen, are not the same thing. In most cases the console work as a debug port connected to a terminal. It'll be up to the kernel level driver to make such distinction and redirect the output from "printf/printk" to the appropriated console or show them over a "graphical" console.

Virtual FrameBuffer

Some devices might not have a real memory buffer, and some memory will be allocated to the passed to the application as its framebuffer. On these cases, MicroWindows will be responsible to notify the driver whenever the buffer is dirty and needs to be updated. How the driver actually implements this is really open and up to the driver.

Displays types

TBD --- Add notes specific to each display

Graphics Displays

Text Displays

Dot/Matrix Displays

LCDs

TODO

Contributors