Detailed Description

Display device driver stack library.

Display Device Driver Stack

The source files for the DISPLAY device driver stack library resides in the kits/common/drivers directory and follows the naming convention: display<device>.c/h.

• Introduction
• Getting Started
• DISPLAY Device Driver Programming
• DISPLAY Device Driver Stack Configuration

Introduction

The DISPLAY device driver stack implements a common API for different types of display devices. Thus making it easy to port applications between different hardware and software platforms. Additionally the DISPLAY device driver stack implements a Platform Abstraction Layer (PAL) in order to provide abstractions of hardware and software services needed by the specific display device drivers. Thus making it easy to port the DISPLAY device driver stack itself between different platforms.

The stack provides a configuration interface via dedicated configuration files in order to suit various application and platform requirements. Please refer to DISPLAY Device Driver Stack Configuration for more information.

There are also several example programs in order to get you started fast.

We recommend that you read through this documentation, and then proceed to build and test a few example programs in order to get started.

Getting Started

This section contains brief descriptions of some of the functions in the API. You will find detailed information on input and output parameters and return values by clicking on the hyperlinked function names. It may also be a good idea to study the code in the example programs.

Your application code must include one header file, display.h , which defines the user interface of the DISPLAY module which is common for all display devices.

The first step an application should do is to call the DISPLAY_Init() function which initializes the DISPLAY driver stack. This includes calling the initialization functions of all registered display device drivers which will initialize the specific display device(s) and make them readily available through the DISPLAY interface defined in display.h .

It is good practice that the user programmer checks the return value of the DISPLAY_Init() call, and for the sake of it, all calls in of the DISPLAY device driver interface. All functions in the DISPLAY device driver interface return an EMSTATUS code which indicates whether the operation was successful or not, and what type of error may have occurred. The possible error codes are listed in display.h .

The second step is typically to retrieve the properties of a DISPLAY device. This can be done by calling the DISPLAY_DeviceGet() function which receives the following two parameters:

• displayDeviceNo which is a unique device number of one of the existing display devices in the system. This value is typically zero for single display systems.
• displayDevice which is a pointer to a DISPLAY_Device_t structure which will be populated with the properties of the specified display device if the function is successful.

If DISPLAY_DeviceGet() is successful, the specified DISPLAY_Device_t structure contains display device properties. The properties include the geometry ( DISPLAY_Geometry_t ), the colour mode ( DISPLAY_ColourMode_t ) and the address mode ( DISPLAY_AddressMode_t ) of the display device. Additionally the DISPLAY_Device_t structure contains function pointers to the device specific functions of the display device. The user should be aware that the device driver need not support all the function pointers of the DISPLAY_Device_t structure. Therefore the user should check if the function pointer is NULL before calling it.

The pPixelMatrixDraw() function is used to move and show the contents of a framebuffer (or pixel matrix buffer) onto the display device. A pixel matrix buffer is a 'partial' framebuffer which covers only part, or the whole, of the geometry of the display.

The format of the pixel data in the pixel matrix buffer is defined by the DISPLAY_ColourMode_t . At the time of writing only three colour modi are defined in DISPLAY_ColourMode_t :

• DISPLAY_COLOUR_MODE_MONOCHROME and
• DISPLAY_COLOUR_MODE_MONOCHROME_INVERSE
• DISPLAY_COLOUR_MODE_RGB_3BIT

The DISPLAY_COLOUR_MODE_MONOCHROME mode defines a pixel bit value of 0 as white, and a pixel bit value of 1 as black. The DISPLAY_COLOUR_MODE_MONOCHROME_INVERSE mode is the opposite, and thus defines a pixel bit value of 0 as black, and a pixel bit value of 1 as white. The DISPLAY_COLOUR_MODE_RGB_3BIT has 3 bits per pixel that individually turns on the red green and blue part of the pixel. 0b001 = red, 0b010 = blue, 0b100 = green. 0x111 = white, 0x000 = black.

The pixel matrix buffer format for the monochrome modi is defined as a byte array where

