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