Display.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) 2016-2020, Texas Instruments Incorporated
3  * All rights reserved.
4  *
5  * Redistribution and use in source and binary forms, with or without
6  * modification, are permitted provided that the following conditions
7  * are met:
8  *
9  * * Redistributions of source code must retain the above copyright
10  * notice, this list of conditions and the following disclaimer.
11  *
12  * * Redistributions in binary form must reproduce the above copyright
13  * notice, this list of conditions and the following disclaimer in the
14  * documentation and/or other materials provided with the distribution.
15  *
16  * * Neither the name of Texas Instruments Incorporated nor the names of
17  * its contributors may be used to endorse or promote products derived
18  * from this software without specific prior written permission.
19  *
20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
22  * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
23  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
24  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
26  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
27  * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
28  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
29  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
30  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31  */
32 
33 /*!****************************************************************************
34  * @file Display.h
35  * @brief Generic interface for text output
36  *
37  * @anchor ti_drivers_Display_Overview
38  * # Overview
39  *
40  * The Display middleware-driver in TI-RTOS is designed to abstract operations
41  * and considerations specific to given output method.
42  *
43  * The APIs in this driver serve as an interface to a typical TI-RTOS
44  * application. The specific peripheral implementations are responsible to
45  * create all the SYS/BIOS specific primitives to allow for thread-safe
46  * operation. The application initializes the Display driver by calling
47  * Display_init() and is then ready to open a Display by calling
48  * Display_open() and passing in a Display parameters data structure.
49  *
50  * @note Display APIs can only be called from task context.
51  *
52  * @note All Display statements will be removed and no display operations will
53  * take place if the symbol *Display_DISABLE_ALL* is defined globally,
54  * or before *Display.h* is included.
55  *
56  * <hr>
57  * @anchor ti_drivers_Display_Usage
58  * # Usage
59  *
60  * This documentation provides a basic @ref ti_drivers_Display_Synopsis
61  * "usage summary" and a set of @ref ti_drivers_Display_Examples "examples"
62  * in the form of commented code fragments. Detailed descriptions of the
63  * APIs are provided in subsequent sections.
64  *
65  * @anchor ti_drivers_Display_Synopsis
66  * ## Synopsis
67  * @anchor ti_drivers_Display_Synopsis_Code
68  * @code
69  * // Import Display Driver definitions
70  * #include <ti/display/Display.h>
71  *
72  * // Initialize optional Display parameters
73  * Display_Handle handle;
74  * Display_Params params;
75  * Display_Params_init(&params);
76  *
77  * // Open Display implementation
78  * handle = Display_open(Display_Type_HOST, &params);
79 
80  *
81  * // Output to Display
82  * Display_printf(handle, 0, 0, "Hello World");
83  *
84  * Display_close(handle);
85  * @endcode
86  *
87  * <hr>
88  * @anchor ti_drivers_Display_Examples
89  * # Examples
90  *
91  * @li @ref ti_drivers_Display_Examples_open "Opening a Display instance"
92  * @li @ref ti_drivers_Display_Examples_float "Floating point support"
93  * @li @ref ti_drivers_Display_Examples_host "Configuring Host Display"
94  * @li @ref ti_drivers_Display_Examples_lcd "Configuring a graphical Display"
95  *
96  * @anchor ti_drivers_Display_Examples_open
97  * ## Opening a Display instance
98  *
99  * @code
100  * Display_Handle handle;
101  * Display_Params params;
102  *
103  * Display_Params_init(&params);
104  * display = Display_open(Display_Type_HOST, &params);
105  * if (display == NULL) {
106  * // Display_open() failed
107  * while(1);
108  * }
109  * @endcode
110  *
111  * @anchor ti_drivers_Display_Examples_float
112  * ## Adding floating point
113  *
114  * @code
115  * // Note that for floating point support, the .cfg file must have a line like
116  * // System.extendedFormats = "%$L%$S%$F%f"; // Add '%f' support
117  * Display_printf(handle, 3, 0, "Pi is %f", 3.1415);
118  * Display_close(handle);
119  * @endcode
120  *
121  * @anchor ti_drivers_Display_Examples_host
122  * ## Configuring the HOST Display
123  *
124  * @code
125  * #include <ti/display/Display.h>
126  * #include <ti/display/DisplayHost.h>
127  *
128  * #define MAXPRINTLEN 1024
129  *
130  * DisplayHost_Object displayHostObject;
131  * static char displayBuf[MAXPRINTLEN];
132  *
133  * const DisplayHost_HWAttrs displayHostHWAttrs = {
134  * .strBuf = displayBuf,
135  * .strBufLen = MAXPRINTLEN
136  * };
137  *
138  * const Display_Config Display_config[] = {
139  * {
140  * .fxnTablePtr = &DisplayHost_fxnTable,
141  * .object = &displayHostObject,
142  * .hwAttrs = &displayHostHWAttrs
143  * }
144  * };
145  *
146  * const uint8_t Display_count = sizeof(Display_config) / sizeof(Display_Config);
147  * @endcode
148  *
149  * @anchor ti_drivers_Display_Examples_lcd
150  * ## Configuring graphical display
151  *
152  * @code
153  * Display_Handle handle;
154  * Display_Params params;
155  *
156  * Display_Params_init(&params);
157  * handle = Display_open(Display_Type_LCD, &params);
158  * if (NULL == handle)
159  * handle = Display_open(Display_Type_UART, &params);
160  * @endcode
161  *
162  *
163  *## Opening the driver #
164  *
165  * Because the Display driver serves as an abstraction, it is possible to
166  * specify the *type* of Display implementations that should be opened, as
167  * well as alternatively the config-array index value like with other TI-RTOS
168  * drivers.
169  *
170  * Optionally, if no particular parameters are desired, the pointer to params
171  * can be replaced with NULL.
172  *
173  * @code
174  * Display_Handle handle;
175  * Display_Params params;
176  *
177  * Display_Params_init(&params);
178  * handle = Display_open(someConfigIndexValue, &params);
179  * //Display_open(Display_Type_HOST, &params);
180  * //Display_open(Display_Type_ANY, &params);
181  * //Display_open(Display_Type_UART, NULL);
182  * //Display_open(Display_Type_UART | Display_Type_LCD, &params);
183  * @endcode
184  *
185  * ## Outputting data #
186  *
187  * After the Display interface is opened, the user can call any of the APIs
188  * @code
189  * Display_clear(handle);
190  * Display_clearLines(handle, 0, 4);
191  * Display_printf(handle, 1, 0, "How are you %s?", yourName);
192  *
193  * // Note that for floating point support, the .cfg file must have a line like
194  * // System.extendedFormats = "%$L%$S%$F%f"; // Add '%f' support
195  * Display_printf(handle, 3, 0, "Pi is %f", 3.1415);
196  * Display_close(handle);
197  * @endcode
198  *
199  * @note Display_printX can only be called from Task context, unless
200  * the only opened interfaces specifically allow calls from any context.
201  *
202  *
203  * For example, Display_open is called, and Display.c iterates over the
204  * available Display_Config's in the external Display_config array.
205  * For each *config*, config->fxns->open is called, and &config is provided for
206  * context.
207  *
208  *
209  * # Instrumentation #
210  *
211  * The Display interface produces log statements if instrumentation is
212  * enabled.
213  *
214  * Diagnostics Mask | Log details |
215  * ---------------- | ----------- |
216  * Diags_USER1 | basic operations performed |
217  * Diags_USER2 | detailed operations performed |
218  *
219  * # Calling Context #
220  *
221  * For most implementations of this interface it is only possible to call the
222  * APIs from Task or Main context because the implementations may rely on
223  * Semaphores or other RTOS services that do not work correctly or do not work
224  * at all in Hwi / Swi context.
225  *
226  * Unless you know that the implementation is safe to use in Hwi/Swi, do not
227  * use this interface in other contexts than Main and Task.
228  *
229  * <hr>
230  * @anchor ti_drivers_Display_Configuration
231  * # Configuration
232  *
233  * Refer to the @ref driver_configuration "Driver's Configuration" section
234  * for driver configuration information.
235  * <hr>
236  *******************************************************************************
237  */
238 #ifndef ti_display_Display__include
239 #define ti_display_Display__include
240 
241 #include <stdint.h>
242 #include <stdarg.h>
243 
244 #ifdef __cplusplus
245 extern "C" {
246 #endif
247 
248 /* -----------------------------------------------------------------------------
249  * Constants
250  * ------------------------------------------------------------------------------
251  */
260 #define Display_Type_ANY 0xFFFFFFFF
261 #define Display_Type_INVALID 0x00000000
262 #define Display_Type_LCD 0x80000000
263 #define Display_Type_UART 0x40000000
264 #define Display_Type_LOG 0x20000000
265 #define Display_Type_ITM 0x10000000
266 #define Display_Type_HOST 0x08000000
267 #define Display_Type_ANSI 0x04000000
268 #define Display_Type_GRLIB 0x00100000
272 #define Display_MAXINDEX 15
273 
291 #define DISPLAY_CMD_RESERVED 32
292 
305 #define DISPLAY_STATUS_RESERVED -32
306 
320 #define DISPLAY_STATUS_SUCCESS 0
321 
328 #define DISPLAY_STATUS_ERROR -1
329 
337 #define DISPLAY_STATUS_UNDEFINEDCMD -2
338 
358 #define DISPLAY_CMD_TRANSPORT_CLOSE 0
359 
368 #define DISPLAY_CMD_TRANSPORT_OPEN 1
369 
373 /* -----------------------------------------------------------------------------
374  * Macros
375  * ------------------------------------------------------------------------------
376  */
377 #define Display_clearLine(handle, n) Display_clearLines(handle, n, 0)
378 #define Display_isIndex(i) (i <= Display_MAXINDEX)
379 #define Display_isMetaType(i) (i > Display_MAXINDEX)
380 
381 #if !defined(Display_DISABLE_ALL) || (!Display_DISABLE_ALL)
382 
384 # define Display_init() \
385  Display_doInit()
386 
388 # define Display_open(id, params) \
389  Display_doOpen(id, params)
390 
392 # define Display_Params_init(params) \
393  Display_doParamsInit(params)
394 
396 # define Display_clear(handle) \
397  Display_doClear(handle)
398 
400 # define Display_clearLines(handle, fromLine, toLine) \
401  Display_doClearLines(handle, fromLine, toLine)
402 
404 # define Display_printf Display_doPrintf
405 
407 # define Display_print0(handle, line, col, fmt) \
408  Display_printf(handle, line, col, fmt)
409 
411 # define Display_print1(handle, line, col, fmt, a0) \
412  Display_printf(handle, line, col, fmt, a0)
413 
415 # define Display_print2(handle, line, col, fmt, a0, a1) \
416  Display_printf(handle, line, col, fmt, a0, a1)
417 
419 # define Display_print3(handle, line, col, fmt, a0, a1, a2) \
420  Display_printf(handle, line, col, fmt, a0, a1, a2)
421 
423 # define Display_print4(handle, line, col, fmt, a0, a1, a2, a3) \
424  Display_printf(handle, line, col, fmt, a0, a1, a2, a3)
425 
427 # define Display_print5(handle, line, col, fmt, a0, a1, a2, a3, a4) \
428  Display_printf(handle, line, col, fmt, a0, a1, a2, a3, a4)
429 
431 # define Display_getType(handle) \
432  Display_doGetType(handle)
433 
435 # define Display_control(handle, cmd, arg) \
436  Display_doControl(handle, cmd, arg)
437 
439 # define Display_close(handle) \
440  Display_doClose(handle)
441 #else
442 # define Display_init()
443 # define Display_open(id, params) NULL
444 # define Display_Params_init(params)
445 # define Display_clear(handle)
446 # define Display_clearLines(handle, fromLine, toLine)
447 # define Display_printf(handle, line, col, fmt, ...)
448 # define Display_print0(handle, line, col, fmt)
449 # define Display_print1(handle, line, col, fmt, a0)
450 # define Display_print2(handle, line, col, fmt, a0, a1)
451 # define Display_print3(handle, line, col, fmt, a0, a1, a2)
452 # define Display_print4(handle, line, col, fmt, a0, a1, a2, a3)
453 # define Display_print5(handle, line, col, fmt, a0, a1, a2, a3, a4)
454 # define Display_getType(handle) Display_Type_INVALID
455 # define Display_control(handle, cmd, arg) NULL
456 # define Display_close(handle)
457 #endif
458 
459 /* -----------------------------------------------------------------------------
460  * Typedefs
461  * ------------------------------------------------------------------------------
462  */
467 
472 typedef void (*Display_initFxn)(Display_Handle handle);
473 
478 {
484 
493 typedef struct Display_Params
494 {
495  Display_LineClearMode lineClearMode; /* Default clear entire line */
497 
502 typedef Display_Handle (*Display_openFxn)(Display_Handle handle,
503  Display_Params *params);
508 typedef void (*Display_clearFxn)(Display_Handle handle);
509 
514 typedef void (*Display_clearLinesFxn)(Display_Handle handle,
515  uint8_t fromLine,
516  uint8_t toLine);
517 
522 typedef void (*Display_vprintfFxn)(Display_Handle handle,
523  uint8_t line,
524  uint8_t column,
525  const char *fmt,
526  va_list va);
527 
533 
538 typedef int (*Display_controlFxn)(Display_Handle handle,
539  unsigned int cmd,
540  void *arg);
545 typedef unsigned int (*Display_getTypeFxn)(void);
546 
552 typedef struct Display_FxnTable
553 {
563 
575 typedef struct Display_Config
576 {
579 
581  void *object;
582 
584  void const *hwAttrs;
586 
587 
588 /* -----------------------------------------------------------------------------
589  * Functions
590  * ------------------------------------------------------------------------------
591  */
622 Display_Handle Display_doOpen(uint32_t id, Display_Params *params);
623 
632 
640 void Display_doClear(Display_Handle handle);
641 
651 void Display_doClearLines(Display_Handle handle, uint8_t fromLine, uint8_t toLine);
652 
664 void Display_doPrintf(Display_Handle handle, uint8_t line, uint8_t column,
665  const char *fmt, ...);
666 
672 void Display_doClose(Display_Handle handle);
673 
680 uint32_t Display_doGetType(Display_Handle handle);
681 
717 void Display_doControl(Display_Handle handle, unsigned int cmd, void *arg);
718 
726 void Display_doInit(void);
727 
728 #ifdef __cplusplus
729 }
730 #endif
731 
732 #endif //ti_display_Display__include
void Display_doClose(Display_Handle handle)
Closes selected Display implementations.
Display_vprintfFxn vprintfFxn
Definition: Display.h:558
struct Display_Config * Display_Handle
A handle for specific Display implementations.
Definition: Display.h:466
struct Display_Config Display_Config
Display Global configuration.
void(* Display_clearLinesFxn)(Display_Handle handle, uint8_t fromLine, uint8_t toLine)
A function pointer to a specific implementation of Display_clearLines().
Definition: Display.h:514
void Display_doParamsInit(Display_Params *params)
Initializes parameter structure with default parameters.
void * object
Definition: Display.h:581
void Display_doInit(void)
Function to initializes the Display driver.
Display_Handle(* Display_openFxn)(Display_Handle handle, Display_Params *params)
A function pointer to a specific implementation of Display_open().
Definition: Display.h:502
unsigned int(* Display_getTypeFxn)(void)
A function pointer to a specific implementation of Display_getType().
Definition: Display.h:545
void Display_doClear(Display_Handle handle)
Calls the clear fxn of all opened Display implementations.
void(* Display_vprintfFxn)(Display_Handle handle, uint8_t line, uint8_t column, const char *fmt, va_list va)
A function pointer to a specific implementation of Display_vprintf().
Definition: Display.h:522
Display Parameters.
Definition: Display.h:493
void const * hwAttrs
Definition: Display.h:584
uint32_t Display_doGetType(Display_Handle handle)
Gets the type of display for the handle.
void Display_doPrintf(Display_Handle handle, uint8_t line, uint8_t column, const char *fmt,...)
Calls the output function of all opened Display implementations.
Definition: Display.h:479
void Display_doControl(Display_Handle handle, unsigned int cmd, void *arg)
Function performs implementation specific features on a given Display_Handle.
Display_clearFxn clearFxn
Definition: Display.h:556
Display_controlFxn controlFxn
Definition: Display.h:560
void(* Display_clearFxn)(Display_Handle handle)
A function pointer to a specific implementation of Display_clear().
Definition: Display.h:508
Display_initFxn initFxn
Definition: Display.h:554
Definition: Display.h:481
The definition of a Display function table that contains the required set of functions to control a s...
Definition: Display.h:552
Display_openFxn openFxn
Definition: Display.h:555
void(* Display_initFxn)(Display_Handle handle)
A function pointer to a specific implementation of Display_initFxn().
Definition: Display.h:472
Definition: Display.h:480
Display_getTypeFxn getTypeFxn
Definition: Display.h:561
void Display_doClearLines(Display_Handle handle, uint8_t fromLine, uint8_t toLine)
Calls the clearLines fxn of all opened Display implementations.
struct Display_FxnTable Display_FxnTable
The definition of a Display function table that contains the required set of functions to control a s...
Display_LineClearMode lineClearMode
Definition: Display.h:495
Display_Handle Display_doOpen(uint32_t id, Display_Params *params)
Initialize all the selected Display implementations.
Display Global configuration.
Definition: Display.h:575
struct Display_Params Display_Params
Display Parameters.
Display_FxnTable const * fxnTablePtr
Definition: Display.h:578
int(* Display_controlFxn)(Display_Handle handle, unsigned int cmd, void *arg)
A function pointer to a driver specific implementation of Display_control().
Definition: Display.h:538
Display_closeFxn closeFxn
Definition: Display.h:559
Display_LineClearMode
How to treat existing elements on a line when writing text.
Definition: Display.h:477
Definition: Display.h:482
Display_clearLinesFxn clearLinesFxn
Definition: Display.h:557
void(* Display_closeFxn)(Display_Handle)
A function pointer to a specific implementation of Display_close().
Definition: Display.h:532
© Copyright 1995-2020, Texas Instruments Incorporated. All rights reserved.
Trademarks | Privacy policy | Terms of use | Terms of sale