• bit 0 of the 0th byte is pixel 0 on line 0, top left on the display,
• bit 1 of the 0th byte is pixel 1 on line 0,
• ...,
• bit 7 of the 15th byte is pixel 127 on line 0,
• bit 0 of the 16th byte is pixel 0 on line 1,
• ...,
• bit 7 of the 2047th byte is pixel 127 on line 127, bottom right on the display.

The pixel matrix buffer format for the RGB 3bit mode is defined as a byte array where

• bits 2:0 of the 0th byte is pixel 0 on line 0, top left on the display,
• bits 5:3 of the 0th byte is pixel 1 on line 0,
• bits 7:6 of the 0th byte and bit 0 of the 1st byte is pixel 2 on line 0,
• ...,
• bits 7:5 of the 47th byte is pixel 127 on line 0,
• bits 2:0 of the 48th byte is pixel 0 on line 1,
• ...,
• bits 7:5 of the 6043rd byte is pixel 127 on line 127, bottom right on the display.

Some device drivers may need/want to support a pixelMatrix allocation function, pointed to by pPixelMatrixAllocate , in order to handle device specific data structures related to the pixel matrix buffers. The pixel matrix buffers allocated with the pPixelMatrixAllocate function may also include control data/padding in order to accomodate for efficient use of the underlying hardware. If the stride member of DISPLAY_Geometry_t structure is bigger than the width member, the pixel matrix buffer contains such control data, and should not be overwritten by the user, unless the user knows how to handle this data (which is usually not necessary).

The user can make use of graphic libraries such as EMWIN and GLIB in order to draw graphical objects in the pixel matrix buffers. Please refer to the documentation of EMWIN and/or GLIB in reptile/emwin/src/Doc and reptile/glib respectively. The documentation of GLIB is embedded in the source code.

NOTE: There is an issue with EMWIN that does not allow drawing on framebuffers of size 128x128 which happens to the size of the Sharp Memory LCD model LS013B7DH03. The DISPLAY interface supports a workaround that allows the user to allocate bigger framebuffers (pixelMatrix buffers) by using the userStride parameter which is included in the DISPLAY interface when EMWIN_WORKAROUND is defined. Therefore, in order to use EMWIN on the LS013B7DH03, the user must define EMWIN_WORKAROUND (typically in displayconfigapp.h) and request a userStride of at least 160 bits, not 128 bits which is the real width (in pixels) of the LS013B7DH03.

The pPixelMatrixClear function clears the contents of the pixel matrix buffer by setting it all to the default background colour.

The pDriverRefresh function should be called if the system resources. e.g. bus clock frequency, has undergone any changes. The pDriverRefresh function will recalibrate internal parameters associated with the display devices.

DISPLAY Device Driver Programming

This section contains a brief introduction to writing device drivers for specific display devices that can run properly in the DISPLAY device driver stack.

If you want to implement a new DISPLAY device driver, basically you need to implement an initialization function that populates a DISPLAY_Device_t data structure with the properties of the display device. At least the geometry DISPLAY_Geometry_t , the colour mode DISPLAY_ColourMode_t , the address mode DISPLAY_AddressMode_t , and the pPixelMatrixDraw function must be implemented. Whether the rest of the device specific functions may need to be implemented depends on the type of display device and application requirements. Also, the device driver programmer should be aware that the upper layers and examples of the DISPLAY device driver stack does not support all types of display devices and is continually being updated for new display devices. Therefore the upper layers and examples may need to be updated in order for existing software to work with a new display device driver.

When the DISPLAY_Device_t data structure is properly populated it should be registered in the DISPLAY module by calling the DISPLAY_DeviceRegister() function with a pointer to the DISPLAY_Device_t structure as parameter. This will make the display device available via the DISPLAY interface which is used by existing upper layer modules, examples and applications directly.

In order to automatically initialize the new display device driver from withing the DISPLAY_Init() function, the driver initialization function can be added to the list of initialization functions in displayconfig.h:

  // Define all display device driver initialization functions here.
#define DISPLAY_DEVICE_DRIVER_INIT_FUNCTIONS \
  {                                          \
   DISPLAY_Ls013b7dh03Init,                  \
   NULL                                      \
  }

