Detailed Description

Generic interface for text output.

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

Driver include

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

#include <ti/mw/Display.h>

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.

Note: 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_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_print0(handle, 1, 0, "Hello"); //--> 'Hello' output on line 1, col 0
Display_print1(handle, 2, 0, "Hello %d", 42); // --> 'Hello 42' on line 2, col 0
// ...
Display_print5(handle, 5, 0, "Hello %d %d %d %d %d", 1, 2, 3, 4, 5);
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 implemening 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 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.

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

Macro Definition Documentation

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

See also: Display_doOpen()

#define Display_Params_init ( params ) Display_doParamsInit(params)

Initialize default parameters.

See also: Display_doParamsInit()

#define Display_clear ( handle ) Display_doClear(handle)

Clear display

See also: Display_doClear()

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

Clear lines in display

See also: Display_doClearLines()

#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

See also: Display_doPut5()

#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

See also: Display_doPut5()

#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

See also: Display_doPut5()

#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

See also: Display_doPut5()

#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

See also: Display_doPut5()

#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

See also: Display_doPut5()

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

Control a specific Display driver

See also: Display_doControl()

#define Display_close ( handle ) Display_doClose(handle)

Close display

See also: Display_doClose()

Typedef Documentation

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

See also: 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.

See also: Display_open()

Enumeration Type Documentation

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

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.

void Display_doParamsInit ( Display_Params * params )

Initializes parameter structure with default parameters.

Parameters

params

Returns: void

void Display_doClear ( Display_Handle handle )

Calls the clear fxn of all opened Display implementations.

Parameters

handle - handle of display

Returns: void

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

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.

Parameters

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

Returns: void

void Display_doClose ( Display_Handle handle )

Closes selected Display implementations.

Returns: void

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.

Detailed Description

Driver include

Operation

Opening the driver

Outputting data

Implementation

Instrumentation

Calling Context

use this interface in other contexts than Main and Task.

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation