Generic interface for text output.
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. The application initializes the Display driver by calling Display_init() and is then ready to open a Display by calling Display_open() and passing in a Display parameters data structure.
This documentation provides a basic usage summary and a set of examples in the form of commented code fragments. Detailed descriptions of the APIs are provided in subsequent sections.
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
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 use this interface in other contexts than Main and Task.
Refer to the Driver's Configuration section for driver configuration information.
#include <stdint.h>
#include <stdarg.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_INVALID 0x00000000 |
#define | Display_Type_LCD 0x80000000 |
#define | Display_Type_UART 0x40000000 |
#define | Display_Type_LOG 0x20000000 |
#define | Display_Type_ITM 0x10000000 |
#define | Display_Type_HOST 0x08000000 |
#define | Display_Type_ANSI 0x04000000 |
#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_init() Display_doInit() |
#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_printf Display_doPrintf |
#define | Display_print0(handle, line, col, fmt) Display_printf(handle, line, col, fmt) |
#define | Display_print1(handle, line, col, fmt, a0) Display_printf(handle, line, col, fmt, a0) |
#define | Display_print2(handle, line, col, fmt, a0, a1) Display_printf(handle, line, col, fmt, a0, a1) |
#define | Display_print3(handle, line, col, fmt, a0, a1, a2) Display_printf(handle, line, col, fmt, a0, a1, a2) |
#define | Display_print4(handle, line, col, fmt, a0, a1, a2, a3) Display_printf(handle, line, col, fmt, a0, a1, a2, a3) |
#define | Display_print5(handle, line, col, fmt, a0, a1, a2, a3, a4) Display_printf(handle, line, col, fmt, a0, a1, a2, a3, a4) |
#define | Display_getType(handle) Display_doGetType(handle) |
#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 void(* | Display_initFxn) (Display_Handle handle) |
A function pointer to a specific implementation of Display_initFxn(). 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_vprintfFxn) (Display_Handle handle, uint8_t line, uint8_t column, char *fmt, va_list va) |
A function pointer to a specific implementation of Display_vprintf(). 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_doPrintf (Display_Handle handle, uint8_t line, uint8_t column, char *fmt,...) |
Calls the output function of all opened Display implementations. More... | |
void | Display_doClose (Display_Handle handle) |
Closes selected Display implementations. More... | |
uint32_t | Display_doGetType (Display_Handle handle) |
Gets the type of display for the handle. More... | |
void | Display_doControl (Display_Handle handle, unsigned int cmd, void *arg) |
Function performs implementation specific features on a given Display_Handle. More... | |
void | Display_doInit (void) |
Function to initializes the Display driver. 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_init | ( | ) | Display_doInit() |
Initializes the Display driver.
#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_printf Display_doPrintf |
Output string fmt with variable arguments to display
#define Display_print0 | ( | handle, | |
line, | |||
col, | |||
fmt | |||
) | Display_printf(handle, line, col, fmt) |
Output string fmt with 0 arguments to display
#define Display_print1 | ( | handle, | |
line, | |||
col, | |||
fmt, | |||
a0 | |||
) | Display_printf(handle, line, col, fmt, a0) |
Output string fmt with 1 argument to display
#define Display_print2 | ( | handle, | |
line, | |||
col, | |||
fmt, | |||
a0, | |||
a1 | |||
) | Display_printf(handle, line, col, fmt, a0, a1) |
Output string fmt with 2 arguments to display
#define Display_print3 | ( | handle, | |
line, | |||
col, | |||
fmt, | |||
a0, | |||
a1, | |||
a2 | |||
) | Display_printf(handle, line, col, fmt, a0, a1, a2) |
Output string fmt with 3 arguments to display
#define Display_print4 | ( | handle, | |
line, | |||
col, | |||
fmt, | |||
a0, | |||
a1, | |||
a2, | |||
a3 | |||
) | Display_printf(handle, line, col, fmt, a0, a1, a2, a3) |
Output string fmt with 4 arguments to display
#define Display_print5 | ( | handle, | |
line, | |||
col, | |||
fmt, | |||
a0, | |||
a1, | |||
a2, | |||
a3, | |||
a4 | |||
) | Display_printf(handle, line, col, fmt, a0, a1, a2, a3, a4) |
Output string fmt with 5 arguments to display
#define Display_getType | ( | handle | ) | Display_doGetType(handle) |
Get type of 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 void(* Display_initFxn) (Display_Handle handle) |
A function pointer to a specific implementation of Display_initFxn().
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_vprintfFxn) (Display_Handle handle, uint8_t line, uint8_t column, char *fmt, va_list va) |
A function pointer to a specific implementation of Display_vprintf().
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:
[in] | id | - Index of Display in Display_config array, or alternatively the type(s) of displays to open |
[in] | params | - display parameters |
void Display_doParamsInit | ( | Display_Params * | params | ) |
Initializes parameter structure with default parameters.
[in] | params |
void Display_doClear | ( | Display_Handle | handle | ) |
Calls the clear fxn of all opened Display implementations.
[in] | 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.
[in] | handle | - handle of display |
[in] | fromLine | - line index (0 .. ) |
[in] | toLine | - line index (0 .. ) |
void Display_doPrintf | ( | Display_Handle | handle, |
uint8_t | line, | ||
uint8_t | column, | ||
char * | fmt, | ||
... | |||
) |
Calls the output function of all opened Display implementations.
[in] | handle | - handle of display |
[in] | line | - line index (0..) |
[in] | column | - column index (0..) |
[in] | fmt | - format string |
[in] | ... | - optional arguments |
void Display_doClose | ( | Display_Handle | handle | ) |
Closes selected Display implementations.
uint32_t Display_doGetType | ( | Display_Handle | handle | ) |
Gets the type of display for the handle.
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.
[in] | handle | A Display handle returned from Display() |
[in] | cmd | Display.h or Display*.h commands. |
[in] | arg | An optional R/W (read/write) command argument accompanied with cmd |
void Display_doInit | ( | void | ) |
Function to initializes the Display driver.