Detailed Description

Generic interface for text output.

============================================================================

Driver include

The display header file should be included in an application as follows:

Operation

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.

Note: Display APIs can only be called from task context.; All Display statements will be removed and no display operations will take place if the symbol Display_DISABLE_ALL is defined globally, or before Display.h is included.

Opening the driver

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.

Display_Handle    handle;
Display_Params    params;
Display_Params_init(&params);
handle = Display_open(someConfigIndexValue, &params);
//Display_open(Display_Type_HOST, &params);
//Display_open(Display_Type_ANY, &params);
//Display_open(Display_Type_UART, NULL);
//Display_open(Display_Type_UART | Display_Type_LCD, &params);

Outputting data

After the Display interface is opened, the user can call any of the APIs

Display_clear(handle);
Display_clearLines(handle, 0, 4);
Display_printf(handle, 1, 0, "How are you %s?", yourName);
// Note that for floating point support, the .cfg file must have a line like
// System.extendedFormats = "%$L%$S%$F%f"; // Add '%f' support
Display_printf(handle, 3, 0, "Pi is %f", 3.1415);
Display_close(handle);

It is also possible to prefer a graphical display if available. Perhaps most interesting for portable applications.

Display_Handle    handle;
Display_Params    params;
Display_Params_init(&params);
handle = Display_open(Display_Type_LCD, &params);
if (NULL == handle)
   handle = Display_open(Display_Type_UART, &params);

Note: Display_printX can only be called from Task context, unless the only opened interfaces specifically allow calls from any context.

Implementation

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:

(Display_FxnTable *) to a set of functions implementing an output channel
(void *) data object that is associated with the Display_FxnTable
(void *) hardware attributes that are associated to the Display_FxnTable

In practical terms that 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 lieu 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.

Below is an example configuration to use the HOST display.

#include <ti/display/Display.h>
#include <ti/display/DisplayHost.h>
#define MAXPRINTLEN 1024
DisplayHost_Object displayHostObject;
static char displayBuf[MAXPRINTLEN];
const DisplayHost_HWAttrs displayHostHWAttrs = {
    .strBuf = displayBuf,
    .strBufLen = MAXPRINTLEN
};
const Display_Config Display_config[] = {
    {
        .fxnTablePtr = &DisplayHost_fxnTable,
        .object = &displayHostObject,
        .hwAttrs = &displayHostHWAttrs
    }
};
const uint8_t Display_count = sizeof(Display_config) / sizeof(Display_Config);

Instrumentation

The Display interface produces log statements if instrumentation is enabled.

Diagnostics Mask	Log details
Diags_USER1	basic operations performed
Diags_USER2	detailed operations performed

Calling Context

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.

#include <stdint.h>
#include <stdarg.h>

Include dependency graph for Display.h:

This graph shows which files directly or indirectly include this file:

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...

Macro Definition Documentation

§ Display_MAXINDEX

#define Display_MAXINDEX 15

Max allowed displays. Any index value above this is a meta-type index.

§ Display_clearLine

#define Display_clearLine	(	handle,
		n
	)	Display_clearLines(handle, n, 0)

§ Display_isIndex

#define Display_isIndex ( i ) (i <= Display_MAXINDEX)

§ Display_isMetaType

#define Display_isMetaType ( i ) (i > Display_MAXINDEX)

§ Display_init

#define Display_init ( ) Display_doInit()

Initializes the Display driver.

See also: Display_doInit()

§ Display_open

#define Display_open	(	id,
		params
	)	Display_doOpen(id, params)

Open selected display id or the first display of type.

See also: Display_doOpen()

§ Display_Params_init

#define Display_Params_init ( params ) Display_doParamsInit(params)

Initialize default parameters.

See also: Display_doParamsInit()

§ Display_clear

#define Display_clear ( handle ) Display_doClear(handle)

Clear display

See also: Display_doClear()

§ Display_clearLines

#define Display_clearLines	(	handle,
		fromLine,
		toLine
	)	Display_doClearLines(handle, fromLine, toLine)

Clear lines in display

See also: Display_doClearLines()

§ Display_printf

#define Display_printf Display_doPrintf

Output string fmt with variable arguments to display

See also: Display_doPrintf()

§ Display_print0

#define Display_print0	(	handle,
		line,
		col,
		fmt
	)	Display_printf(handle, line, col, fmt)

Output string fmt with 0 arguments to display

See also: Display_doPrintf()

§ Display_print1

#define Display_print1	(	handle,
		line,
		col,
		fmt,
		a0
	)	Display_printf(handle, line, col, fmt, a0)

Output string fmt with 1 argument to display

See also: Display_doPrintf()

§ Display_print2

#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

See also: Display_doPrintf()

§ Display_print3

#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

See also: Display_doPrintf()

§ Display_print4

#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

See also: Display_doPrintf()

§ Display_print5

#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

See also: Display_doPrintf()

§ Display_getType

#define Display_getType ( handle ) Display_doGetType(handle)

Get type of display

§ Display_control

#define Display_control	(	handle,
		cmd,
		arg
	)	Display_doControl(handle, cmd, arg)

Control a specific Display driver

See also: Display_doControl()

§ Display_close

#define Display_close ( handle ) Display_doClose(handle)

Close display

See also: Display_doClose()

Typedef Documentation

§ Display_Handle

typedef struct Display_Config* Display_Handle

A handle for specific Display implementations.

§ Display_initFxn

typedef void(* Display_initFxn) (Display_Handle handle)

A function pointer to a specific implementation of Display_initFxn().

