git.sur5r.net Git - freertos/blob - FreeRTOS/Demo/CORTEX_MPU_M33F_NXP_LPC55S69_MCUXpresso/NXP_Code/utilities/fsl_debug_console.h

   1 /*\r
   2  * Copyright (c) 2013 - 2015, Freescale Semiconductor, Inc.\r
   3  * Copyright 2016-2018 NXP\r
   4  * All rights reserved.\r
   5  *\r
   6  * SPDX-License-Identifier: BSD-3-Clause\r
   7  *\r
   8  * Debug console shall provide input and output functions to scan and print formatted data.\r
   9  * o Support a format specifier for PRINTF follows this prototype "%[flags][width][.precision][length]specifier"\r
  10  *   - [flags] :'-', '+', '#', ' ', '0'\r
  11  *   - [width]:  number (0,1...)\r
  12  *   - [.precision]: number (0,1...)\r
  13  *   - [length]: do not support\r
  14  *   - [specifier]: 'd', 'i', 'f', 'F', 'x', 'X', 'o', 'p', 'u', 'c', 's', 'n'\r
  15  * o Support a format specifier for SCANF follows this prototype " %[*][width][length]specifier"\r
  16  *   - [*]: is supported.\r
  17  *   - [width]: number (0,1...)\r
  18  *   - [length]: 'h', 'hh', 'l','ll','L'. ignore ('j','z','t')\r
  19  *   - [specifier]: 'd', 'i', 'u', 'f', 'F', 'e', 'E', 'g', 'G', 'a', 'A', 'o', 'c', 's'\r
  20  */\r
  21 \r
  22 #ifndef _FSL_DEBUGCONSOLE_H_\r
  23 #define _FSL_DEBUGCONSOLE_H_\r
  24 \r
  25 #include "fsl_common.h"\r
  26 #include "serial_manager.h"\r
  27 \r
  28 /*!\r
  29  * @addtogroup debugconsole\r
  30  * @{\r
  31  */\r
  32 \r
  33 /*******************************************************************************\r
  34  * Definitions\r
  35  ******************************************************************************/\r
  36 \r
  37 extern serial_handle_t g_serialHandle; /*!< serial manager handle */\r
  38 \r
  39 /*! @brief Definition select redirect toolchain printf, scanf to uart or not. */\r
  40 #define DEBUGCONSOLE_REDIRECT_TO_TOOLCHAIN 0U /*!< Select toolchain printf and scanf. */\r
  41 #define DEBUGCONSOLE_REDIRECT_TO_SDK 1U       /*!< Select SDK version printf, scanf. */\r
  42 #define DEBUGCONSOLE_DISABLE 2U               /*!< Disable debugconsole function. */\r
  43 \r
  44 /*! @brief Definition to select sdk or toolchain printf, scanf. The macro only support\r
  45  * to be redefined in project setting.\r
  46  */\r
  47 #ifndef SDK_DEBUGCONSOLE\r
  48 #define SDK_DEBUGCONSOLE 1U\r
  49 #endif\r
  50 \r
  51 #if defined(SDK_DEBUGCONSOLE) && !(SDK_DEBUGCONSOLE)\r
  52 #include <stdio.h>\r
  53 #endif\r
  54 \r
  55 /*! @brief Definition to select redirect toolchain printf, scanf to uart or not.\r
  56  *\r
  57  *  if SDK_DEBUGCONSOLE defined to 0,it represents select toolchain printf, scanf.\r
  58  *  if SDK_DEBUGCONSOLE defined to 1,it represents select SDK version printf, scanf.\r
  59  *  if SDK_DEBUGCONSOLE defined to 2,it represents disable debugconsole function.\r
  60  */\r
  61 #if SDK_DEBUGCONSOLE == DEBUGCONSOLE_DISABLE /* Disable debug console */\r
  62 #define PRINTF\r
  63 #define SCANF\r
  64 #define PUTCHAR\r
  65 #define GETCHAR\r
  66 #elif SDK_DEBUGCONSOLE == DEBUGCONSOLE_REDIRECT_TO_SDK /* Select printf, scanf, putchar, getchar of SDK version. */\r
  67 #define PRINTF DbgConsole_Printf\r
  68 #define SCANF DbgConsole_Scanf\r
  69 #define PUTCHAR DbgConsole_Putchar\r
  70 #define GETCHAR DbgConsole_Getchar\r
  71 #elif SDK_DEBUGCONSOLE == DEBUGCONSOLE_REDIRECT_TO_TOOLCHAIN /* Select printf, scanf, putchar, getchar of toolchain. \ \\r
  72                                                               */\r
  73 #define PRINTF printf\r
  74 #define SCANF scanf\r
  75 #define PUTCHAR putchar\r
  76 #define GETCHAR getchar\r
  77 #endif /* SDK_DEBUGCONSOLE */\r
  78 \r
  79 /*******************************************************************************\r
  80  * Prototypes\r
  81  ******************************************************************************/\r
  82 \r
  83 #if defined(__cplusplus)\r
  84 extern "C" {\r
  85 #endif /* __cplusplus */\r
  86 \r
  87 /*! @name Initialization*/\r
  88 /* @{ */\r
  89 \r
  90 #if ((SDK_DEBUGCONSOLE == DEBUGCONSOLE_REDIRECT_TO_SDK) || defined(SDK_DEBUGCONSOLE_UART))\r
  91 /*!\r
  92  * @brief Initializes the peripheral used for debug messages.\r
  93  *\r
  94  * Call this function to enable debug log messages to be output via the specified peripheral\r
  95  * initialized by the serial manager module.\r
  96  * After this function has returned, stdout and stdin are connected to the selected peripheral.\r
  97  *\r
  98  * @param instance      The instance of the module.\r
  99  * @param baudRate      The desired baud rate in bits per second.\r
 100  * @param device        Low level device type for the debug console, can be one of the following.\r
 101  *                      @arg kSerialPort_Uart,\r
 102  *                      @arg kSerialPort_UsbCdc\r
 103  *                      @arg kSerialPort_UsbCdcVirtual.\r
 104  * @param clkSrcFreq    Frequency of peripheral source clock.\r
 105  *\r
 106  * @return              Indicates whether initialization was successful or not.\r
 107  * @retval kStatus_Success          Execution successfully\r
 108  */\r
 109 status_t DbgConsole_Init(uint8_t instance, uint32_t baudRate, serial_port_type_t device, uint32_t clkSrcFreq);\r
 110 \r
 111 /*!\r
 112  * @brief De-initializes the peripheral used for debug messages.\r
 113  *\r
 114  * Call this function to disable debug log messages to be output via the specified peripheral\r
 115  * initialized by the serial manager module.\r
 116  *\r
 117  * @return Indicates whether de-initialization was successful or not.\r
 118  */\r
 119 status_t DbgConsole_Deinit(void);\r
 120 #else\r
 121 /*!\r
 122  * Use an error to replace the DbgConsole_Init when SDK_DEBUGCONSOLE is not DEBUGCONSOLE_REDIRECT_TO_SDK and\r
 123  * SDK_DEBUGCONSOLE_UART is not defined.\r
 124  */\r
 125 static inline status_t DbgConsole_Init(uint8_t instance,\r
 126                                        uint32_t baudRate,\r
 127                                        serial_port_type_t device,\r
 128                                        uint32_t clkSrcFreq)\r
 129 {\r
 130     (void)instance;\r
 131     (void)baudRate;\r
 132     (void)device;\r
 133     (void)clkSrcFreq;\r
 134     return (status_t)kStatus_Fail;\r
 135 }\r
 136 /*!\r
 137  * Use an error to replace the DbgConsole_Deinit when SDK_DEBUGCONSOLE is not DEBUGCONSOLE_REDIRECT_TO_SDK and\r
 138  * SDK_DEBUGCONSOLE_UART is not defined.\r
 139  */\r
 140 static inline status_t DbgConsole_Deinit(void)\r
 141 {\r
 142     return (status_t)kStatus_Fail;\r
 143 }\r
 144 #endif /* ((SDK_DEBUGCONSOLE == DEBUGCONSOLE_REDIRECT_TO_SDK) || defined(SDK_DEBUGCONSOLE_UART)) */\r
 145 \r
 146 #if SDK_DEBUGCONSOLE\r
 147 /*!\r
 148  * @brief Writes formatted output to the standard output stream.\r
 149  *\r
 150  * Call this function to write a formatted output to the standard output stream.\r
 151  *\r
 152  * @param   formatString Format control string.\r
 153  * @return  Returns the number of characters printed or a negative value if an error occurs.\r
 154  */\r
 155 int DbgConsole_Printf(const char *formatString, ...);\r
 156 \r
 157 /*!\r
 158  * @brief Writes a character to stdout.\r
 159  *\r
 160  * Call this function to write a character to stdout.\r
 161  *\r
 162  * @param   ch Character to be written.\r
 163  * @return  Returns the character written.\r
 164  */\r
 165 int DbgConsole_Putchar(int ch);\r
 166 \r
 167 /*!\r
 168  * @brief Reads formatted data from the standard input stream.\r
 169  *\r
 170  * Call this function to read formatted data from the standard input stream.\r
 171  *\r
 172  * @note Due the limitation in the BM OSA environment (CPU is blocked in the function,\r
 173  * other tasks will not be scheduled), the function cannot be used when the\r
 174  * DEBUG_CONSOLE_TRANSFER_NON_BLOCKING is set in the BM OSA environment.\r
 175  * And an error is returned when the function called in this case. The suggestion\r
 176  * is that polling the non-blocking function DbgConsole_TryGetchar to get the input char.\r
 177  *\r
 178  * @param   formatString Format control string.\r
 179  * @return  Returns the number of fields successfully converted and assigned.\r
 180  */\r
 181 int DbgConsole_Scanf(char *formatString, ...);\r
 182 \r
 183 /*!\r
 184  * @brief Reads a character from standard input.\r
 185  *\r
 186  * Call this function to read a character from standard input.\r
 187  *\r
 188  * @note Due the limitation in the BM OSA environment (CPU is blocked in the function,\r
 189  * other tasks will not be scheduled), the function cannot be used when the\r
 190  * DEBUG_CONSOLE_TRANSFER_NON_BLOCKING is set in the BM OSA environment.\r
 191  * And an error is returned when the function called in this case. The suggestion\r
 192  * is that polling the non-blocking function DbgConsole_TryGetchar to get the input char.\r
 193  *\r
 194  * @return Returns the character read.\r
 195  */\r
 196 int DbgConsole_Getchar(void);\r
 197 \r
 198 /*!\r
 199  * @brief Writes formatted output to the standard output stream with the blocking mode.\r
 200  *\r
 201  * Call this function to write a formatted output to the standard output stream with the blocking mode.\r
 202  * The function will send data with blocking mode no matter the DEBUG_CONSOLE_TRANSFER_NON_BLOCKING set\r
 203  * or not.\r
 204  * The function could be used in system ISR mode with DEBUG_CONSOLE_TRANSFER_NON_BLOCKING set.\r
 205  *\r
 206  * @param   formatString Format control string.\r
 207  * @return  Returns the number of characters printed or a negative value if an error occurs.\r
 208  */\r
 209 int DbgConsole_BlockingPrintf(const char *formatString, ...);\r
 210 \r
 211 /*!\r
 212  * @brief Debug console flush.\r
 213  *\r
 214  * Call this function to wait the tx buffer empty.\r
 215  * If interrupt transfer is using, make sure the global IRQ is enable before call this function\r
 216  * This function should be called when\r
 217  * 1, before enter power down mode\r
 218  * 2, log is required to print to terminal immediately\r
 219  * @return Indicates whether wait idle was successful or not.\r
 220  */\r
 221 status_t DbgConsole_Flush(void);\r
 222 \r
 223 #ifdef DEBUG_CONSOLE_TRANSFER_NON_BLOCKING\r
 224 /*!\r
 225  * @brief Debug console try to get char\r
 226  * This function provides a API which will not block current task, if character is\r
 227  * available return it, otherwise return fail.\r
 228  * @param ch the address of char to receive\r
 229  * @return Indicates get char was successful or not.\r
 230  */\r
 231 status_t DbgConsole_TryGetchar(char *ch);\r
 232 #endif\r
 233 \r
 234 #endif /* SDK_DEBUGCONSOLE */\r
 235 \r
 236 /*! @} */\r
 237 \r
 238 #if defined(__cplusplus)\r
 239 }\r
 240 #endif /* __cplusplus */\r
 241 \r
 242 /*! @} */\r
 243 \r
 244 #endif /* _FSL_DEBUGCONSOLE_H_ */\r