The displayconfig.h file should also include #define inclusion constants for the specific display device drivers included in the system. Typically there is only one display device, however some systems may add more than one display devices if present.

Additionally, we recommended to implement a platform abstraction layer in order to facilitate for easy porting of the display device driver between different hardware and software platforms. The displaypal.h file declares an interface that abstracts the platform specifics required by the Sharp Memory LCD (model LS013B7DH03) device driver implemented in displayls013b7dh03.c . And displaypalemlib.c implements the PAL functions on top of EMLIB. A new device driver may need additional hardware and software services and the displaypal.h can be extended to support any such device.

DISPLAY Device Driver Stack Configuration

This section contains a description of the configuration interface of the DISPLAY device driver stack. The configuraion interface consists of a set of configuration files:

• One for each module in the DISPLAY device driver stack, where the platform default configurations are specified.
• One for each application called displayconfigapp.h in which the user can specify application specific configurations and override defaults if desired.
• And one that ties everything together by including all configuration files, called displayconfigall.h (included in display.h ).

Normally the application programmer just need to deal with the application specific configuration file displayconfigapp.h which typically should be minimalistic and easy to setup. Below is a list of the typical configuration parameters that the application programmer may need to relate to on a given platform/kit:

#define PIXEL_MATRIX_ALLOC_SUPPORT
     Specifies whether the DISPLAY device driver stack should include
     support for allocation of pixel matrices. The user should be aware
     that this may pull in malloc which consumes a relatively large amount
     of memory which is typically not wanted on kits with small amount of
     RAM. The user can define USE_STATIC_PIXEL_MATRIX_POOL in order to
     avoid malloc from being used.

#define USE_STATIC_PIXEL_MATRIX_POOL
     Specifies to use a statically allocated buffer pool to allocate pixel
     matrix buffers from. The user can specify the size of the pixel matrix
     buffer pool with PIXEL_MATRIX_POOL_SIZE.
     NOTE:
     The allocator does not support free'ing pixel matrices. It allocates
     continuosly from the static pool without keeping track of the sizes of
     old allocations. I.e. this is a one-shot allocator, and the  user should
     allocate buffers once at the beginning of the program.

#define PIXEL_MATRIX_POOL_SIZE
     Specifies the size of the static pixel matrix buffer pool. The pool size
     is highly application dependent, and the application programmer should
     consider to minimize this on system with a small amount of RAM.

#define INCLUDE_TEXTDISPLAY_SUPPORT
     Specifies whether to include TEXTDISPLAY support which implements a
     line based text output terminal interface supporting the C language
     stdout (standard output) interface including functions like printf,
     puts, putchar, etc.  The application programmer must select only one
     of the following fonts.

#define TEXTDISPLAY_FONT_6x8
     Select a font which is 6 pixels wide and 8 pixels high, resulting in
     21 column and 16 lines on a 128x128 display.

#define TEXTDISPLAY_FONT_8x8
     Select a font which is 8 pixels wide and 8 pixels high, resulting in
     16 column and 16 lines on a 128x128 display.

#define TEXTDISPLAY_NUMBER_FONT_16x20
     Select a _NUMBERS_ONLY_ font which is 16 pixels wide and 20 pixels high,
     resulting in 8 column and 6 lines on a 128x128 display.
     Note that this font does not include letters. It includes only the
     number characters 0,1,2,3,4,5,6,7,8,9 and additionally the colon ':' sign.
     This font is used by the digital clock mode in the clock example on the
     Zero Gecko starting kit (EFM32ZG_STK3200).

#define INCLUDE_VIDEO_TERMINAL_ESCAPE_SEQUENCE_SUPPORT
     Include support for some VT52/VT100 escape sequences in order to move the
     cursor around the screen without clearing the existing characters. Please
     refer to the textdisplay.h file for a list of supported escape sequence
     codes.

#define RETARGETTEXTDISPLAY_SCROLL_MODE
     Set to 'true' to enable scroll mode on the text display device where
     stdout is retargeted. Set to 'false' to disable scroll mode.