§ Display_LineClearMode

typedef enum Display_LineClearMode Display_LineClearMode

How to treat existing elements on a line when writing text.

§ Display_Params

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().

See also: Display_Params_init()

§ Display_openFxn

typedef Display_Handle(* Display_openFxn) (Display_Handle handle, Display_Params *params)

A function pointer to a specific implementation of Display_open().

§ Display_clearFxn

typedef void(* Display_clearFxn) (Display_Handle handle)

A function pointer to a specific implementation of Display_clear().

§ Display_clearLinesFxn

typedef void(* Display_clearLinesFxn) (Display_Handle handle, uint8_t fromLine, uint8_t toLine)

A function pointer to a specific implementation of Display_clearLines().

§ Display_vprintfFxn

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().

§ Display_closeFxn

typedef void(* Display_closeFxn) (Display_Handle)

A function pointer to a specific implementation of Display_close().

§ Display_controlFxn

typedef int(* Display_controlFxn) (Display_Handle handle, unsigned int cmd, void *arg)

A function pointer to a driver specific implementation of Display_control().

§ Display_getTypeFxn

typedef unsigned int(* Display_getTypeFxn) (void)

A function pointer to a specific implementation of Display_getType().

§ Display_FxnTable

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.

§ Display_Config

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.

See also: Display_init()

Enumeration Type Documentation

§ Display_LineClearMode

enum Display_LineClearMode

How to treat existing elements on a line when writing text.

Enumerator
DISPLAY_CLEAR_NONE	Do not clear anything before writing
DISPLAY_CLEAR_LEFT	Clear pixels to left of text on the line
DISPLAY_CLEAR_RIGHT	Clear pixels to right of text on the line
DISPLAY_CLEAR_BOTH	Clear pixels on both sides of text

Function Documentation

§ Display_doOpen()

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:

Display_Type_ANY open and use the first available display
Display_Type_HOST open and use HOST type displays
Display_Type_LCD open and use LCD type displays
Display_Type_UART open and use UART type displays
Display_Type_LOG open and use xdc.runtime.Log type displays
Display_ITM open and use ARM ITM output type displays
Display_Type_GRLIB open and use GrLib capable displays It is possible to combine types: Display_Type_UART | Display_Type_LCD

Note: Only one display is opened. If the type matches more than one, only the first one found in the Display_config array is opened.

Precondition: Display_init() has been called

Parameters

id	- Index of Display in Display_config array, or alternatively the type(s) of displays to open
params	- display parameters

Returns: Display_Handle of opened Display or NULL.

See also: Display_doInit(); Display_doClose()

§ Display_doParamsInit()

void Display_doParamsInit ( Display_Params * params )

Initializes parameter structure with default parameters.

Parameters

params

Returns: void

§ Display_doClear()

void Display_doClear ( Display_Handle handle )

Calls the clear fxn of all opened Display implementations.

Parameters

handle - handle of display

Returns: void

§ Display_doClearLines()

void Display_doClearLines	(	Display_Handle	handle,
		uint8_t	fromLine,
		uint8_t	toLine
	)

Calls the clearLines fxn of all opened Display implementations.

Parameters

handle	- handle of display
fromLine	- line index (0 .. )
toLine	- line index (0 .. )

Returns: void

§ Display_doPrintf()

void Display_doPrintf	(	Display_Handle	handle,
		uint8_t	line,
		uint8_t	column,
		char *	fmt,
			...
	)

Calls the output function of all opened Display implementations.

Parameters

handle	- handle of display
line	- line index (0..)
column	- column index (0..)
fmt	- format string
...	- optional arguments

Returns: void

§ Display_doClose()

void Display_doClose ( Display_Handle handle )

Closes selected Display implementations.

Returns: void

§ Display_doGetType()

uint32_t Display_doGetType ( Display_Handle handle )

Gets the type of display for the handle.

See also: Meta-types of display implementations

Returns: uint32_t representing Display_Type_Xxxx

§ Display_doControl()

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.

Precondition: Display_open() has to be called first.

Parameters

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

Returns: Implementation specific return codes. Negative values indicate unsuccessful operations.

§ Display_doInit()

void Display_doInit ( void )

Function to initializes the Display driver.

Precondition: The Display_config structure must exist and be persistent before this function can be called. This function must also be called before any other Display driver APIs.

Detailed Description

Driver include

Operation

Opening the driver

Outputting data

Implementation

Instrumentation

Calling Context

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

§ Display_MAXINDEX

§ Display_clearLine

§ Display_isIndex

§ Display_isMetaType

§ Display_init

§ Display_open

§ Display_Params_init

§ Display_clear

§ Display_clearLines

§ Display_printf

§ Display_print0

§ Display_print1

§ Display_print2

§ Display_print3

§ Display_print4

§ Display_print5

§ Display_getType

§ Display_control

§ Display_close

Typedef Documentation

§ Display_Handle

§ Display_initFxn

§ Display_LineClearMode

§ Display_Params

§ Display_openFxn

§ Display_clearFxn

§ Display_clearLinesFxn

§ Display_vprintfFxn

§ Display_closeFxn

§ Display_controlFxn

§ Display_getTypeFxn

§ Display_FxnTable

§ Display_Config

Enumeration Type Documentation

§ Display_LineClearMode

Function Documentation

§ Display_doOpen()

§ Display_doParamsInit()

§ Display_doClear()

§ Display_doClearLines()

§ Display_doPrintf()

§ Display_doClose()

§ Display_doGetType()

§ Display_doControl()

§ Display_doInit()