git.sur5r.net Git - freertos/blob - FreeRTOS/Demo/CORTEX_MPU_M33F_NXP_LPC55S69_MCUXpresso/NXP_Code/drivers/fsl_usart.h

   1 /*\r
   2  * Copyright (c) 2016, 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 #ifndef _FSL_USART_H_\r
   9 #define _FSL_USART_H_\r
  10 \r
  11 #include "fsl_common.h"\r
  12 \r
  13 /*!\r
  14  * @addtogroup usart_driver\r
  15  * @{\r
  16  */\r
  17 \r
  18 /*******************************************************************************\r
  19  * Definitions\r
  20  ******************************************************************************/\r
  21 \r
  22 /*! @name Driver version */\r
  23 /*@{*/\r
  24 /*! @brief USART driver version 2.0.3. */\r
  25 #define FSL_USART_DRIVER_VERSION (MAKE_VERSION(2, 0, 3))\r
  26 /*@}*/\r
  27 \r
  28 #define USART_FIFOTRIG_TXLVL_GET(base) (((base)->FIFOTRIG & USART_FIFOTRIG_TXLVL_MASK) >> USART_FIFOTRIG_TXLVL_SHIFT)\r
  29 #define USART_FIFOTRIG_RXLVL_GET(base) (((base)->FIFOTRIG & USART_FIFOTRIG_RXLVL_MASK) >> USART_FIFOTRIG_RXLVL_SHIFT)\r
  30 \r
  31 /*! @brief Error codes for the USART driver. */\r
  32 enum _usart_status\r
  33 {\r
  34     kStatus_USART_TxBusy = MAKE_STATUS(kStatusGroup_LPC_USART, 0),              /*!< Transmitter is busy. */\r
  35     kStatus_USART_RxBusy = MAKE_STATUS(kStatusGroup_LPC_USART, 1),              /*!< Receiver is busy. */\r
  36     kStatus_USART_TxIdle = MAKE_STATUS(kStatusGroup_LPC_USART, 2),              /*!< USART transmitter is idle. */\r
  37     kStatus_USART_RxIdle = MAKE_STATUS(kStatusGroup_LPC_USART, 3),              /*!< USART receiver is idle. */\r
  38     kStatus_USART_TxError = MAKE_STATUS(kStatusGroup_LPC_USART, 7),             /*!< Error happens on txFIFO. */\r
  39     kStatus_USART_RxError = MAKE_STATUS(kStatusGroup_LPC_USART, 9),             /*!< Error happens on rxFIFO. */\r
  40     kStatus_USART_RxRingBufferOverrun = MAKE_STATUS(kStatusGroup_LPC_USART, 8), /*!< Error happens on rx ring buffer */\r
  41     kStatus_USART_NoiseError = MAKE_STATUS(kStatusGroup_LPC_USART, 10),         /*!< USART noise error. */\r
  42     kStatus_USART_FramingError = MAKE_STATUS(kStatusGroup_LPC_USART, 11),       /*!< USART framing error. */\r
  43     kStatus_USART_ParityError = MAKE_STATUS(kStatusGroup_LPC_USART, 12),        /*!< USART parity error. */\r
  44     kStatus_USART_BaudrateNotSupport =\r
  45         MAKE_STATUS(kStatusGroup_LPC_USART, 13), /*!< Baudrate is not support in current clock source */\r
  46 };\r
  47 \r
  48 /*! @brief USART parity mode. */\r
  49 typedef enum _usart_parity_mode\r
  50 {\r
  51     kUSART_ParityDisabled = 0x0U, /*!< Parity disabled */\r
  52     kUSART_ParityEven = 0x2U,     /*!< Parity enabled, type even, bit setting: PE|PT = 10 */\r
  53     kUSART_ParityOdd = 0x3U,      /*!< Parity enabled, type odd,  bit setting: PE|PT = 11 */\r
  54 } usart_parity_mode_t;\r
  55 \r
  56 /*! @brief USART stop bit count. */\r
  57 typedef enum _usart_stop_bit_count\r
  58 {\r
  59     kUSART_OneStopBit = 0U, /*!< One stop bit */\r
  60     kUSART_TwoStopBit = 1U, /*!< Two stop bits */\r
  61 } usart_stop_bit_count_t;\r
  62 \r
  63 /*! @brief USART data size. */\r
  64 typedef enum _usart_data_len\r
  65 {\r
  66     kUSART_7BitsPerChar = 0U, /*!< Seven bit mode */\r
  67     kUSART_8BitsPerChar = 1U, /*!< Eight bit mode */\r
  68 } usart_data_len_t;\r
  69 \r
  70 /*! @brief txFIFO watermark values */\r
  71 typedef enum _usart_txfifo_watermark\r
  72 {\r
  73     kUSART_TxFifo0 = 0, /*!< USART tx watermark is empty */\r
  74     kUSART_TxFifo1 = 1, /*!< USART tx watermark at 1 item */\r
  75     kUSART_TxFifo2 = 2, /*!< USART tx watermark at 2 items */\r
  76     kUSART_TxFifo3 = 3, /*!< USART tx watermark at 3 items */\r
  77     kUSART_TxFifo4 = 4, /*!< USART tx watermark at 4 items */\r
  78     kUSART_TxFifo5 = 5, /*!< USART tx watermark at 5 items */\r
  79     kUSART_TxFifo6 = 6, /*!< USART tx watermark at 6 items */\r
  80     kUSART_TxFifo7 = 7, /*!< USART tx watermark at 7 items */\r
  81 } usart_txfifo_watermark_t;\r
  82 \r
  83 /*! @brief rxFIFO watermark values */\r
  84 typedef enum _usart_rxfifo_watermark\r
  85 {\r
  86     kUSART_RxFifo1 = 0, /*!< USART rx watermark at 1 item */\r
  87     kUSART_RxFifo2 = 1, /*!< USART rx watermark at 2 items */\r
  88     kUSART_RxFifo3 = 2, /*!< USART rx watermark at 3 items */\r
  89     kUSART_RxFifo4 = 3, /*!< USART rx watermark at 4 items */\r
  90     kUSART_RxFifo5 = 4, /*!< USART rx watermark at 5 items */\r
  91     kUSART_RxFifo6 = 5, /*!< USART rx watermark at 6 items */\r
  92     kUSART_RxFifo7 = 6, /*!< USART rx watermark at 7 items */\r
  93     kUSART_RxFifo8 = 7, /*!< USART rx watermark at 8 items */\r
  94 } usart_rxfifo_watermark_t;\r
  95 \r
  96 /*!\r
  97  * @brief USART interrupt configuration structure, default settings all disabled.\r
  98  */\r
  99 enum _usart_interrupt_enable\r
 100 {\r
 101     kUSART_TxErrorInterruptEnable = (USART_FIFOINTENSET_TXERR_MASK),\r
 102     kUSART_RxErrorInterruptEnable = (USART_FIFOINTENSET_RXERR_MASK),\r
 103     kUSART_TxLevelInterruptEnable = (USART_FIFOINTENSET_TXLVL_MASK),\r
 104     kUSART_RxLevelInterruptEnable = (USART_FIFOINTENSET_RXLVL_MASK),\r
 105 };\r
 106 \r
 107 /*!\r
 108  * @brief USART status flags.\r
 109  *\r
 110  * This provides constants for the USART status flags for use in the USART functions.\r
 111  */\r
 112 enum _usart_flags\r
 113 {\r
 114     kUSART_TxError = (USART_FIFOSTAT_TXERR_MASK),                 /*!< TEERR bit, sets if TX buffer is error */\r
 115     kUSART_RxError = (USART_FIFOSTAT_RXERR_MASK),                 /*!< RXERR bit, sets if RX buffer is error */\r
 116     kUSART_TxFifoEmptyFlag = (USART_FIFOSTAT_TXEMPTY_MASK),       /*!< TXEMPTY bit, sets if TX buffer is empty */\r
 117     kUSART_TxFifoNotFullFlag = (USART_FIFOSTAT_TXNOTFULL_MASK),   /*!< TXNOTFULL bit, sets if TX buffer is not full */\r
 118     kUSART_RxFifoNotEmptyFlag = (USART_FIFOSTAT_RXNOTEMPTY_MASK), /*!< RXNOEMPTY bit, sets if RX buffer is not empty */\r
 119     kUSART_RxFifoFullFlag = (USART_FIFOSTAT_RXFULL_MASK),         /*!< RXFULL bit, sets if RX buffer is full */\r
 120 };\r
 121 \r
 122 /*! @brief USART configuration structure. */\r
 123 typedef struct _usart_config\r
 124 {\r
 125     uint32_t baudRate_Bps;                /*!< USART baud rate  */\r
 126     usart_parity_mode_t parityMode;       /*!< Parity mode, disabled (default), even, odd */\r
 127     usart_stop_bit_count_t stopBitCount;  /*!< Number of stop bits, 1 stop bit (default) or 2 stop bits  */\r
 128     usart_data_len_t bitCountPerChar;     /*!< Data length - 7 bit, 8 bit  */\r
 129     bool loopback;                        /*!< Enable peripheral loopback */\r
 130     bool enableRx;                        /*!< Enable RX */\r
 131     bool enableTx;                        /*!< Enable TX */\r
 132     usart_txfifo_watermark_t txWatermark; /*!< txFIFO watermark */\r
 133     usart_rxfifo_watermark_t rxWatermark; /*!< rxFIFO watermark */\r
 134 } usart_config_t;\r
 135 \r
 136 /*! @brief USART transfer structure. */\r
 137 typedef struct _usart_transfer\r
 138 {\r
 139     uint8_t *data;   /*!< The buffer of data to be transfer.*/\r
 140     size_t dataSize; /*!< The byte count to be transfer. */\r
 141 } usart_transfer_t;\r
 142 \r
 143 /* Forward declaration of the handle typedef. */\r
 144 typedef struct _usart_handle usart_handle_t;\r
 145 \r
 146 /*! @brief USART transfer callback function. */\r
 147 typedef void (*usart_transfer_callback_t)(USART_Type *base, usart_handle_t *handle, status_t status, void *userData);\r
 148 \r
 149 /*! @brief USART handle structure. */\r
 150 struct _usart_handle\r
 151 {\r
 152     uint8_t *volatile txData;   /*!< Address of remaining data to send. */\r
 153     volatile size_t txDataSize; /*!< Size of the remaining data to send. */\r
 154     size_t txDataSizeAll;       /*!< Size of the data to send out. */\r
 155     uint8_t *volatile rxData;   /*!< Address of remaining data to receive. */\r
 156     volatile size_t rxDataSize; /*!< Size of the remaining data to receive. */\r
 157     size_t rxDataSizeAll;       /*!< Size of the data to receive. */\r
 158 \r
 159     uint8_t *rxRingBuffer;              /*!< Start address of the receiver ring buffer. */\r
 160     size_t rxRingBufferSize;            /*!< Size of the ring buffer. */\r
 161     volatile uint16_t rxRingBufferHead; /*!< Index for the driver to store received data into ring buffer. */\r
 162     volatile uint16_t rxRingBufferTail; /*!< Index for the user to get data from the ring buffer. */\r
 163 \r
 164     usart_transfer_callback_t callback; /*!< Callback function. */\r
 165     void *userData;                     /*!< USART callback function parameter.*/\r
 166 \r
 167     volatile uint8_t txState; /*!< TX transfer state. */\r
 168     volatile uint8_t rxState; /*!< RX transfer state */\r
 169 \r
 170     usart_txfifo_watermark_t txWatermark; /*!< txFIFO watermark */\r
 171     usart_rxfifo_watermark_t rxWatermark; /*!< rxFIFO watermark */\r
 172 };\r
 173 \r
 174 /*******************************************************************************\r
 175  * API\r
 176  ******************************************************************************/\r
 177 \r
 178 #if defined(__cplusplus)\r
 179 extern "C" {\r
 180 #endif /* _cplusplus */\r
 181 \r
 182 /*! @brief Returns instance number for USART peripheral base address. */\r
 183 uint32_t USART_GetInstance(USART_Type *base);\r
 184 \r
 185 /*!\r
 186  * @name Initialization and deinitialization\r
 187  * @{\r
 188  */\r
 189 \r
 190 /*!\r
 191  * @brief Initializes a USART instance with user configuration structure and peripheral clock.\r
 192  *\r
 193  * This function configures the USART module with the user-defined settings. The user can configure the configuration\r
 194  * structure and also get the default configuration by using the USART_GetDefaultConfig() function.\r
 195  * Example below shows how to use this API to configure USART.\r
 196  * @code\r
 197  *  usart_config_t usartConfig;\r
 198  *  usartConfig.baudRate_Bps = 115200U;\r
 199  *  usartConfig.parityMode = kUSART_ParityDisabled;\r
 200  *  usartConfig.stopBitCount = kUSART_OneStopBit;\r
 201  *  USART_Init(USART1, &usartConfig, 20000000U);\r
 202  * @endcode\r
 203  *\r
 204  * @param base USART peripheral base address.\r
 205  * @param config Pointer to user-defined configuration structure.\r
 206  * @param srcClock_Hz USART clock source frequency in HZ.\r
 207  * @retval kStatus_USART_BaudrateNotSupport Baudrate is not support in current clock source.\r
 208  * @retval kStatus_InvalidArgument USART base address is not valid\r
 209  * @retval kStatus_Success Status USART initialize succeed\r
 210  */\r
 211 status_t USART_Init(USART_Type *base, const usart_config_t *config, uint32_t srcClock_Hz);\r
 212 \r
 213 /*!\r
 214  * @brief Deinitializes a USART instance.\r
 215  *\r
 216  * This function waits for TX complete, disables TX and RX, and disables the USART clock.\r
 217  *\r
 218  * @param base USART peripheral base address.\r
 219  */\r
 220 void USART_Deinit(USART_Type *base);\r
 221 \r
 222 /*!\r
 223  * @brief Gets the default configuration structure.\r
 224  *\r
 225  * This function initializes the USART configuration structure to a default value. The default\r
 226  * values are:\r
 227  *   usartConfig->baudRate_Bps = 115200U;\r
 228  *   usartConfig->parityMode = kUSART_ParityDisabled;\r
 229  *   usartConfig->stopBitCount = kUSART_OneStopBit;\r
 230  *   usartConfig->bitCountPerChar = kUSART_8BitsPerChar;\r
 231  *   usartConfig->loopback = false;\r
 232  *   usartConfig->enableTx = false;\r
 233  *   usartConfig->enableRx = false;\r
 234  *\r
 235  * @param config Pointer to configuration structure.\r
 236  */\r
 237 void USART_GetDefaultConfig(usart_config_t *config);\r
 238 \r
 239 /*!\r
 240  * @brief Sets the USART instance baud rate.\r
 241  *\r
 242  * This function configures the USART module baud rate. This function is used to update\r
 243  * the USART module baud rate after the USART module is initialized by the USART_Init.\r
 244  * @code\r
 245  *  USART_SetBaudRate(USART1, 115200U, 20000000U);\r
 246  * @endcode\r
 247  *\r
 248  * @param base USART peripheral base address.\r
 249  * @param baudrate_Bps USART baudrate to be set.\r
 250  * @param srcClock_Hz USART clock source freqency in HZ.\r
 251  * @retval kStatus_USART_BaudrateNotSupport Baudrate is not support in current clock source.\r
 252  * @retval kStatus_Success Set baudrate succeed.\r
 253  * @retval kStatus_InvalidArgument One or more arguments are invalid.\r
 254  */\r
 255 status_t USART_SetBaudRate(USART_Type *base, uint32_t baudrate_Bps, uint32_t srcClock_Hz);\r
 256 \r
 257 /* @} */\r
 258 \r
 259 /*!\r
 260  * @name Status\r
 261  * @{\r
 262  */\r
 263 \r
 264 /*!\r
 265  * @brief Get USART status flags.\r
 266  *\r
 267  * This function get all USART status flags, the flags are returned as the logical\r
 268  * OR value of the enumerators @ref _usart_flags. To check a specific status,\r
 269  * compare the return value with enumerators in @ref _usart_flags.\r
 270  * For example, to check whether the TX is empty:\r
 271  * @code\r
 272  *     if (kUSART_TxFifoNotFullFlag & USART_GetStatusFlags(USART1))\r
 273  *     {\r
 274  *         ...\r
 275  *     }\r
 276  * @endcode\r
 277  *\r
 278  * @param base USART peripheral base address.\r
 279  * @return USART status flags which are ORed by the enumerators in the _usart_flags.\r
 280  */\r
 281 static inline uint32_t USART_GetStatusFlags(USART_Type *base)\r
 282 {\r
 283     return base->FIFOSTAT;\r
 284 }\r
 285 \r
 286 /*!\r
 287  * @brief Clear USART status flags.\r
 288  *\r
 289  * This function clear supported USART status flags\r
 290  * Flags that can be cleared or set are:\r
 291  *      kUSART_TxError\r
 292  *      kUSART_RxError\r
 293  * For example:\r
 294  * @code\r
 295  *     USART_ClearStatusFlags(USART1, kUSART_TxError | kUSART_RxError)\r
 296  * @endcode\r
 297  *\r
 298  * @param base USART peripheral base address.\r
 299  * @param mask status flags to be cleared.\r
 300  */\r
 301 static inline void USART_ClearStatusFlags(USART_Type *base, uint32_t mask)\r
 302 {\r
 303     /* Only TXERR, RXERR fields support write. Remaining fields should be set to zero */\r
 304     base->FIFOSTAT = mask & (USART_FIFOSTAT_TXERR_MASK | USART_FIFOSTAT_RXERR_MASK);\r
 305 }\r
 306 \r
 307 /* @} */\r
 308 \r
 309 /*!\r
 310  * @name Interrupts\r
 311  * @{\r
 312  */\r
 313 \r
 314 /*!\r
 315  * @brief Enables USART interrupts according to the provided mask.\r
 316  *\r
 317  * This function enables the USART interrupts according to the provided mask. The mask\r
 318  * is a logical OR of enumeration members. See @ref _usart_interrupt_enable.\r
 319  * For example, to enable TX empty interrupt and RX full interrupt:\r
 320  * @code\r
 321  *     USART_EnableInterrupts(USART1, kUSART_TxLevelInterruptEnable | kUSART_RxLevelInterruptEnable);\r
 322  * @endcode\r
 323  *\r
 324  * @param base USART peripheral base address.\r
 325  * @param mask The interrupts to enable. Logical OR of @ref _usart_interrupt_enable.\r
 326  */\r
 327 static inline void USART_EnableInterrupts(USART_Type *base, uint32_t mask)\r
 328 {\r
 329     base->FIFOINTENSET = mask & 0xF;\r
 330 }\r
 331 \r
 332 /*!\r
 333  * @brief Disables USART interrupts according to a provided mask.\r
 334  *\r
 335  * This function disables the USART interrupts according to a provided mask. The mask\r
 336  * is a logical OR of enumeration members. See @ref _usart_interrupt_enable.\r
 337  * This example shows how to disable the TX empty interrupt and RX full interrupt:\r
 338  * @code\r
 339  *     USART_DisableInterrupts(USART1, kUSART_TxLevelInterruptEnable | kUSART_RxLevelInterruptEnable);\r
 340  * @endcode\r
 341  *\r
 342  * @param base USART peripheral base address.\r
 343  * @param mask The interrupts to disable. Logical OR of @ref _usart_interrupt_enable.\r
 344  */\r
 345 static inline void USART_DisableInterrupts(USART_Type *base, uint32_t mask)\r
 346 {\r
 347     base->FIFOINTENCLR = mask & 0xF;\r
 348 }\r
 349 \r
 350 /*!\r
 351  * @brief Returns enabled USART interrupts.\r
 352  *\r
 353  * This function returns the enabled USART interrupts.\r
 354  *\r
 355  * @param base USART peripheral base address.\r
 356  */\r
 357 static inline uint32_t USART_GetEnabledInterrupts(USART_Type *base)\r
 358 {\r
 359     return base->FIFOINTENSET;\r
 360 }\r
 361 \r
 362 /*!\r
 363 * @brief Enable DMA for Tx\r
 364 */\r
 365 static inline void USART_EnableTxDMA(USART_Type *base, bool enable)\r
 366 {\r
 367     if (enable)\r
 368     {\r
 369         base->FIFOCFG |= USART_FIFOCFG_DMATX_MASK;\r
 370     }\r
 371     else\r
 372     {\r
 373         base->FIFOCFG &= ~(USART_FIFOCFG_DMATX_MASK);\r
 374     }\r
 375 }\r
 376 \r
 377 /*!\r
 378 * @brief Enable DMA for Rx\r
 379 */\r
 380 static inline void USART_EnableRxDMA(USART_Type *base, bool enable)\r
 381 {\r
 382     if (enable)\r
 383     {\r
 384         base->FIFOCFG |= USART_FIFOCFG_DMARX_MASK;\r
 385     }\r
 386     else\r
 387     {\r
 388         base->FIFOCFG &= ~(USART_FIFOCFG_DMARX_MASK);\r
 389     }\r
 390 }\r
 391 \r
 392 /*!\r
 393  * @brief Enable CTS.\r
 394  * This function will determine whether CTS is used for flow control.\r
 395  *\r
 396  * @param base    USART peripheral base address.\r
 397  * @param enable  Enable CTS or not, true for enable and false for disable.\r
 398  */\r
 399 static inline void USART_EnableCTS(USART_Type *base, bool enable)\r
 400 {\r
 401     if (enable)\r
 402     {\r
 403         base->CFG |= USART_CFG_CTSEN_MASK;\r
 404     }\r
 405     else\r
 406     {\r
 407         base->CFG &= ~USART_CFG_CTSEN_MASK;\r
 408     }\r
 409 }\r
 410 \r
 411 /* @} */\r
 412 \r
 413 /*!\r
 414  * @name Bus Operations\r
 415  * @{\r
 416  */\r
 417 \r
 418 /*!\r
 419  * @brief Writes to the FIFOWR register.\r
 420  *\r
 421  * This function writes data to the txFIFO directly. The upper layer must ensure\r
 422  * that txFIFO has space for data to write before calling this function.\r
 423  *\r
 424  * @param base USART peripheral base address.\r
 425  * @param data The byte to write.\r
 426  */\r
 427 static inline void USART_WriteByte(USART_Type *base, uint8_t data)\r
 428 {\r
 429     base->FIFOWR = data;\r
 430 }\r
 431 \r
 432 /*!\r
 433  * @brief Reads the FIFORD register directly.\r
 434  *\r
 435  * This function reads data from the rxFIFO directly. The upper layer must\r
 436  * ensure that the rxFIFO is not empty before calling this function.\r
 437  *\r
 438  * @param base USART peripheral base address.\r
 439  * @return The byte read from USART data register.\r
 440  */\r
 441 static inline uint8_t USART_ReadByte(USART_Type *base)\r
 442 {\r
 443     return base->FIFORD;\r
 444 }\r
 445 \r
 446 /*!\r
 447  * @brief Writes to the TX register using a blocking method.\r
 448  *\r
 449  * This function polls the TX register, waits for the TX register to be empty or for the TX FIFO\r
 450  * to have room and writes data to the TX buffer.\r
 451  *\r
 452  * @param base USART peripheral base address.\r
 453  * @param data Start address of the data to write.\r
 454  * @param length Size of the data to write.\r
 455  */\r
 456 void USART_WriteBlocking(USART_Type *base, const uint8_t *data, size_t length);\r
 457 \r
 458 /*!\r
 459  * @brief Read RX data register using a blocking method.\r
 460  *\r
 461  * This function polls the RX register, waits for the RX register to be full or for RX FIFO to\r
 462  * have data and read data from the TX register.\r
 463  *\r
 464  * @param base USART peripheral base address.\r
 465  * @param data Start address of the buffer to store the received data.\r
 466  * @param length Size of the buffer.\r
 467  * @retval kStatus_USART_FramingError Receiver overrun happened while receiving data.\r
 468  * @retval kStatus_USART_ParityError Noise error happened while receiving data.\r
 469  * @retval kStatus_USART_NoiseError Framing error happened while receiving data.\r
 470  * @retval kStatus_USART_RxError Overflow or underflow rxFIFO happened.\r
 471  * @retval kStatus_Success Successfully received all data.\r
 472  */\r
 473 status_t USART_ReadBlocking(USART_Type *base, uint8_t *data, size_t length);\r
 474 \r
 475 /* @} */\r
 476 \r
 477 /*!\r
 478  * @name Transactional\r
 479  * @{\r
 480  */\r
 481 \r
 482 /*!\r
 483  * @brief Initializes the USART handle.\r
 484  *\r
 485  * This function initializes the USART handle which can be used for other USART\r
 486  * transactional APIs. Usually, for a specified USART instance,\r
 487  * call this API once to get the initialized handle.\r
 488  *\r
 489  * @param base USART peripheral base address.\r
 490  * @param handle USART handle pointer.\r
 491  * @param callback The callback function.\r
 492  * @param userData The parameter of the callback function.\r
 493  */\r
 494 status_t USART_TransferCreateHandle(USART_Type *base,\r
 495                                     usart_handle_t *handle,\r
 496                                     usart_transfer_callback_t callback,\r
 497                                     void *userData);\r
 498 \r
 499 /*!\r
 500  * @brief Transmits a buffer of data using the interrupt method.\r
 501  *\r
 502  * This function sends data using an interrupt method. This is a non-blocking function, which\r
 503  * returns directly without waiting for all data to be written to the TX register. When\r
 504  * all data is written to the TX register in the IRQ handler, the USART driver calls the callback\r
 505  * function and passes the @ref kStatus_USART_TxIdle as status parameter.\r
 506  *\r
 507  * @note The kStatus_USART_TxIdle is passed to the upper layer when all data is written\r
 508  * to the TX register. However it does not ensure that all data are sent out. Before disabling the TX,\r
 509  * check the kUSART_TransmissionCompleteFlag to ensure that the TX is finished.\r
 510  *\r
 511  * @param base USART peripheral base address.\r
 512  * @param handle USART handle pointer.\r
 513  * @param xfer USART transfer structure. See  #usart_transfer_t.\r
 514  * @retval kStatus_Success Successfully start the data transmission.\r
 515  * @retval kStatus_USART_TxBusy Previous transmission still not finished, data not all written to TX register yet.\r
 516  * @retval kStatus_InvalidArgument Invalid argument.\r
 517  */\r
 518 status_t USART_TransferSendNonBlocking(USART_Type *base, usart_handle_t *handle, usart_transfer_t *xfer);\r
 519 \r
 520 /*!\r
 521  * @brief Sets up the RX ring buffer.\r
 522  *\r
 523  * This function sets up the RX ring buffer to a specific USART handle.\r
 524  *\r
 525  * When the RX ring buffer is used, data received are stored into the ring buffer even when the\r
 526  * user doesn't call the USART_TransferReceiveNonBlocking() API. If there is already data received\r
 527  * in the ring buffer, the user can get the received data from the ring buffer directly.\r
 528  *\r
 529  * @note When using the RX ring buffer, one byte is reserved for internal use. In other\r
 530  * words, if @p ringBufferSize is 32, then only 31 bytes are used for saving data.\r
 531  *\r
 532  * @param base USART peripheral base address.\r
 533  * @param handle USART handle pointer.\r
 534  * @param ringBuffer Start address of the ring buffer for background receiving. Pass NULL to disable the ring buffer.\r
 535  * @param ringBufferSize size of the ring buffer.\r
 536  */\r
 537 void USART_TransferStartRingBuffer(USART_Type *base,\r
 538                                    usart_handle_t *handle,\r
 539                                    uint8_t *ringBuffer,\r
 540                                    size_t ringBufferSize);\r
 541 \r
 542 /*!\r
 543  * @brief Aborts the background transfer and uninstalls the ring buffer.\r
 544  *\r
 545  * This function aborts the background transfer and uninstalls the ring buffer.\r
 546  *\r
 547  * @param base USART peripheral base address.\r
 548  * @param handle USART handle pointer.\r
 549  */\r
 550 void USART_TransferStopRingBuffer(USART_Type *base, usart_handle_t *handle);\r
 551 \r
 552 /*!\r
 553  * @brief Get the length of received data in RX ring buffer.\r
 554  *\r
 555  * @param handle USART handle pointer.\r
 556  * @return Length of received data in RX ring buffer.\r
 557  */\r
 558 size_t USART_TransferGetRxRingBufferLength(usart_handle_t *handle);\r
 559 \r
 560 /*!\r
 561  * @brief Aborts the interrupt-driven data transmit.\r
 562  *\r
 563  * This function aborts the interrupt driven data sending. The user can get the remainBtyes to find out\r
 564  * how many bytes are still not sent out.\r
 565  *\r
 566  * @param base USART peripheral base address.\r
 567  * @param handle USART handle pointer.\r
 568  */\r
 569 void USART_TransferAbortSend(USART_Type *base, usart_handle_t *handle);\r
 570 \r
 571 /*!\r
 572  * @brief Get the number of bytes that have been written to USART TX register.\r
 573  *\r
 574  * This function gets the number of bytes that have been written to USART TX\r
 575  * register by interrupt method.\r
 576  *\r
 577  * @param base USART peripheral base address.\r
 578  * @param handle USART handle pointer.\r
 579  * @param count Send bytes count.\r
 580  * @retval kStatus_NoTransferInProgress No send in progress.\r
 581  * @retval kStatus_InvalidArgument Parameter is invalid.\r
 582  * @retval kStatus_Success Get successfully through the parameter \p count;\r
 583  */\r
 584 status_t USART_TransferGetSendCount(USART_Type *base, usart_handle_t *handle, uint32_t *count);\r
 585 \r
 586 /*!\r
 587  * @brief Receives a buffer of data using an interrupt method.\r
 588  *\r
 589  * This function receives data using an interrupt method. This is a non-blocking function, which\r
 590  *  returns without waiting for all data to be received.\r
 591  * If the RX ring buffer is used and not empty, the data in the ring buffer is copied and\r
 592  * the parameter @p receivedBytes shows how many bytes are copied from the ring buffer.\r
 593  * After copying, if the data in the ring buffer is not enough to read, the receive\r
 594  * request is saved by the USART driver. When the new data arrives, the receive request\r
 595  * is serviced first. When all data is received, the USART driver notifies the upper layer\r
 596  * through a callback function and passes the status parameter @ref kStatus_USART_RxIdle.\r
 597  * For example, the upper layer needs 10 bytes but there are only 5 bytes in the ring buffer.\r
 598  * The 5 bytes are copied to the xfer->data and this function returns with the\r
 599  * parameter @p receivedBytes set to 5. For the left 5 bytes, newly arrived data is\r
 600  * saved from the xfer->data[5]. When 5 bytes are received, the USART driver notifies the upper layer.\r
 601  * If the RX ring buffer is not enabled, this function enables the RX and RX interrupt\r
 602  * to receive data to the xfer->data. When all data is received, the upper layer is notified.\r
 603  *\r
 604  * @param base USART peripheral base address.\r
 605  * @param handle USART handle pointer.\r
 606  * @param xfer USART transfer structure, see #usart_transfer_t.\r
 607  * @param receivedBytes Bytes received from the ring buffer directly.\r
 608  * @retval kStatus_Success Successfully queue the transfer into transmit queue.\r
 609  * @retval kStatus_USART_RxBusy Previous receive request is not finished.\r
 610  * @retval kStatus_InvalidArgument Invalid argument.\r
 611  */\r
 612 status_t USART_TransferReceiveNonBlocking(USART_Type *base,\r
 613                                           usart_handle_t *handle,\r
 614                                           usart_transfer_t *xfer,\r
 615                                           size_t *receivedBytes);\r
 616 \r
 617 /*!\r
 618  * @brief Aborts the interrupt-driven data receiving.\r
 619  *\r
 620  * This function aborts the interrupt-driven data receiving. The user can get the remainBytes to find out\r
 621  * how many bytes not received yet.\r
 622  *\r
 623  * @param base USART peripheral base address.\r
 624  * @param handle USART handle pointer.\r
 625  */\r
 626 void USART_TransferAbortReceive(USART_Type *base, usart_handle_t *handle);\r
 627 \r
 628 /*!\r
 629  * @brief Get the number of bytes that have been received.\r
 630  *\r
 631  * This function gets the number of bytes that have been received.\r
 632  *\r
 633  * @param base USART peripheral base address.\r
 634  * @param handle USART handle pointer.\r
 635  * @param count Receive bytes count.\r
 636  * @retval kStatus_NoTransferInProgress No receive in progress.\r
 637  * @retval kStatus_InvalidArgument Parameter is invalid.\r
 638  * @retval kStatus_Success Get successfully through the parameter \p count;\r
 639  */\r
 640 status_t USART_TransferGetReceiveCount(USART_Type *base, usart_handle_t *handle, uint32_t *count);\r
 641 \r
 642 /*!\r
 643  * @brief USART IRQ handle function.\r
 644  *\r
 645  * This function handles the USART transmit and receive IRQ request.\r
 646  *\r
 647  * @param base USART peripheral base address.\r
 648  * @param handle USART handle pointer.\r
 649  */\r
 650 void USART_TransferHandleIRQ(USART_Type *base, usart_handle_t *handle);\r
 651 \r
 652 /* @} */\r
 653 \r
 654 #if defined(__cplusplus)\r
 655 }\r
 656 #endif\r
 657 \r
 658 /*! @}*/\r
 659 \r
 660 #endif /* _FSL_USART_H_ */\r