#define RETARGETTEXTDISPLAY_LINE_FEED_MODE
     Set to 'true' to enable adding Carriage Return (CR) to Line Feed (LF)
     characters on the text display device where stdout is retargeted.
     Set to 'false' to disable line feed mode.

#define PAL_TIMER_REPEAT_FUNCTION
     Specify a function that can register a callback function to be called
     repeatedly at a given frequency. On some platforms, like the
     EFM32ZG_STK3200, the DISPLAY driver Platform Abstraction Layer (PAL)
     uses the RTC to time and toggle the EXTCOMIN pin of the Sharp memory
     LCD per default. However, some applications, like the clock example
     want to use the RTC to keep track of time, i.e. generate interrupt
     every second. Therefore such applications need to support a
     'timer repeat' service function in order to support the PAL and
     take control over the RTC on the application level. E.g. the clock
     example implements a function (RtcIntCallbackRegister)) that
     enables the PAL to register the callback function that needs to be
     called in order to toggle the EXTCOMIN pin.

The rest of this section lists and describes the configuration parameters included in the module configuration files which are set to default values specific for the kit/platform. Each development kit from Silicon Labs that supports the DISPLAY Device driver stack includes a unique set of these configuration files in the kits/kit_name/config folder.

DISPLAY Module Configuration

This section includes descriptions of the configuration parameters for the DISPLAY Module specified in displayconfig.h.

#define INCLUDE_DISPLAY_SHARP_LS013B7DH03
     Include support for the SHARP Memory LCD model LS013B7DH03.

#define DISPLAY_DEVICES_MAX
     Maximum number of display devices the display module is configured
     to support. This number may be increased if the system includes more
     than one display device. However, the number should be kept low in order
     to save memory.

#define DISPLAY0_WIDTH and DISPLAY0_HEIGHT
     Specifies the geometry of display device #0 in the system. (I.e. on the
     Zero Gecko Kit (EFM32ZG_STK3200) the Sharp Memory LCD is 128x128 pixels
     high and wide, the DISPLAY0_WIDTH and DISPLAY0_HEIGHT should be 128.
     These defines can be used to declare static framebuffers in the
     application in order to save extra memory consumed by malloc.

#define DISPLAY_DEVICE_DRIVER_INIT_FUNCTIONS
     Lists the display device driver initialization function to be called
     automaticallyt by <em> DISPLAY_Init </em>.

Sharp Memory LCD Configuration

This section includes descriptions of the configuration parameters for the Sharp Memory LCD Device Driver specified in displayls013b7dh03config.h.

#define SHARP_MEMLCD_DEVICE_NAME
     Name of display device.

#define LCD_PORT_SCLK and LCD_PIN_SCLK
     Location of SPI clock pin.

#define LCD_PORT_SI and LCD_PIN_SI
     Location of SPI Slave Input pin.

#define LCD_PORT_SCS and LCD_PIN_SCS
     Location of SPI Chip Select pin.

#define LCD_PORT_EXTCOMIN and LCD_PIN_EXTCOMIN
     Location of External COM inversion signal pin.

#define LCD_PORT_DISP_SEL and LCD_PIN_DISP_SEL
     Location of Display on/off pin.

#define LCD_PORT_DISP_PWR and LCD_PIN_DISP_PWR
     Location of Display Power pin (if present on kit).

#define LCD_PORT_EXTMODE and LCD_PIN_EXTMODE
     Location of External COM inversion mode pin.

#define POLARITY_INVERSION_EXTCOMIN
     Select how LCD polarity inversion should be handled.
     If POLARITY_INVERSION_EXTCOMIN is defined, the EXTMODE pin is set to HIGH,
     and the polarity inversion is armed for every rising edge of the EXTCOMIN
     pin. The actual polarity inversion is triggered at the next transision of
     SCS. This mode is recommended because it causes less CPU and SPI load
     than the alternative mode, see below.
     If POLARITY_INVERSION_EXTCOMIN is undefined, the EXTMODE pin is set to
     LOW, and the polarity inversion is toggled by sending an SPI command.
     This mode causes more CPU and SPI load than using the EXTCOMIN pin mode.

