![]() |
![]() |
TI-RTOS Drivers
tidrivers_full_2_20_01_10
|
Generic interface for text output.
============================================================================
The display header file should be included in an application as follows:
The Display middleware-driver in TI-RTOS is designed to abstract operations and considerations specific to given output method.
The APIs in this driver serve as an interface to a typical TI-RTOS application. The specific peripheral implementations are responsible to create all the SYS/BIOS specific primitives to allow for thread-safe operation.
Because the Display driver serves as an abstraction, it is possible to specify the type of Display implementations that should be opened, as well as alternatively the config-array index value like with other TI-RTOS drivers.
Optionally, if no particular parameters are desired, the pointer to params can be replaced with NULL.
After the Display interface is opened, the user can call any of the APIs
It is also possible to prefer a graphical display if available. Perhaps most interesting for portable applications.
This module serves as the main interface for TI-RTOS applications. Its purpose is to redirect the module's APIs to specific implementations which are specified using a pointer to a Display_FxnTable.
The Display interface module is joined (at link time) to a NULL-terminated array of Display_Config data structures named Display_config. Display_config is implemented in the application with each entry being an instance of a Display implementation. Each entry in Display_config contains a:
In practical terms theat means the Display_Config struct for each specific implementation equates to an instance of an abstract Display 'class', where the functions are always provided the a Display_Config struct pointer in the parameter list, in liu of what in some languages is called this or self.
For example, Display_open is called, and display.c iterates over the available Display_Config's in the external Display_config array. For each config, config->fxns->open is called, and &config is provided for context.
The Display interface produces log statements if instrumentation is enabled.
Diagnostics Mask | Log details |
---|---|
Diags_USER1 | basic operations performed |
Diags_USER2 | detailed operations performed |
For most implementations of this interface it is only possible to call the APIs from Task or Main context because the implementations may rely on Semaphores or other RTOS services that do not work correctly or do not work at all in Hwi / Swi context.
Unless you know that the implementation is safe to use in Hwi/Swi, do not
#include <stdint.h>
Go to the source code of this file.
Data Structures | |
struct | Display_Params |
Display Parameters. More... | |
struct | Display_FxnTable |
The definition of a Display function table that contains the required set of functions to control a specific Display driver implementation. More... | |
struct | Display_Config |
Display Global configuration. More... | |
Macros | |
#define | Display_Type_ANY 0xFFFFFFFF |
#define | Display_Type_LCD 0x80000000 |
#define | Display_Type_UART 0x40000000 |
#define | Display_Type_LOG 0x20000000 |
#define | Display_Type_ITM 0x10000000 |
#define | Display_Type_GRLIB 0x00100000 |
#define | Display_MAXINDEX 15 |
#define | DISPLAY_CMD_RESERVED 32 |
#define | DISPLAY_STATUS_RESERVED -32 |
#define | DISPLAY_STATUS_SUCCESS 0 |
Successful status code returned by Display_control(). More... | |
#define | DISPLAY_STATUS_ERROR -1 |
Generic error status code returned by Display_control(). More... | |
#define | DISPLAY_STATUS_UNDEFINEDCMD -2 |
An error status code returned by Display_control() for undefined command codes. More... | |
#define | DISPLAY_CMD_TRANSPORT_CLOSE 0 |
Command used by Display_control to release its transport layer. More... | |
#define | DISPLAY_CMD_TRANSPORT_OPEN 1 |
Command used by Display_control to resume control of its transport. More... | |
#define | Display_clearLine(handle, n) Display_clearLines(handle, n, 0) |
#define | Display_isIndex(i) (i <= Display_MAXINDEX) |
#define | Display_isMetaType(i) (i > Display_MAXINDEX) |
#define | Display_open(id, params) Display_doOpen(id, params) |
#define | Display_Params_init(params) Display_doParamsInit(params) |
#define | Display_clear(handle) Display_doClear(handle) |
#define | Display_clearLines(handle, fromLine, toLine) Display_doClearLines(handle, fromLine, toLine) |
#define | Display_print0(handle, line, col, fmt) Display_print5(handle, line, col, (uintptr_t)(fmt), 0, 0, 0, 0, 0) |
#define | Display_print1(handle, line, col, fmt, a0) Display_print5(handle, line, col, (uintptr_t)(fmt), (uintptr_t)(a0), 0, 0, 0, 0) |
#define | Display_print2(handle, line, col, fmt, a0, a1) Display_print5(handle, line, col, (uintptr_t)(fmt), (uintptr_t)(a0), (uintptr_t)(a1), 0, 0, 0) |
#define | Display_print3(handle, line, col, fmt, a0, a1, a2) Display_print5(handle, line, col, (uintptr_t)(fmt), (uintptr_t)(a0), (uintptr_t)(a1), (uintptr_t)(a2), 0, 0) |
#define | Display_print4(handle, line, col, fmt, a0, a1, a2, a3) Display_print5(handle, line, col, (uintptr_t)(fmt), (uintptr_t)(a0), (uintptr_t)(a1), (uintptr_t)(a2), (uintptr_t)(a3), 0) |
#define | Display_print5(handle, line, col, fmt, a0, a1, a2, a3, a4) Display_doPut5(handle, line, col, (uintptr_t)(fmt), (uintptr_t)(a0), (uintptr_t)(a1), (uintptr_t)(a2), (uintptr_t)(a3), (uintptr_t)(a4)) |
#define | Display_control(handle, cmd, arg) Display_doControl(handle, cmd, arg) |
#define | Display_close(handle) Display_doClose(handle) |
Typedefs | |
typedef struct Display_Config * | Display_Handle |
A handle for specific Display implementations. More... | |
typedef enum Display_LineClearMode | Display_LineClearMode |
How to treat existing elements on a line when writing text. More... | |
typedef struct Display_Params | Display_Params |
Display Parameters. More... | |
typedef Display_Handle(* | Display_openFxn) (Display_Handle handle, Display_Params *params) |
A function pointer to a specific implementation of Display_open(). More... | |
typedef void(* | Display_clearFxn) (Display_Handle handle) |
A function pointer to a specific implementation of Display_clear(). More... | |
typedef void(* | Display_clearLinesFxn) (Display_Handle handle, uint8_t fromLine, uint8_t toLine) |
A function pointer to a specific implementation of Display_clearLines(). More... | |
typedef void(* | Display_put5Fxn) (Display_Handle handle, uint8_t line, uint8_t column, uintptr_t fmt, uintptr_t a0, uintptr_t a1, uintptr_t a2, uintptr_t a3, uintptr_t a4) |
A function pointer to a specific implementation of Display_put5(). More... | |
typedef void(* | Display_closeFxn) (Display_Handle) |
A function pointer to a specific implementation of Display_close(). More... | |
typedef int(* | Display_controlFxn) (Display_Handle handle, unsigned int cmd, void *arg) |
A function pointer to a driver specific implementation of Display_control(). More... | |
typedef unsigned int(* | Display_getTypeFxn) (void) |
A function pointer to a specific implementation of Display_getType(). More... | |
typedef struct Display_FxnTable | Display_FxnTable |
The definition of a Display function table that contains the required set of functions to control a specific Display driver implementation. More... | |
typedef struct Display_Config | Display_Config |
Display Global configuration. More... | |
Enumerations | |
enum | Display_LineClearMode { DISPLAY_CLEAR_NONE = 0, DISPLAY_CLEAR_LEFT, DISPLAY_CLEAR_RIGHT, DISPLAY_CLEAR_BOTH } |
How to treat existing elements on a line when writing text. More... | |
Functions | |
Display_Handle | Display_doOpen (uint32_t id, Display_Params *params) |
Initialize all the selected Display implementations. More... | |
void | Display_doParamsInit (Display_Params *params) |
Initializes parameter structure with default parameters. More... | |
void | Display_doClear (Display_Handle handle) |
Calls the clear fxn of all opened Display implementations. More... | |
void | Display_doClearLines (Display_Handle handle, uint8_t fromLine, uint8_t toLine) |
Calls the clearLines fxn of all opened Display implementations. More... | |
void | Display_doPut5 (Display_Handle handle, uint8_t line, uint8_t column, uintptr_t fmt, uintptr_t a0, uintptr_t a1, uintptr_t a2, uintptr_t a3, uintptr_t a4) |
Calls the output function of all opened Display implementations. More... | |
void | Display_doClose (Display_Handle handle) |
Closes selected Display implementations. More... | |
void | Display_doControl (Display_Handle handle, unsigned int cmd, void *arg) |
Function performs implementation specific features on a given Display_Handle. More... | |
#define Display_MAXINDEX 15 |
Max allowed displays. Any index value above this is a meta-type index.
#define Display_clearLine | ( | handle, | |
n | |||
) | Display_clearLines(handle, n, 0) |
#define Display_isIndex | ( | i | ) | (i <= Display_MAXINDEX) |
#define Display_isMetaType | ( | i | ) | (i > Display_MAXINDEX) |
#define Display_open | ( | id, | |
params | |||
) | Display_doOpen(id, params) |
Open selected display id or the first display of type.
#define Display_Params_init | ( | params | ) | Display_doParamsInit(params) |
Initialize default parameters.
#define Display_clear | ( | handle | ) | Display_doClear(handle) |
Clear display
#define Display_clearLines | ( | handle, | |
fromLine, | |||
toLine | |||
) | Display_doClearLines(handle, fromLine, toLine) |
Clear lines in display
#define Display_print0 | ( | handle, | |
line, | |||
col, | |||
fmt | |||
) | Display_print5(handle, line, col, (uintptr_t)(fmt), 0, 0, 0, 0, 0) |
Output string fmt with 0 arguments to display
#define Display_print1 | ( | handle, | |
line, | |||
col, | |||
fmt, | |||
a0 | |||
) | Display_print5(handle, line, col, (uintptr_t)(fmt), (uintptr_t)(a0), 0, 0, 0, 0) |
Output string fmt with 1 argument to display
#define Display_print2 | ( | handle, | |
line, | |||
col, | |||
fmt, | |||
a0, | |||
a1 | |||
) | Display_print5(handle, line, col, (uintptr_t)(fmt), (uintptr_t)(a0), (uintptr_t)(a1), 0, 0, 0) |
Output string fmt with 2 arguments to display
#define Display_print3 | ( | handle, | |
line, | |||
col, | |||
fmt, | |||
a0, | |||
a1, | |||
a2 | |||
) | Display_print5(handle, line, col, (uintptr_t)(fmt), (uintptr_t)(a0), (uintptr_t)(a1), (uintptr_t)(a2), 0, 0) |
Output string fmt with 3 arguments to display
#define Display_print4 | ( | handle, | |
line, | |||
col, | |||
fmt, | |||
a0, | |||
a1, | |||
a2, | |||
a3 | |||
) | Display_print5(handle, line, col, (uintptr_t)(fmt), (uintptr_t)(a0), (uintptr_t)(a1), (uintptr_t)(a2), (uintptr_t)(a3), 0) |
Output string fmt with 4 arguments to display
#define Display_print5 | ( | handle, | |
line, | |||
col, | |||
fmt, | |||
a0, | |||
a1, | |||
a2, | |||
a3, | |||
a4 | |||
) | Display_doPut5(handle, line, col, (uintptr_t)(fmt), (uintptr_t)(a0), (uintptr_t)(a1), (uintptr_t)(a2), (uintptr_t)(a3), (uintptr_t)(a4)) |
Output string fmt with 5 arguments to display
#define Display_control | ( | handle, | |
cmd, | |||
arg | |||
) | Display_doControl(handle, cmd, arg) |
Control a specific Display driver
#define Display_close | ( | handle | ) | Display_doClose(handle) |
Close display
typedef struct Display_Config* Display_Handle |
A handle for specific Display implementations.
typedef enum Display_LineClearMode Display_LineClearMode |
How to treat existing elements on a line when writing text.
typedef struct Display_Params Display_Params |
Display Parameters.
Display parameters are used with the Display_open() call. Default values for these parameters are set using Display_Params_init().
typedef Display_Handle(* Display_openFxn) (Display_Handle handle, Display_Params *params) |
A function pointer to a specific implementation of Display_open().
typedef void(* Display_clearFxn) (Display_Handle handle) |
A function pointer to a specific implementation of Display_clear().
typedef void(* Display_clearLinesFxn) (Display_Handle handle, uint8_t fromLine, uint8_t toLine) |
A function pointer to a specific implementation of Display_clearLines().
typedef void(* Display_put5Fxn) (Display_Handle handle, uint8_t line, uint8_t column, uintptr_t fmt, uintptr_t a0, uintptr_t a1, uintptr_t a2, uintptr_t a3, uintptr_t a4) |
A function pointer to a specific implementation of Display_put5().
typedef void(* Display_closeFxn) (Display_Handle) |
A function pointer to a specific implementation of Display_close().
typedef int(* Display_controlFxn) (Display_Handle handle, unsigned int cmd, void *arg) |
A function pointer to a driver specific implementation of Display_control().
typedef unsigned int(* Display_getTypeFxn) (void) |
A function pointer to a specific implementation of Display_getType().
typedef struct Display_FxnTable Display_FxnTable |
The definition of a Display function table that contains the required set of functions to control a specific Display driver implementation.
typedef struct Display_Config Display_Config |
Display Global configuration.
The Display_Config structure contains a set of pointers used to characterize the Display interface implementation.
This structure needs to be defined before calling Display_open() and it must not be changed thereafter.
How to treat existing elements on a line when writing text.
Display_Handle Display_doOpen | ( | uint32_t | id, |
Display_Params * | params | ||
) |
Initialize all the selected Display implementations.
The index parameter can be an index in the global Display_config array, or a meta-type signifying which types of display to open.
The different allowed values in addition to actual index are:
id | - Index of Display in Display_config array, or alternatively the type(s) of displays to open |
params | - display parameters |
void Display_doParamsInit | ( | Display_Params * | params | ) |
Initializes parameter structure with default parameters.
params |
void Display_doClear | ( | Display_Handle | handle | ) |
Calls the clear fxn of all opened Display implementations.
handle | - handle of display |
void Display_doClearLines | ( | Display_Handle | handle, |
uint8_t | fromLine, | ||
uint8_t | toLine | ||
) |
Calls the clearLines fxn of all opened Display implementations.
handle | - handle of display |
fromLine | - line index (0 .. ) |
toLine | - line index (0 .. ) |
void Display_doPut5 | ( | Display_Handle | handle, |
uint8_t | line, | ||
uint8_t | column, | ||
uintptr_t | fmt, | ||
uintptr_t | a0, | ||
uintptr_t | a1, | ||
uintptr_t | a2, | ||
uintptr_t | a3, | ||
uintptr_t | a4 | ||
) |
Calls the output function of all opened Display implementations.
handle | - handle of display |
line | - line index (0..) |
column | - column index (0..) |
fmt | - format string |
a0 | - optional format arguments |
a1 | - optional format arguments |
a2 | - optional format arguments |
a3 | - optional format arguments |
a4 | - optional format arguments |
void Display_doClose | ( | Display_Handle | handle | ) |
Closes selected Display implementations.
void Display_doControl | ( | Display_Handle | handle, |
unsigned int | cmd, | ||
void * | arg | ||
) |
Function performs implementation specific features on a given Display_Handle.
Commands for Display_control can originate from Display.h or from implementation specific Display*.h (DisplaySharp.h, DisplayUart.h, etc.. ) files. While commands from Display.h are API portable across driver implementations, not all implementations may support all these commands. Conversely, commands from driver implementation specific Display*.h files add unique driver capabilities but are not API portable across all Display driver implementations.
Commands supported by Display.h follow a DISPLAY_CMD_<cmd> naming convention.
Commands supported by Display*.h follow a DISPLAY*_CMD_<cmd> naming convention.
Each control command defines arg differently. The types of arg are documented with each command.
See Display_control command codes for command codes.
See Display_control return status codes for status codes.
handle | A Display handle returned from Display() |
cmd | Display.h or Display*.h commands. |
arg | An optional R/W (read/write) command argument accompanied with cmd |