|
EFM32 Gecko Software Documentation
efm32g-doc-5.1.2
|
|
EFM32 Gecko Software Documentation
efm32g-doc-5.1.2
|
Display device driver stack library. See Display Device Driver Stack for more information.
The source files for the DISPLAY device driver stack library resides in the kits/common/drivers directory and follows the naming convention: displaymodule_name.c/h.
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.
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:
If DISPLAY_DeviceGet() is successful, the specified DISPLAY_Device_t structure contains the properties of the display device. 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 two colour modi are defined in DISPLAY_ColourMode_t :
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 pixel matrix buffer format for the monochrome modi is defined as a byte array where
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.
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.
We recommend to study the existing DISPLAY device driver(s). At the time of writing this text, there exists only one DISPLAY device driver for the Sharp Memory LCD (model LS013B7DH03) implemented in displayls013b7dh03.c/h.
When the DISPLAY_Device_t data structure is properly populated it should be registered in the DISPLAY module by calling the DISPLAY_DeviceRegister function (declared in displaybackend.h) 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.
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:
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.
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>.
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.
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.
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) |
Functions | |
| EMSTATUS | DISPLAY_DeviceGet (int displayDeviceNo, DISPLAY_Device_t *device) |
| Get the display device data structure corresponding to the device number. More... | |
| EMSTATUS | DISPLAY_DeviceRegister (DISPLAY_Device_t *device) |
| Register a display device. More... | |
| EMSTATUS | DISPLAY_DriverRefresh (void) |
| Refresh all DISPLAY devices. More... | |
| EMSTATUS | DISPLAY_Init (void) |
| Initialize the DISPLAY module. More... | |
| #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) |
Feature/option not supported.
Definition at line 50 of file display.h.
Referenced by DISPLAY_DeviceGet(), DISPLAY_DeviceRegister(), and DISPLAY_DriverRefresh().
| #define DISPLAY_EMSTATUS_NOT_SUPPORTED (DISPLAY_EMSTATUS_BASE | 4) |
| #define DISPLAY_EMSTATUS_OK (0) |
EMSTATUS codes of the display interface. Operation successful.
Definition at line 45 of file display.h.
Referenced by DISPLAY_DeviceGet(), DISPLAY_DeviceRegister(), DISPLAY_DriverRefresh(), DISPLAY_Init(), RETARGET_TextDisplayInit(), and TEXTDISPLAY_New().
| #define DISPLAY_EMSTATUS_OUT_OF_RANGE (DISPLAY_EMSTATUS_BASE | 2) |
Parameters out of range.
Definition at line 47 of file display.h.
Referenced by DISPLAY_DeviceGet().
| typedef enum DISPLAY_AddressMode_t DISPLAY_AddressMode_t |
Display device address modes.
| typedef enum DISPLAY_ColourMode_t DISPLAY_ColourMode_t |
Display device colour modes.
| typedef struct DISPLAY_Device_t DISPLAY_Device_t |
Display device data structure, including a specification of how the display device behaves.
| typedef struct DISPLAY_Geometry_t DISPLAY_Geometry_t |
Display geometry specification.
| typedef void* DISPLAY_PixelMatrix_t |
| typedef EMSTATUS(* pDisplayDeviceDriverInitFunction_t) (void) |
Display device address modes.
| enum DISPLAY_ColourMode_t |
| EMSTATUS DISPLAY_DeviceGet | ( | int | displayDeviceNo, |
| DISPLAY_Device_t * | device | ||
| ) |
Get the display device data structure corresponding to the device number.
| [in] | displayDeviceNo | Unique device number of one of the display devices in the system. |
| [out] | device | Pointer to a DISPLAY_Device_t structure which will be populated with the properties of the specified display device if the function is successful. |
Definition at line 139 of file display.c.
References DISPLAY_EMSTATUS_NOT_INITIALIZED, DISPLAY_EMSTATUS_OK, and DISPLAY_EMSTATUS_OUT_OF_RANGE.
Referenced by RETARGET_TextDisplayInit(), and TEXTDISPLAY_New().
| EMSTATUS DISPLAY_DeviceRegister | ( | DISPLAY_Device_t * | device | ) |
Register a display device.
| device | The display device structure which specifies the properties of the display. |
Definition at line 172 of file display.c.
References DISPLAY_EMSTATUS_NOT_ENOUGH_MEMORY, DISPLAY_EMSTATUS_NOT_INITIALIZED, and DISPLAY_EMSTATUS_OK.
| EMSTATUS DISPLAY_DriverRefresh | ( | void | ) |
Refresh all DISPLAY devices.
This function requests all DISPLAY device drivers to update their internal state with respect to system resource changes, like a bus clock frequency. This function may need to be called after system changes.
Definition at line 97 of file display.c.
References DISPLAY_EMSTATUS_NOT_INITIALIZED, DISPLAY_EMSTATUS_OK, and DISPLAY_Device_t::pDriverRefresh.
| EMSTATUS DISPLAY_Init | ( | void | ) |
Initialize the DISPLAY module.
Definition at line 64 of file display.c.
References DISPLAY_EMSTATUS_OK.
1.8.10