#define POLARITY_INVERSION_EXTCOMIN_PAL_AUTO_TOGGLE
     Define POLARITY_INVERSION_EXTCOMIN_PAL_AUTO_TOGGLE if you want the PAL
     (Platform Abstraction Layer interface) to automatically toggle the
     EXTCOMIN pin.
     If the PAL_TIMER_REPEAT function is defined the EXTCOMIN toggling is
     handled by a timer repeat system, then
     POLARITY_INVERSION_EXTCOMIN_PAL_AUTO_TOGGLE should be undefined.

PAL Configuration

This section includes descriptions of the configuration parameters for the PAL (Platform Abstraction Layer) specified in displaypalconfig.h.

    // The user should select one of the following as  RTC clock source.
#define PAL_RTC_CLOCK_LFXO
     Selects the LFXO oscillator as source for the RTC clock.

#define PAL_RTC_CLOCK_LFRCO
     Selects the LFRCO oscillator as source for the RTC clock.

#define PAL_RTC_CLOCK_ULFRCO
     Selects the ULFRCO oscillator as source for the RTC clock.

#define PAL_SPI_USART_UNIT
     Select which USART device to use as SPI interface.

#define PAL_SPI_USART_CLOCK
     Select which USART clock is used to clock the SPI interface.

#define PAL_SPI_USART_LOCATION
     Route location of the USART/SPI pins.

#define PAL_SPI_BAUDRATE
     Specifies the SPI baud rate.

TEXTDISPLAY Configuration

The configuration of the TEXTDISPLAY and RETARGETTEXTDISPLAY is described in TextDisplay Library and Retarget TextDisplay Module .

Data Structures
struct	DISPLAY_Device_t
struct	DISPLAY_Geometry_t

Macros
#define	DISPLAY_EMSTATUS_INVALID_PARAMETER ( DISPLAY_EMSTATUS_BASE | 3)
#define	DISPLAY_EMSTATUS_NOT_ENOUGH_MEMORY ( DISPLAY_EMSTATUS_BASE | 1)
#define	DISPLAY_EMSTATUS_NOT_INITIALIZED ( DISPLAY_EMSTATUS_BASE | 5)
#define	DISPLAY_EMSTATUS_NOT_SUPPORTED ( DISPLAY_EMSTATUS_BASE | 4)
#define	DISPLAY_EMSTATUS_OK (0)
#define	DISPLAY_EMSTATUS_OUT_OF_RANGE ( DISPLAY_EMSTATUS_BASE | 2)

Typedefs
typedef enum DISPLAY_AddressMode_t	DISPLAY_AddressMode_t
typedef enum DISPLAY_ColourMode_t	DISPLAY_ColourMode_t
typedef struct DISPLAY_Device_t	DISPLAY_Device_t
typedef struct DISPLAY_Geometry_t	DISPLAY_Geometry_t
typedef void *	DISPLAY_PixelMatrix_t
typedef EMSTATUS(*	pDisplayDeviceDriverInitFunction_t ) (void)

Enumerations
enum	DISPLAY_AddressMode_t { DISPLAY_ADDRESSING_BY_ROWS_ONLY , DISPLAY_ADDRESSING_BY_ROWS_AND_COLUMNS }
enum	DISPLAY_ColourMode_t { DISPLAY_COLOUR_MODE_MONOCHROME , DISPLAY_COLOUR_MODE_MONOCHROME_INVERSE , DISPLAY_COLOUR_MODE_RGB_3BIT }

Functions
EMSTATUS	DISPLAY_DeviceGet (int displayDeviceNo, DISPLAY_Device_t *device)
	Get the display device data structure corresponding to the device number.
EMSTATUS	DISPLAY_DeviceRegister ( DISPLAY_Device_t *device)
	Register a display device.
EMSTATUS	DISPLAY_DriverRefresh (void)
	Refresh all DISPLAY devices.
EMSTATUS	DISPLAY_Init (void)
	Initialize the DISPLAY module.

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation