git.sur5r.net Git - freertos/blob - FreeRTOS/Demo/CORTEX_MPU_M33F_NXP_LPC55S69_MCUXpresso/NXP_Code/component/serial_manager/serial_manager.h

   1 /*\r
   2  * Copyright 2018 NXP\r
   3  * All rights reserved.\r
   4  *\r
   5  *\r
   6  * SPDX-License-Identifier: BSD-3-Clause\r
   7  */\r
   8 \r
   9 #ifndef __SERIAL_MANAGER_H__\r
  10 #define __SERIAL_MANAGER_H__\r
  11 \r
  12 /*!\r
  13  * @addtogroup serialmanager\r
  14  * @{\r
  15  */\r
  16 \r
  17 /*******************************************************************************\r
  18  * Definitions\r
  19  ******************************************************************************/\r
  20 #ifdef DEBUG_CONSOLE_TRANSFER_NON_BLOCKING\r
  21 /*! @brief Enable or disable serial manager non-blocking mode (1 - enable, 0 - disable) */\r
  22 #define SERIAL_MANAGER_NON_BLOCKING_MODE (1U)\r
  23 #else\r
  24 #ifndef SERIAL_MANAGER_NON_BLOCKING_MODE\r
  25 #define SERIAL_MANAGER_NON_BLOCKING_MODE (0U)\r
  26 #endif\r
  27 #endif\r
  28 \r
  29 /*! @brief Enable or disable uart port (1 - enable, 0 - disable) */\r
  30 #ifndef SERIAL_PORT_TYPE_UART\r
  31 #define SERIAL_PORT_TYPE_UART (0U)\r
  32 #endif\r
  33 \r
  34 /*! @brief Enable or disable USB CDC port (1 - enable, 0 - disable) */\r
  35 #ifndef SERIAL_PORT_TYPE_USBCDC\r
  36 #define SERIAL_PORT_TYPE_USBCDC (0U)\r
  37 #endif\r
  38 \r
  39 /*! @brief Enable or disable SWO port (1 - enable, 0 - disable) */\r
  40 #ifndef SERIAL_PORT_TYPE_SWO\r
  41 #define SERIAL_PORT_TYPE_SWO (0U)\r
  42 #endif\r
  43 \r
  44 /*! @brief Enable or disable USB CDC virtual port (1 - enable, 0 - disable) */\r
  45 #ifndef SERIAL_PORT_TYPE_USBCDC_VIRTUAL\r
  46 #define SERIAL_PORT_TYPE_USBCDC_VIRTUAL (0U)\r
  47 #endif\r
  48 \r
  49 /*! @brief Set serial manager write handle size */\r
  50 #if (defined(SERIAL_MANAGER_NON_BLOCKING_MODE) && (SERIAL_MANAGER_NON_BLOCKING_MODE > 0U))\r
  51 #define SERIAL_MANAGER_WRITE_HANDLE_SIZE (44U)\r
  52 #define SERIAL_MANAGER_READ_HANDLE_SIZE (44U)\r
  53 #else\r
  54 #define SERIAL_MANAGER_WRITE_HANDLE_SIZE (4U)\r
  55 #define SERIAL_MANAGER_READ_HANDLE_SIZE (4U)\r
  56 #endif\r
  57 \r
  58 #if (defined(SERIAL_PORT_TYPE_UART) && (SERIAL_PORT_TYPE_UART > 0U))\r
  59 #include "serial_port_uart.h"\r
  60 #endif\r
  61 \r
  62 #if (defined(SERIAL_PORT_TYPE_USBCDC) && (SERIAL_PORT_TYPE_USBCDC > 0U))\r
  63 \r
  64 #if !(defined(SERIAL_MANAGER_NON_BLOCKING_MODE) && (SERIAL_MANAGER_NON_BLOCKING_MODE > 0U))\r
  65 #error The serial manager blocking mode cannot be supported for USB CDC.\r
  66 #endif\r
  67 \r
  68 #include "serial_port_usb.h"\r
  69 #endif\r
  70 \r
  71 #if (defined(SERIAL_PORT_TYPE_SWO) && (SERIAL_PORT_TYPE_SWO > 0U))\r
  72 #include "serial_port_swo.h"\r
  73 #endif\r
  74 \r
  75 #if (defined(SERIAL_PORT_TYPE_USBCDC_VIRTUAL) && (SERIAL_PORT_TYPE_USBCDC_VIRTUAL > 0U))\r
  76 \r
  77 #if !(defined(SERIAL_MANAGER_NON_BLOCKING_MODE) && (SERIAL_MANAGER_NON_BLOCKING_MODE > 0U))\r
  78 #error The serial manager blocking mode cannot be supported for USB CDC.\r
  79 #endif\r
  80 \r
  81 #include "serial_port_usb_virtual.h"\r
  82 #endif\r
  83 \r
  84 #define SERIAL_MANAGER_HANDLE_SIZE_TEMP 0U\r
  85 #if (defined(SERIAL_PORT_TYPE_UART) && (SERIAL_PORT_TYPE_UART > 0U))\r
  86 \r
  87 #if (SERIAL_PORT_UART_HANDLE_SIZE > SERIAL_MANAGER_HANDLE_SIZE_TEMP)\r
  88 #undef SERIAL_MANAGER_HANDLE_SIZE_TEMP\r
  89 #define SERIAL_MANAGER_HANDLE_SIZE_TEMP SERIAL_PORT_UART_HANDLE_SIZE\r
  90 #endif\r
  91 \r
  92 #endif\r
  93 \r
  94 #if (defined(SERIAL_PORT_TYPE_USBCDC) && (SERIAL_PORT_TYPE_USBCDC > 0U))\r
  95 \r
  96 #if (SERIAL_PORT_USB_CDC_HANDLE_SIZE > SERIAL_MANAGER_HANDLE_SIZE_TEMP)\r
  97 #undef SERIAL_MANAGER_HANDLE_SIZE_TEMP\r
  98 #define SERIAL_MANAGER_HANDLE_SIZE_TEMP SERIAL_PORT_USB_CDC_HANDLE_SIZE\r
  99 #endif\r
 100 \r
 101 #endif\r
 102 \r
 103 #if (defined(SERIAL_PORT_TYPE_SWO) && (SERIAL_PORT_TYPE_SWO > 0U))\r
 104 \r
 105 #if (SERIAL_PORT_SWO_HANDLE_SIZE > SERIAL_MANAGER_HANDLE_SIZE_TEMP)\r
 106 #undef SERIAL_MANAGER_HANDLE_SIZE_TEMP\r
 107 #define SERIAL_MANAGER_HANDLE_SIZE_TEMP SERIAL_PORT_SWO_HANDLE_SIZE\r
 108 #endif\r
 109 \r
 110 #endif\r
 111 \r
 112 #if (defined(SERIAL_PORT_TYPE_USBCDC_VIRTUAL) && (SERIAL_PORT_TYPE_USBCDC_VIRTUAL > 0U))\r
 113 \r
 114 #if (SERIAL_PORT_USB_VIRTUAL_HANDLE_SIZE > SERIAL_MANAGER_HANDLE_SIZE_TEMP)\r
 115 #undef SERIAL_MANAGER_HANDLE_SIZE_TEMP\r
 116 #define SERIAL_MANAGER_HANDLE_SIZE_TEMP SERIAL_PORT_USB_VIRTUAL_HANDLE_SIZE\r
 117 #endif\r
 118 \r
 119 #endif\r
 120 \r
 121 /*! @brief SERIAL_PORT_UART_HANDLE_SIZE/SERIAL_PORT_USB_CDC_HANDLE_SIZE + serial manager dedicated size */\r
 122 #if ((defined(SERIAL_MANAGER_HANDLE_SIZE_TEMP) && (SERIAL_MANAGER_HANDLE_SIZE_TEMP > 0U)))\r
 123 #else\r
 124 #error SERIAL_PORT_TYPE_UART, SERIAL_PORT_TYPE_USBCDC, SERIAL_PORT_TYPE_SWO and SERIAL_PORT_TYPE_USBCDC_VIRTUAL should not be cleared at same time.\r
 125 #endif\r
 126 \r
 127 #if (defined(SERIAL_MANAGER_NON_BLOCKING_MODE) && (SERIAL_MANAGER_NON_BLOCKING_MODE > 0U))\r
 128 #define SERIAL_MANAGER_HANDLE_SIZE (SERIAL_MANAGER_HANDLE_SIZE_TEMP + 120U)\r
 129 #else\r
 130 #define SERIAL_MANAGER_HANDLE_SIZE (SERIAL_MANAGER_HANDLE_SIZE_TEMP + 12U)\r
 131 #endif\r
 132 \r
 133 #define SERIAL_MANAGER_USE_COMMON_TASK (1U)\r
 134 #define SERIAL_MANAGER_TASK_PRIORITY (2U)\r
 135 #define SERIAL_MANAGER_TASK_STACK_SIZE (1000U)\r
 136 \r
 137 typedef void *serial_handle_t;\r
 138 typedef void *serial_write_handle_t;\r
 139 typedef void *serial_read_handle_t;\r
 140 \r
 141 /*! @brief serial port type*/\r
 142 typedef enum _serial_port_type\r
 143 {\r
 144     kSerialPort_Uart = 1U,     /*!< Serial port UART */\r
 145     kSerialPort_UsbCdc,        /*!< Serial port USB CDC */\r
 146     kSerialPort_Swo,           /*!< Serial port SWO */\r
 147     kSerialPort_UsbCdcVirtual, /*!< Serial port USB CDC Virtual */\r
 148 } serial_port_type_t;\r
 149 \r
 150 /*! @brief serial manager config structure*/\r
 151 typedef struct _serial_manager_config\r
 152 {\r
 153     uint8_t *ringBuffer;     /*!< Ring buffer address, it is used to buffer data received by the hardware.\r
 154                                   Besides, the memory space cannot be free during the lifetime of the serial\r
 155                                   manager module. */\r
 156     uint32_t ringBufferSize; /*!< The size of the ring buffer */\r
 157     serial_port_type_t type; /*!< Serial port type */\r
 158     void *portConfig;        /*!< Serial port configuration */\r
 159 } serial_manager_config_t;\r
 160 \r
 161 /*! @brief serial manager error code*/\r
 162 typedef enum _serial_manager_status\r
 163 {\r
 164     kStatus_SerialManager_Success = kStatus_Success,                            /*!< Success */\r
 165     kStatus_SerialManager_Error   = MAKE_STATUS(kStatusGroup_SERIALMANAGER, 1), /*!< Failed */\r
 166     kStatus_SerialManager_Busy    = MAKE_STATUS(kStatusGroup_SERIALMANAGER, 2), /*!< Busy */\r
 167     kStatus_SerialManager_Notify  = MAKE_STATUS(kStatusGroup_SERIALMANAGER, 3), /*!< Ring buffer is not empty */\r
 168     kStatus_SerialManager_Canceled =\r
 169         MAKE_STATUS(kStatusGroup_SERIALMANAGER, 4), /*!< the non-blocking request is canceled */\r
 170     kStatus_SerialManager_HandleConflict = MAKE_STATUS(kStatusGroup_SERIALMANAGER, 5), /*!< The handle is opened */\r
 171     kStatus_SerialManager_RingBufferOverflow =\r
 172         MAKE_STATUS(kStatusGroup_SERIALMANAGER, 6), /*!< The ring buffer is overflowed */\r
 173 } serial_manager_status_t;\r
 174 \r
 175 /*! @brief Callback message structure */\r
 176 typedef struct _serial_manager_callback_message\r
 177 {\r
 178     uint8_t *buffer; /*!< Transferred buffer */\r
 179     uint32_t length; /*!< Transferred data length */\r
 180 } serial_manager_callback_message_t;\r
 181 \r
 182 /*! @brief callback function */\r
 183 typedef void (*serial_manager_callback_t)(void *callbackParam,\r
 184                                           serial_manager_callback_message_t *message,\r
 185                                           serial_manager_status_t status);\r
 186 \r
 187 /*******************************************************************************\r
 188  * API\r
 189  ******************************************************************************/\r
 190 \r
 191 #if defined(__cplusplus)\r
 192 extern "C" {\r
 193 #endif /* _cplusplus */\r
 194 \r
 195 /*!\r
 196  * @brief Initializes a serial manager module with the serial manager handle and the user configuration structure.\r
 197  *\r
 198  * This function configures the Serial Manager module with user-defined settings. The user can configure the\r
 199  * configuration\r
 200  * structure. The parameter serialHandle is a pointer to point to a memory space of size #SERIAL_MANAGER_HANDLE_SIZE\r
 201  * allocated by the caller.\r
 202  * The Serial Manager module supports two types of serial port, UART (includes UART, USART, LPSCI, LPUART, etc) and USB\r
 203  * CDC.\r
 204  * Please refer to #serial_port_type_t for serial port setting. These two types can be set by using\r
 205  * #serial_manager_config_t.\r
 206  *\r
 207  * Example below shows how to use this API to configure the Serial Manager.\r
 208  * For UART,\r
 209  *  @code\r
 210  *   #define SERIAL_MANAGER_RING_BUFFER_SIZE          (256U)\r
 211  *   static uint32_t s_serialHandleBuffer[((SERIAL_MANAGER_HANDLE_SIZE + sizeof(uint32_t) - 1) / sizeof(uitn32_t))];\r
 212  *   static serial_handle_t s_serialHandle = (serial_handle_t)&s_serialHandleBuffer[0];\r
 213  *   static uint8_t s_ringBuffer[SERIAL_MANAGER_RING_BUFFER_SIZE];\r
 214  *\r
 215  *   serial_manager_config_t config;\r
 216  *   serial_port_uart_config_t uartConfig;\r
 217  *   config.type = kSerialPort_Uart;\r
 218  *   config.ringBuffer = &s_ringBuffer[0];\r
 219  *   config.ringBufferSize = SERIAL_MANAGER_RING_BUFFER_SIZE;\r
 220  *   uartConfig.instance = 0;\r
 221  *   uartConfig.clockRate = 24000000;\r
 222  *   uartConfig.baudRate = 115200;\r
 223  *   uartConfig.parityMode = kSerialManager_UartParityDisabled;\r
 224  *   uartConfig.stopBitCount = kSerialManager_UartOneStopBit;\r
 225  *   uartConfig.enableRx = 1;\r
 226  *   uartConfig.enableTx = 1;\r
 227  *   config.portConfig = &uartConfig;\r
 228  *   SerialManager_Init(s_serialHandle, &config);\r
 229  *  @endcode\r
 230  * For USB CDC,\r
 231  *  @code\r
 232  *   #define SERIAL_MANAGER_RING_BUFFER_SIZE          (256U)\r
 233  *   static uint32_t s_serialHandleBuffer[((SERIAL_MANAGER_HANDLE_SIZE + sizeof(uint32_t) - 1) / sizeof(uitn32_t))];\r
 234  *   static serial_handle_t s_serialHandle = (serial_handle_t)&s_serialHandleBuffer[0];\r
 235  *   static uint8_t s_ringBuffer[SERIAL_MANAGER_RING_BUFFER_SIZE];\r
 236  *\r
 237  *   serial_manager_config_t config;\r
 238  *   serial_port_usb_cdc_config_t usbCdcConfig;\r
 239  *   config.type = kSerialPort_UsbCdc;\r
 240  *   config.ringBuffer = &s_ringBuffer[0];\r
 241  *   config.ringBufferSize = SERIAL_MANAGER_RING_BUFFER_SIZE;\r
 242  *   usbCdcConfig.controllerIndex = kSerialManager_UsbControllerKhci0;\r
 243  *   config.portConfig = &usbCdcConfig;\r
 244  *   SerialManager_Init(s_serialHandle, &config);\r
 245  *  @endcode\r
 246  *\r
 247  * @param serialHandle Pointer to point to a memory space of size #SERIAL_MANAGER_HANDLE_SIZE allocated by the caller.\r
 248  * The handle should be 4 byte aligned, because unaligned access does not support on some devices.\r
 249  * @param config Pointer to user-defined configuration structure.\r
 250  * @retval kStatus_SerialManager_Error An error occurred.\r
 251  * @retval kStatus_SerialManager_Success The Serial Manager module initialization succeed.\r
 252  */\r
 253 serial_manager_status_t SerialManager_Init(serial_handle_t serialHandle, serial_manager_config_t *config);\r
 254 \r
 255 /*!\r
 256  * @brief De-initializes the serial manager module instance.\r
 257  *\r
 258  * This function de-initializes the serial manager module instance. If the opened writing or\r
 259  * reading handle is not closed, the function will return kStatus_SerialManager_Busy.\r
 260  *\r
 261  * @param serialHandle The serial manager module handle pointer.\r
 262  * @retval kStatus_SerialManager_Success The serial manager de-initialization succeed.\r
 263  * @retval kStatus_SerialManager_Busy Opened reading or writing handle is not closed.\r
 264  */\r
 265 serial_manager_status_t SerialManager_Deinit(serial_handle_t serialHandle);\r
 266 \r
 267 /*!\r
 268  * @brief Opens a writing handle for the serial manager module.\r
 269  *\r
 270  * This function Opens a writing handle for the serial manager module. If the serial manager needs to\r
 271  * be used in different tasks, the task should open a dedicated write handle for itself by calling\r
 272  * #SerialManager_OpenWriteHandle. Since there can only one buffer for transmission for the writing\r
 273  * handle at the same time, multiple writing handles need to be opened when the multiple transmission\r
 274  * is needed for a task.\r
 275  *\r
 276  * @param serialHandle The serial manager module handle pointer.\r
 277  * The handle should be 4 byte aligned, because unaligned access does not support on some devices.\r
 278  * @param writeHandle The serial manager module writing handle pointer.\r
 279  * The handle should be 4 byte aligned, because unaligned access does not support on some devices.\r
 280  * @retval kStatus_SerialManager_Error An error occurred.\r
 281  * @retval kStatus_SerialManager_HandleConflict The writing handle was opened.\r
 282  * @retval kStatus_SerialManager_Success The writing handle is opened.\r
 283  *\r
 284  * Example below shows how to use this API to write data.\r
 285  * For task 1,\r
 286  *  @code\r
 287  *   static uint32_t s_serialWriteHandleBuffer1[((SERIAL_MANAGER_WRITE_HANDLE_SIZE + sizeof(uint32_t) - 1) /\r
 288  * sizeof(uitn32_t))]; static serial_write_handle_t s_serialWriteHandle1 =\r
 289  * (serial_write_handle_t)&s_serialWriteHandleBuffer1[0]; static uint8_t s_nonBlockingWelcome1[] = "This is non-blocking\r
 290  * writing log for task1!\r\n"; SerialManager_OpenWriteHandle(serialHandle, s_serialWriteHandle1);\r
 291  *   SerialManager_InstallTxCallback(s_serialWriteHandle1, Task1_SerialManagerTxCallback, s_serialWriteHandle1);\r
 292  *   SerialManager_WriteNonBlocking(s_serialWriteHandle1, s_nonBlockingWelcome1, sizeof(s_nonBlockingWelcome1) - 1);\r
 293  *  @endcode\r
 294  * For task 2,\r
 295  *  @code\r
 296  *   static uint32_t s_serialWriteHandleBuffer2[((SERIAL_MANAGER_WRITE_HANDLE_SIZE + sizeof(uint32_t) - 1) /\r
 297  * sizeof(uitn32_t))]; static serial_write_handle_t s_serialWriteHandle2 =\r
 298  * (serial_write_handle_t)&s_serialWriteHandleBuffer2[0]; static uint8_t s_nonBlockingWelcome2[] = "This is non-blocking\r
 299  * writing log for task2!\r\n"; SerialManager_OpenWriteHandle(serialHandle, s_serialWriteHandle2);\r
 300  *   SerialManager_InstallTxCallback(s_serialWriteHandle2, Task2_SerialManagerTxCallback, s_serialWriteHandle2);\r
 301  *   SerialManager_WriteNonBlocking(s_serialWriteHandle2, s_nonBlockingWelcome2, sizeof(s_nonBlockingWelcome2) - 1);\r
 302  *  @endcode\r
 303  */\r
 304 serial_manager_status_t SerialManager_OpenWriteHandle(serial_handle_t serialHandle, serial_write_handle_t writeHandle);\r
 305 \r
 306 /*!\r
 307  * @brief Closes a writing handle for the serial manager module.\r
 308  *\r
 309  * This function Closes a writing handle for the serial manager module.\r
 310  *\r
 311  * @param writeHandle The serial manager module writing handle pointer.\r
 312  * @retval kStatus_SerialManager_Success The writing handle is closed.\r
 313  */\r
 314 serial_manager_status_t SerialManager_CloseWriteHandle(serial_write_handle_t writeHandle);\r
 315 \r
 316 /*!\r
 317  * @brief Opens a reading handle for the serial manager module.\r
 318  *\r
 319  * This function Opens a reading handle for the serial manager module. The reading handle can not be\r
 320  * opened multiple at the same time. The error code kStatus_SerialManager_Busy would be returned when\r
 321  * the previous reading handle is not closed. And There can only be one buffer for receiving for the\r
 322  * reading handle at the same time.\r
 323  *\r
 324  * @param serialHandle The serial manager module handle pointer.\r
 325  * The handle should be 4 byte aligned, because unaligned access does not support on some devices.\r
 326  * @param readHandle The serial manager module reading handle pointer.\r
 327  * The handle should be 4 byte aligned, because unaligned access does not support on some devices.\r
 328  * @retval kStatus_SerialManager_Error An error occurred.\r
 329  * @retval kStatus_SerialManager_Success The reading handle is opened.\r
 330  * @retval kStatus_SerialManager_Busy Previous reading handle is not closed.\r
 331  *\r
 332  * Example below shows how to use this API to read data.\r
 333  *  @code\r
 334  *   static uint32_t s_serialReadHandleBuffer[((SERIAL_MANAGER_READ_HANDLE_SIZE + sizeof(uint32_t) - 1) /\r
 335  * sizeof(uitn32_t))]; static serial_read_handle_t s_serialReadHandle =\r
 336  * (serial_read_handle_t)&s_serialReadHandleBuffer[0]; SerialManager_OpenReadHandle(serialHandle, s_serialReadHandle);\r
 337  *   static uint8_t s_nonBlockingBuffer[64];\r
 338  *   SerialManager_InstallRxCallback(s_serialReadHandle, APP_SerialManagerRxCallback, s_serialReadHandle);\r
 339  *   SerialManager_ReadNonBlocking(s_serialReadHandle, s_nonBlockingBuffer, sizeof(s_nonBlockingBuffer));\r
 340  *  @endcode\r
 341  */\r
 342 serial_manager_status_t SerialManager_OpenReadHandle(serial_handle_t serialHandle, serial_read_handle_t readHandle);\r
 343 \r
 344 /*!\r
 345  * @brief Closes a reading for the serial manager module.\r
 346  *\r
 347  * This function Closes a reading for the serial manager module.\r
 348  *\r
 349  * @param readHandle The serial manager module reading handle pointer.\r
 350  * @retval kStatus_SerialManager_Success The reading handle is closed.\r
 351  */\r
 352 serial_manager_status_t SerialManager_CloseReadHandle(serial_read_handle_t readHandle);\r
 353 \r
 354 /*!\r
 355  * @brief Transmits data with the blocking mode.\r
 356  *\r
 357  * This is a blocking function, which polls the sending queue, waits for the sending queue to be empty.\r
 358  * This function sends data using an interrupt method. The interrupt of the hardware could not be disabled.\r
 359  * And There can only one buffer for transmission for the writing handle at the same time.\r
 360  *\r
 361  * @note The function #SerialManager_WriteBlocking and the function #SerialManager_WriteNonBlocking\r
 362  * cannot be used at the same time.\r
 363  * And, the function #SerialManager_CancelWriting cannot be used to abort the transmission of this function.\r
 364  *\r
 365  * @param writeHandle The serial manager module handle pointer.\r
 366  * @param buffer Start address of the data to write.\r
 367  * @param length Length of the data to write.\r
 368  * @retval kStatus_SerialManager_Success Successfully sent all data.\r
 369  * @retval kStatus_SerialManager_Busy Previous transmission still not finished; data not all sent yet.\r
 370  * @retval kStatus_SerialManager_Error An error occurred.\r
 371  */\r
 372 serial_manager_status_t SerialManager_WriteBlocking(serial_write_handle_t writeHandle,\r
 373                                                     uint8_t *buffer,\r
 374                                                     uint32_t length);\r
 375 \r
 376 /*!\r
 377  * @brief Reads data with the blocking mode.\r
 378  *\r
 379  * This is a blocking function, which polls the receiving buffer, waits for the receiving buffer to be full.\r
 380  * This function receives data using an interrupt method. The interrupt of the hardware could not be disabled.\r
 381  * And There can only one buffer for receiving for the reading handle at the same time.\r
 382  *\r
 383  * @note The function #SerialManager_ReadBlocking and the function #SerialManager_ReadNonBlocking\r
 384  * cannot be used at the same time.\r
 385  * And, the function #SerialManager_CancelReading cannot be used to abort the transmission of this function.\r
 386  *\r
 387  * @param readHandle The serial manager module handle pointer.\r
 388  * @param buffer Start address of the data to store the received data.\r
 389  * @param length The length of the data to be received.\r
 390  * @retval kStatus_SerialManager_Success Successfully received all data.\r
 391  * @retval kStatus_SerialManager_Busy Previous transmission still not finished; data not all received yet.\r
 392  * @retval kStatus_SerialManager_Error An error occurred.\r
 393  */\r
 394 serial_manager_status_t SerialManager_ReadBlocking(serial_read_handle_t readHandle, uint8_t *buffer, uint32_t length);\r
 395 \r
 396 #if (defined(SERIAL_MANAGER_NON_BLOCKING_MODE) && (SERIAL_MANAGER_NON_BLOCKING_MODE > 0U))\r
 397 /*!\r
 398  * @brief Transmits data with the non-blocking mode.\r
 399  *\r
 400  * This is a non-blocking function, which returns directly without waiting for all data to be sent.\r
 401  * When all data is sent, the module notifies the upper layer through a TX callback function and passes\r
 402  * the status parameter @ref kStatus_SerialManager_Success.\r
 403  * This function sends data using an interrupt method. The interrupt of the hardware could not be disabled.\r
 404  * And There can only one buffer for transmission for the writing handle at the same time.\r
 405  *\r
 406  * @note The function #SerialManager_WriteBlocking and the function #SerialManager_WriteNonBlocking\r
 407  * cannot be used at the same time. And, the TX callback is mandatory before the function could be used.\r
 408  *\r
 409  * @param writeHandle The serial manager module handle pointer.\r
 410  * @param buffer Start address of the data to write.\r
 411  * @param length Length of the data to write.\r
 412  * @retval kStatus_SerialManager_Success Successfully sent all data.\r
 413  * @retval kStatus_SerialManager_Busy Previous transmission still not finished; data not all sent yet.\r
 414  * @retval kStatus_SerialManager_Error An error occurred.\r
 415  */\r
 416 serial_manager_status_t SerialManager_WriteNonBlocking(serial_write_handle_t writeHandle,\r
 417                                                        uint8_t *buffer,\r
 418                                                        uint32_t length);\r
 419 \r
 420 /*!\r
 421  * @brief Reads data with the non-blocking mode.\r
 422  *\r
 423  * This is a non-blocking function, which returns directly without waiting for all data to be received.\r
 424  * When all data is received, the module driver notifies the upper layer\r
 425  * through a RX callback function and passes the status parameter @ref kStatus_SerialManager_Success.\r
 426  * This function receives data using an interrupt method. The interrupt of the hardware could not be disabled.\r
 427  * And There can only one buffer for receiving for the reading handle at the same time.\r
 428  *\r
 429  * @note The function #SerialManager_ReadBlocking and the function #SerialManager_ReadNonBlocking\r
 430  * cannot be used at the same time. And, the RX callback is mandatory before the function could be used.\r
 431  *\r
 432  * @param readHandle The serial manager module handle pointer.\r
 433  * @param buffer Start address of the data to store the received data.\r
 434  * @param length The length of the data to be received.\r
 435  * @retval kStatus_SerialManager_Success Successfully received all data.\r
 436  * @retval kStatus_SerialManager_Busy Previous transmission still not finished; data not all received yet.\r
 437  * @retval kStatus_SerialManager_Error An error occurred.\r
 438  */\r
 439 serial_manager_status_t SerialManager_ReadNonBlocking(serial_read_handle_t readHandle,\r
 440                                                       uint8_t *buffer,\r
 441                                                       uint32_t length);\r
 442 \r
 443 /*!\r
 444  * @brief Tries to read data.\r
 445  *\r
 446  * The function tries to read data from internal ring buffer. If the ring buffer is not empty, the data will be\r
 447  * copied from ring buffer to up layer buffer. The copied length is the minimum of the ring buffer and up layer length.\r
 448  * After the data is copied, the actual data length is passed by the parameter length.\r
 449  * And There can only one buffer for receiving for the reading handle at the same time.\r
 450  *\r
 451  * @param readHandle The serial manager module handle pointer.\r
 452  * @param buffer Start address of the data to store the received data.\r
 453  * @param length The length of the data to be received.\r
 454  * @param receivedLength Length received from the ring buffer directly.\r
 455  * @retval kStatus_SerialManager_Success Successfully received all data.\r
 456  * @retval kStatus_SerialManager_Busy Previous transmission still not finished; data not all received yet.\r
 457  * @retval kStatus_SerialManager_Error An error occurred.\r
 458  */\r
 459 serial_manager_status_t SerialManager_TryRead(serial_read_handle_t readHandle,\r
 460                                               uint8_t *buffer,\r
 461                                               uint32_t length,\r
 462                                               uint32_t *receivedLength);\r
 463 \r
 464 /*!\r
 465  * @brief Cancels unfinished send transmission.\r
 466  *\r
 467  * The function cancels unfinished send transmission. When the transfer is canceled, the module notifies the upper layer\r
 468  * through a TX callback function and passes the status parameter @ref kStatus_SerialManager_Canceled.\r
 469  *\r
 470  * @note The function #SerialManager_CancelWriting cannot be used to abort the transmission of\r
 471  * the function #SerialManager_WriteBlocking.\r
 472  *\r
 473  * @param writeHandle The serial manager module handle pointer.\r
 474  * @retval kStatus_SerialManager_Success Get successfully abort the sending.\r
 475  * @retval kStatus_SerialManager_Error An error occurred.\r
 476  */\r
 477 serial_manager_status_t SerialManager_CancelWriting(serial_write_handle_t writeHandle);\r
 478 \r
 479 /*!\r
 480  * @brief Cancels unfinished receive transmission.\r
 481  *\r
 482  * The function cancels unfinished receive transmission. When the transfer is canceled, the module notifies the upper\r
 483  * layer\r
 484  * through a RX callback function and passes the status parameter @ref kStatus_SerialManager_Canceled.\r
 485  *\r
 486  * @note The function #SerialManager_CancelReading cannot be used to abort the transmission of\r
 487  * the function #SerialManager_ReadBlocking.\r
 488  *\r
 489  * @param readHandle The serial manager module handle pointer.\r
 490  * @retval kStatus_SerialManager_Success Get successfully abort the receiving.\r
 491  * @retval kStatus_SerialManager_Error An error occurred.\r
 492  */\r
 493 serial_manager_status_t SerialManager_CancelReading(serial_read_handle_t readHandle);\r
 494 \r
 495 /*!\r
 496  * @brief Installs a TX callback and callback parameter.\r
 497  *\r
 498  * This function is used to install the TX callback and callback parameter for the serial manager module.\r
 499  * When any status of TX transmission changed, the driver will notify the upper layer by the installed callback\r
 500  * function. And the status is also passed as status parameter when the callback is called.\r
 501  *\r
 502  * @param writeHandle The serial manager module handle pointer.\r
 503  * @param callback The callback function.\r
 504  * @param callbackParam The parameter of the callback function.\r
 505  * @retval kStatus_SerialManager_Success Successfully install the callback.\r
 506  */\r
 507 serial_manager_status_t SerialManager_InstallTxCallback(serial_write_handle_t writeHandle,\r
 508                                                         serial_manager_callback_t callback,\r
 509                                                         void *callbackParam);\r
 510 \r
 511 /*!\r
 512  * @brief Installs a RX callback and callback parameter.\r
 513  *\r
 514  * This function is used to install the RX callback and callback parameter for the serial manager module.\r
 515  * When any status of RX transmission changed, the driver will notify the upper layer by the installed callback\r
 516  * function. And the status is also passed as status parameter when the callback is called.\r
 517  *\r
 518  * @param readHandle The serial manager module handle pointer.\r
 519  * @param callback The callback function.\r
 520  * @param callbackParam The parameter of the callback function.\r
 521  * @retval kStatus_SerialManager_Success Successfully install the callback.\r
 522  */\r
 523 serial_manager_status_t SerialManager_InstallRxCallback(serial_read_handle_t readHandle,\r
 524                                                         serial_manager_callback_t callback,\r
 525                                                         void *callbackParam);\r
 526 \r
 527 #endif\r
 528 \r
 529 /*!\r
 530  * @brief Prepares to enter low power consumption.\r
 531  *\r
 532  * This function is used to prepare to enter low power consumption.\r
 533  *\r
 534  * @param serialHandle The serial manager module handle pointer.\r
 535  * @retval kStatus_SerialManager_Success Successful operation.\r
 536  */\r
 537 serial_manager_status_t SerialManager_EnterLowpower(serial_handle_t serialHandle);\r
 538 \r
 539 /*!\r
 540  * @brief Restores from low power consumption.\r
 541  *\r
 542  * This function is used to restore from low power consumption.\r
 543  *\r
 544  * @param serialHandle The serial manager module handle pointer.\r
 545  * @retval kStatus_SerialManager_Success Successful operation.\r
 546  */\r
 547 serial_manager_status_t SerialManager_ExitLowpower(serial_handle_t serialHandle);\r
 548 \r
 549 #if defined(__cplusplus)\r
 550 }\r
 551 #endif\r
 552 /*! @} */\r
 553 #endif /* __SERIAL_MANAGER_H__ */\r