Data Structures | Macros | Typedefs | Enumerations | Functions
Display.h File Reference

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.

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.

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:

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.

#define MAXPRINTLEN 1024
DisplayHost_Object displayHostObject;
static char displayBuf[MAXPRINTLEN];
const DisplayHost_HWAttrs displayHostHWAttrs = {
.strBuf = displayBuf,
.strBufLen = MAXPRINTLEN
};
const Display_Config Display_config[] = {
{
.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_ConfigDisplay_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,
 
)    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

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

§ 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

The definition of a Display function table that contains the required set of functions to control a specific Display driver implementation.

§ 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

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
handleA Display handle returned from Display()
cmdDisplay.h or Display*.h commands.
argAn 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.
© Copyright 1995-2018, Texas Instruments Incorporated. All rights reserved.
Trademarks | Privacy policy | Terms of use | Terms of sale