Display.h

Go to the documentation of this file.

/*
 * Copyright (c) 2016-2019, Texas Instruments Incorporated
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * *  Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 * *  Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 *
 * *  Neither the name of Texas Instruments Incorporated nor the names of
 *    its contributors may be used to endorse or promote products derived
 *    from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

/*!****************************************************************************
 *  @file       Display.h
 *  @brief      Generic interface for text output
 *
 *  @anchor ti_drivers_Display_Overview
 *  # Overview
 *
 *  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.
 *
 *  @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.
 *
 *  <hr>
 *  @anchor ti_drivers_Display_Usage
 *  # Usage
 *
 *  This documentation provides a basic @ref ti_drivers_Display_Synopsis
 *  "usage summary" and a set of @ref ti_drivers_Display_Examples "examples"
 *  in the form of commented code fragments. Detailed descriptions of the
 *  APIs are provided in subsequent sections.
 *
 *  @anchor ti_drivers_Display_Synopsis
 *  ## Synopsis
 *  @anchor ti_drivers_Display_Synopsis_Code
 *  @code
 *  // Import Display Driver definitions
 *  #include <ti/display/Display.h>
 *  
 *  // Initialize optional Display parameters
 *  Display_Handle    handle;
 *  Display_Params    params;
 *  Display_Params_init(&params);
 *  
 *  // Open Display implementation
 *  handle = Display_open(Display_Type_HOST, &params);

 *  
 *  // Output to Display
 *  Display_printf(handle, 0, 0, "Hello World");
 *  
 *  Display_close(handle);
 *  @endcode
 *  
 *  <hr>
 *  @anchor ti_drivers_Display_Examples
 *  # Examples
 *  
 *  @li @ref ti_drivers_Display_Examples_open "Opening a Display instance"
 *  @li @ref ti_drivers_Display_Examples_float "Floating point support"
 *  @li @ref ti_drivers_Display_Examples_host "Configuring Host Display"
 *  @li @ref ti_drivers_Display_Examples_lcd "Configuring a graphical Display"
 * 
 *  @anchor ti_drivers_Display_Examples_open
 *  ## Opening a Display instance
 *  
 *  @code
 *  Display_Handle    handle;
 *  Display_Params    params;
 *  
 *  Display_Params_init(&params);
 *  display = Display_open(Display_Type_HOST, &params);
 *  if (display == NULL) {
 *      // Display_open() failed
 *      while(1);
 *  }
 *  @endcode
 *  
 *  @anchor ti_drivers_Display_Examples_float
 *  ## Adding floating point
 *  
 *  @code
 *  // 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);
 *  @endcode
 *  
 *  @anchor ti_drivers_Display_Examples_host
 *  ## Configuring the HOST Display
 *  
 *  @code
 *  #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);
 *  @endcode
 *  
 *  @anchor ti_drivers_Display_Examples_lcd
 *  ## Configuring graphical display
 *  
 *  @code
 *  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);
 *  @endcode
 *  
 *  
 *## 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.
 *
 *  @code
 *  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);
 *  @endcode
 *
 *  ## Outputting data #
 *
 *  After the Display interface is opened, the user can call any of the APIs
 *  @code
 *  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);
 *  @endcode
 *
 *  @note Display_printX can only be called from Task context, unless
 *        the only opened interfaces specifically allow calls from any context.
 *
 *
 *  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.
 *
  *  <hr>
 *  @anchor ti_drivers_Display_Configuration
 *  # Configuration
 *
 *  Refer to the @ref driver_configuration "Driver's Configuration" section
 *  for driver configuration information.
 *  <hr>
 *******************************************************************************
 */
#ifndef ti_display_Display__include
#define ti_display_Display__include

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

#ifdef __cplusplus
extern "C" {
#endif

/* -----------------------------------------------------------------------------
 *                                          Constants
 * ------------------------------------------------------------------------------
 */
#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

#define DISPLAY_STATUS_ERROR          -1

#define DISPLAY_STATUS_UNDEFINEDCMD   -2

#define DISPLAY_CMD_TRANSPORT_CLOSE  0

#define DISPLAY_CMD_TRANSPORT_OPEN   1

/* -----------------------------------------------------------------------------
 *                                          Macros
 * ------------------------------------------------------------------------------
 */
#define Display_clearLine(handle, n)    Display_clearLines(handle, n, 0)
#define Display_isIndex(i)              (i <= Display_MAXINDEX)
#define Display_isMetaType(i)           (i > Display_MAXINDEX)

#if !defined(Display_DISABLE_ALL) || (!Display_DISABLE_ALL)

#  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)
#else
#  define Display_init()
#  define Display_open(id, params)    NULL
#  define Display_Params_init(params)
#  define Display_clear(handle)
#  define Display_clearLines(handle, fromLine, toLine)
#  define Display_printf(handle, line, col, fmt, ...)
#  define Display_print0(handle, line, col, fmt)
#  define Display_print1(handle, line, col, fmt, a0)
#  define Display_print2(handle, line, col, fmt, a0, a1)
#  define Display_print3(handle, line, col, fmt, a0, a1, a2)
#  define Display_print4(handle, line, col, fmt, a0, a1, a2, a3)
#  define Display_print5(handle, line, col, fmt, a0, a1, a2, a3, a4)
#  define Display_getType(handle) Display_Type_INVALID
#  define Display_control(handle, cmd, arg)  NULL
#  define Display_close(handle)
#endif

/* -----------------------------------------------------------------------------
 *                                          Typedefs
 * ------------------------------------------------------------------------------
 */
typedef struct Display_Config * Display_Handle;

typedef void (*Display_initFxn)(Display_Handle handle);

typedef enum Display_LineClearMode
{
    DISPLAY_CLEAR_NONE = 0,   
    DISPLAY_CLEAR_LEFT,       
    DISPLAY_CLEAR_RIGHT,      
    DISPLAY_CLEAR_BOTH        
} Display_LineClearMode;

typedef struct Display_Params
{
    Display_LineClearMode lineClearMode;  /* Default clear entire line */
} Display_Params;

typedef Display_Handle (*Display_openFxn)(Display_Handle handle,
                                          Display_Params *params);
typedef void (*Display_clearFxn)(Display_Handle handle);

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

typedef void (*Display_vprintfFxn)(Display_Handle handle,
                                   uint8_t line,
                                   uint8_t column,
                                   char *fmt,
                                   va_list va);

typedef void (*Display_closeFxn)(Display_Handle);

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

typedef struct Display_FxnTable
{
    Display_initFxn       initFxn;
    Display_openFxn       openFxn;
    Display_clearFxn      clearFxn;
    Display_clearLinesFxn clearLinesFxn;
    Display_vprintfFxn    vprintfFxn;
    Display_closeFxn      closeFxn;
    Display_controlFxn    controlFxn;
    Display_getTypeFxn    getTypeFxn;
} Display_FxnTable;

typedef struct Display_Config
{
    Display_FxnTable const *fxnTablePtr;

    void                   *object;

    void const             *hwAttrs;
} Display_Config;


/* -----------------------------------------------------------------------------
 *                                          Functions
 * ------------------------------------------------------------------------------
 */
Display_Handle  Display_doOpen(uint32_t id, Display_Params *params);

void Display_doParamsInit(Display_Params *params);

void  Display_doClear(Display_Handle handle);

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

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

void  Display_doClose(Display_Handle handle);

uint32_t  Display_doGetType(Display_Handle handle);

void  Display_doControl(Display_Handle handle, unsigned int cmd, void *arg);

void Display_doInit(void);

#ifdef __cplusplus
}
#endif

#endif //ti_display_Display__include