git.sur5r.net Git - freertos/blob - FreeRTOS/Demo/CORTEX_M0+_LPC51U68_LPCXpresso/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.0. */\r
  25 #define FSL_USART_DRIVER_VERSION (MAKE_VERSION(2, 1, 0))\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 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     usart_txfifo_watermark_t txWatermark; /*!< txFIFO watermark */\r
 189     usart_rxfifo_watermark_t rxWatermark; /*!< rxFIFO watermark */\r
 190 };\r
 191 \r
 192 /*******************************************************************************\r
 193  * API\r
 194  ******************************************************************************/\r
 195 \r
 196 #if defined(__cplusplus)\r
 197 extern "C" {\r
 198 #endif /* _cplusplus */\r
 199 \r
 200 /*! @brief Returns instance number for USART peripheral base address. */\r
 201 uint32_t USART_GetInstance(USART_Type *base);\r
 202 \r
 203 /*!\r
 204  * @name Initialization and deinitialization\r
 205  * @{\r
 206  */\r
 207 \r
 208 /*!\r
 209  * @brief Initializes a USART instance with user configuration structure and peripheral clock.\r
 210  *\r
 211  * This function configures the USART module with the user-defined settings. The user can configure the configuration\r
 212  * structure and also get the default configuration by using the USART_GetDefaultConfig() function.\r
 213  * Example below shows how to use this API to configure USART.\r
 214  * @code\r
 215  *  usart_config_t usartConfig;\r
 216  *  usartConfig.baudRate_Bps = 115200U;\r
 217  *  usartConfig.parityMode = kUSART_ParityDisabled;\r
 218  *  usartConfig.stopBitCount = kUSART_OneStopBit;\r
 219  *  USART_Init(USART1, &usartConfig, 20000000U);\r
 220  * @endcode\r
 221  *\r
 222  * @param base USART peripheral base address.\r
 223  * @param config Pointer to user-defined configuration structure.\r
 224  * @param srcClock_Hz USART clock source frequency in HZ.\r
 225  * @retval kStatus_USART_BaudrateNotSupport Baudrate is not support in current clock source.\r
 226  * @retval kStatus_InvalidArgument USART base address is not valid\r
 227  * @retval kStatus_Success Status USART initialize succeed\r
 228  */\r
 229 status_t USART_Init(USART_Type *base, const usart_config_t *config, uint32_t srcClock_Hz);\r
 230 \r
 231 /*!\r
 232  * @brief Deinitializes a USART instance.\r
 233  *\r
 234  * This function waits for TX complete, disables TX and RX, and disables the USART clock.\r
 235  *\r
 236  * @param base USART peripheral base address.\r
 237  */\r
 238 void USART_Deinit(USART_Type *base);\r
 239 \r
 240 /*!\r
 241  * @brief Gets the default configuration structure.\r
 242  *\r
 243  * This function initializes the USART configuration structure to a default value. The default\r
 244  * values are:\r
 245  *   usartConfig->baudRate_Bps = 115200U;\r
 246  *   usartConfig->parityMode = kUSART_ParityDisabled;\r
 247  *   usartConfig->stopBitCount = kUSART_OneStopBit;\r
 248  *   usartConfig->bitCountPerChar = kUSART_8BitsPerChar;\r
 249  *   usartConfig->loopback = false;\r
 250  *   usartConfig->enableTx = false;\r
 251  *   usartConfig->enableRx = false;\r
 252  *\r
 253  * @param config Pointer to configuration structure.\r
 254  */\r
 255 void USART_GetDefaultConfig(usart_config_t *config);\r
 256 \r
 257 /*!\r
 258  * @brief Sets the USART instance baud rate.\r
 259  *\r
 260  * This function configures the USART module baud rate. This function is used to update\r
 261  * the USART module baud rate after the USART module is initialized by the USART_Init.\r
 262  * @code\r
 263  *  USART_SetBaudRate(USART1, 115200U, 20000000U);\r
 264  * @endcode\r
 265  *\r
 266  * @param base USART peripheral base address.\r
 267  * @param baudrate_Bps USART baudrate to be set.\r
 268  * @param srcClock_Hz USART clock source frequency in HZ.\r
 269  * @retval kStatus_USART_BaudrateNotSupport Baudrate is not support in current clock source.\r
 270  * @retval kStatus_Success Set baudrate succeed.\r
 271  * @retval kStatus_InvalidArgument One or more arguments are invalid.\r
 272  */\r
 273 status_t USART_SetBaudRate(USART_Type *base, uint32_t baudrate_Bps, uint32_t srcClock_Hz);\r
 274 \r
 275 /* @} */\r
 276 \r
 277 /*!\r
 278  * @name Status\r
 279  * @{\r
 280  */\r
 281 \r
 282 /*!\r
 283  * @brief Get USART status flags.\r
 284  *\r
 285  * This function get all USART status flags, the flags are returned as the logical\r
 286  * OR value of the enumerators @ref _usart_flags. To check a specific status,\r
 287  * compare the return value with enumerators in @ref _usart_flags.\r
 288  * For example, to check whether the TX is empty:\r
 289  * @code\r
 290  *     if (kUSART_TxFifoNotFullFlag & USART_GetStatusFlags(USART1))\r
 291  *     {\r
 292  *         ...\r
 293  *     }\r
 294  * @endcode\r
 295  *\r
 296  * @param base USART peripheral base address.\r
 297  * @return USART status flags which are ORed by the enumerators in the _usart_flags.\r
 298  */\r
 299 static inline uint32_t USART_GetStatusFlags(USART_Type *base)\r
 300 {\r
 301     return base->FIFOSTAT;\r
 302 }\r
 303 \r
 304 /*!\r
 305  * @brief Clear USART status flags.\r
 306  *\r
 307  * This function clear supported USART status flags\r
 308  * Flags that can be cleared or set are:\r
 309  *      kUSART_TxError\r
 310  *      kUSART_RxError\r
 311  * For example:\r
 312  * @code\r
 313  *     USART_ClearStatusFlags(USART1, kUSART_TxError | kUSART_RxError)\r
 314  * @endcode\r
 315  *\r
 316  * @param base USART peripheral base address.\r
 317  * @param mask status flags to be cleared.\r
 318  */\r
 319 static inline void USART_ClearStatusFlags(USART_Type *base, uint32_t mask)\r
 320 {\r
 321     /* Only TXERR, RXERR fields support write. Remaining fields should be set to zero */\r
 322     base->FIFOSTAT = mask & (USART_FIFOSTAT_TXERR_MASK | USART_FIFOSTAT_RXERR_MASK);\r
 323 }\r
 324 \r
 325 /* @} */\r
 326 \r
 327 /*!\r
 328  * @name Interrupts\r
 329  * @{\r
 330  */\r
 331 \r
 332 /*!\r
 333  * @brief Enables USART interrupts according to the provided mask.\r
 334  *\r
 335  * This function enables the USART interrupts according to the provided mask. The mask\r
 336  * is a logical OR of enumeration members. See @ref _usart_interrupt_enable.\r
 337  * For example, to enable TX empty interrupt and RX full interrupt:\r
 338  * @code\r
 339  *     USART_EnableInterrupts(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 enable. Logical OR of @ref _usart_interrupt_enable.\r
 344  */\r
 345 static inline void USART_EnableInterrupts(USART_Type *base, uint32_t mask)\r
 346 {\r
 347     base->FIFOINTENSET = mask & 0xF;\r
 348 }\r
 349 \r
 350 /*!\r
 351  * @brief Disables USART interrupts according to a provided mask.\r
 352  *\r
 353  * This function disables the USART interrupts according to a provided mask. The mask\r
 354  * is a logical OR of enumeration members. See @ref _usart_interrupt_enable.\r
 355  * This example shows how to disable the TX empty interrupt and RX full interrupt:\r
 356  * @code\r
 357  *     USART_DisableInterrupts(USART1, kUSART_TxLevelInterruptEnable | kUSART_RxLevelInterruptEnable);\r
 358  * @endcode\r
 359  *\r
 360  * @param base USART peripheral base address.\r
 361  * @param mask The interrupts to disable. Logical OR of @ref _usart_interrupt_enable.\r
 362  */\r
 363 static inline void USART_DisableInterrupts(USART_Type *base, uint32_t mask)\r
 364 {\r
 365     base->FIFOINTENCLR = mask & 0xF;\r
 366 }\r
 367 \r
 368 /*!\r
 369  * @brief Returns enabled USART interrupts.\r
 370  *\r
 371  * This function returns the enabled USART interrupts.\r
 372  *\r
 373  * @param base USART peripheral base address.\r
 374  */\r
 375 static inline uint32_t USART_GetEnabledInterrupts(USART_Type *base)\r
 376 {\r
 377     return base->FIFOINTENSET;\r
 378 }\r
 379 \r
 380 /*!\r
 381  * @brief Enable DMA for Tx\r
 382  */\r
 383 static inline void USART_EnableTxDMA(USART_Type *base, bool enable)\r
 384 {\r
 385     if (enable)\r
 386     {\r
 387         base->FIFOCFG |= USART_FIFOCFG_DMATX_MASK;\r
 388     }\r
 389     else\r
 390     {\r
 391         base->FIFOCFG &= ~(USART_FIFOCFG_DMATX_MASK);\r
 392     }\r
 393 }\r
 394 \r
 395 /*!\r
 396  * @brief Enable DMA for Rx\r
 397  */\r
 398 static inline void USART_EnableRxDMA(USART_Type *base, bool enable)\r
 399 {\r
 400     if (enable)\r
 401     {\r
 402         base->FIFOCFG |= USART_FIFOCFG_DMARX_MASK;\r
 403     }\r
 404     else\r
 405     {\r
 406         base->FIFOCFG &= ~(USART_FIFOCFG_DMARX_MASK);\r
 407     }\r
 408 }\r
 409 \r
 410 /*!\r
 411  * @brief Enable CTS.\r
 412  * This function will determine whether CTS is used for flow control.\r
 413  *\r
 414  * @param base    USART peripheral base address.\r
 415  * @param enable  Enable CTS or not, true for enable and false for disable.\r
 416  */\r
 417 static inline void USART_EnableCTS(USART_Type *base, bool enable)\r
 418 {\r
 419     if (enable)\r
 420     {\r
 421         base->CFG |= USART_CFG_CTSEN_MASK;\r
 422     }\r
 423     else\r
 424     {\r
 425         base->CFG &= ~USART_CFG_CTSEN_MASK;\r
 426     }\r
 427 }\r
 428 \r
 429 /*!\r
 430  * @brief Continuous Clock generation.\r
 431  * By default, SCLK is only output while data is being transmitted in synchronous mode.\r
 432  * Enable this funciton, SCLK will run continuously in synchronous mode, allowing\r
 433  * characters to be received on Un_RxD independently from transmission on Un_TXD).\r
 434  *\r
 435  * @param base    USART peripheral base address.\r
 436  * @param enable  Enable Continuous Clock generation mode or not, true for enable and false for disable.\r
 437  */\r
 438 static inline void USART_EnableContinuousSCLK(USART_Type *base, bool enable)\r
 439 {\r
 440     if (enable)\r
 441     {\r
 442         base->CTL |= USART_CTL_CC_MASK;\r
 443     }\r
 444     else\r
 445     {\r
 446         base->CTL &= ~USART_CTL_CC_MASK;\r
 447     }\r
 448 }\r
 449 \r
 450 /*!\r
 451  * @brief Enable Continuous Clock generation bit auto clear.\r
 452  * While enable this cuntion, the Continuous Clock bit is automatically cleared when a complete\r
 453  * character has been received. This bit is cleared at the same time.\r
 454  *\r
 455  * @param base    USART peripheral base address.\r
 456  * @param enable  Enable auto clear or not, true for enable and false for disable.\r
 457  */\r
 458 static inline void USART_EnableAutoClearSCLK(USART_Type *base, bool enable)\r
 459 {\r
 460     if (enable)\r
 461     {\r
 462         base->CTL |= USART_CTL_CLRCCONRX_MASK;\r
 463     }\r
 464     else\r
 465     {\r
 466         base->CTL &= ~USART_CTL_CLRCCONRX_MASK;\r
 467     }\r
 468 }\r
 469 /* @} */\r
 470 \r
 471 /*!\r
 472  * @name Bus Operations\r
 473  * @{\r
 474  */\r
 475 \r
 476 /*!\r
 477  * @brief Writes to the FIFOWR register.\r
 478  *\r
 479  * This function writes data to the txFIFO directly. The upper layer must ensure\r
 480  * that txFIFO has space for data to write before calling this function.\r
 481  *\r
 482  * @param base USART peripheral base address.\r
 483  * @param data The byte to write.\r
 484  */\r
 485 static inline void USART_WriteByte(USART_Type *base, uint8_t data)\r
 486 {\r
 487     base->FIFOWR = data;\r
 488 }\r
 489 \r
 490 /*!\r
 491  * @brief Reads the FIFORD register directly.\r
 492  *\r
 493  * This function reads data from the rxFIFO directly. The upper layer must\r
 494  * ensure that the rxFIFO is not empty before calling this function.\r
 495  *\r
 496  * @param base USART peripheral base address.\r
 497  * @return The byte read from USART data register.\r
 498  */\r
 499 static inline uint8_t USART_ReadByte(USART_Type *base)\r
 500 {\r
 501     return base->FIFORD;\r
 502 }\r
 503 \r
 504 /*!\r
 505  * @brief Writes to the TX register using a blocking method.\r
 506  *\r
 507  * This function polls the TX register, waits for the TX register to be empty or for the TX FIFO\r
 508  * to have room and writes data to the TX buffer.\r
 509  *\r
 510  * @param base USART peripheral base address.\r
 511  * @param data Start address of the data to write.\r
 512  * @param length Size of the data to write.\r
 513  */\r
 514 void USART_WriteBlocking(USART_Type *base, const uint8_t *data, size_t length);\r
 515 \r
 516 /*!\r
 517  * @brief Read RX data register using a blocking method.\r
 518  *\r
 519  * This function polls the RX register, waits for the RX register to be full or for RX FIFO to\r
 520  * have data and read data from the TX register.\r
 521  *\r
 522  * @param base USART peripheral base address.\r
 523  * @param data Start address of the buffer to store the received data.\r
 524  * @param length Size of the buffer.\r
 525  * @retval kStatus_USART_FramingError Receiver overrun happened while receiving data.\r
 526  * @retval kStatus_USART_ParityError Noise error happened while receiving data.\r
 527  * @retval kStatus_USART_NoiseError Framing error happened while receiving data.\r
 528  * @retval kStatus_USART_RxError Overflow or underflow rxFIFO happened.\r
 529  * @retval kStatus_Success Successfully received all data.\r
 530  */\r
 531 status_t USART_ReadBlocking(USART_Type *base, uint8_t *data, size_t length);\r
 532 \r
 533 /* @} */\r
 534 \r
 535 /*!\r
 536  * @name Transactional\r
 537  * @{\r
 538  */\r
 539 \r
 540 /*!\r
 541  * @brief Initializes the USART handle.\r
 542  *\r
 543  * This function initializes the USART handle which can be used for other USART\r
 544  * transactional APIs. Usually, for a specified USART instance,\r
 545  * call this API once to get the initialized handle.\r
 546  *\r
 547  * @param base USART peripheral base address.\r
 548  * @param handle USART handle pointer.\r
 549  * @param callback The callback function.\r
 550  * @param userData The parameter of the callback function.\r
 551  */\r
 552 status_t USART_TransferCreateHandle(USART_Type *base,\r
 553                                     usart_handle_t *handle,\r
 554                                     usart_transfer_callback_t callback,\r
 555                                     void *userData);\r
 556 \r
 557 /*!\r
 558  * @brief Transmits a buffer of data using the interrupt method.\r
 559  *\r
 560  * This function sends data using an interrupt method. This is a non-blocking function, which\r
 561  * returns directly without waiting for all data to be written to the TX register. When\r
 562  * all data is written to the TX register in the IRQ handler, the USART driver calls the callback\r
 563  * function and passes the @ref kStatus_USART_TxIdle as status parameter.\r
 564  *\r
 565  * @note The kStatus_USART_TxIdle is passed to the upper layer when all data is written\r
 566  * to the TX register. However it does not ensure that all data are sent out. Before disabling the TX,\r
 567  * check the kUSART_TransmissionCompleteFlag to ensure that the TX is finished.\r
 568  *\r
 569  * @param base USART peripheral base address.\r
 570  * @param handle USART handle pointer.\r
 571  * @param xfer USART transfer structure. See  #usart_transfer_t.\r
 572  * @retval kStatus_Success Successfully start the data transmission.\r
 573  * @retval kStatus_USART_TxBusy Previous transmission still not finished, data not all written to TX register yet.\r
 574  * @retval kStatus_InvalidArgument Invalid argument.\r
 575  */\r
 576 status_t USART_TransferSendNonBlocking(USART_Type *base, usart_handle_t *handle, usart_transfer_t *xfer);\r
 577 \r
 578 /*!\r
 579  * @brief Sets up the RX ring buffer.\r
 580  *\r
 581  * This function sets up the RX ring buffer to a specific USART handle.\r
 582  *\r
 583  * When the RX ring buffer is used, data received are stored into the ring buffer even when the\r
 584  * user doesn't call the USART_TransferReceiveNonBlocking() API. If there is already data received\r
 585  * in the ring buffer, the user can get the received data from the ring buffer directly.\r
 586  *\r
 587  * @note When using the RX ring buffer, one byte is reserved for internal use. In other\r
 588  * words, if @p ringBufferSize is 32, then only 31 bytes are used for saving data.\r
 589  *\r
 590  * @param base USART peripheral base address.\r
 591  * @param handle USART handle pointer.\r
 592  * @param ringBuffer Start address of the ring buffer for background receiving. Pass NULL to disable the ring buffer.\r
 593  * @param ringBufferSize size of the ring buffer.\r
 594  */\r
 595 void USART_TransferStartRingBuffer(USART_Type *base,\r
 596                                    usart_handle_t *handle,\r
 597                                    uint8_t *ringBuffer,\r
 598                                    size_t ringBufferSize);\r
 599 \r
 600 /*!\r
 601  * @brief Aborts the background transfer and uninstalls the ring buffer.\r
 602  *\r
 603  * This function aborts the background transfer and uninstalls the ring buffer.\r
 604  *\r
 605  * @param base USART peripheral base address.\r
 606  * @param handle USART handle pointer.\r
 607  */\r
 608 void USART_TransferStopRingBuffer(USART_Type *base, usart_handle_t *handle);\r
 609 \r
 610 /*!\r
 611  * @brief Get the length of received data in RX ring buffer.\r
 612  *\r
 613  * @param handle USART handle pointer.\r
 614  * @return Length of received data in RX ring buffer.\r
 615  */\r
 616 size_t USART_TransferGetRxRingBufferLength(usart_handle_t *handle);\r
 617 \r
 618 /*!\r
 619  * @brief Aborts the interrupt-driven data transmit.\r
 620  *\r
 621  * This function aborts the interrupt driven data sending. The user can get the remainBtyes to find out\r
 622  * how many bytes are still not sent out.\r
 623  *\r
 624  * @param base USART peripheral base address.\r
 625  * @param handle USART handle pointer.\r
 626  */\r
 627 void USART_TransferAbortSend(USART_Type *base, usart_handle_t *handle);\r
 628 \r
 629 /*!\r
 630  * @brief Get the number of bytes that have been written to USART TX register.\r
 631  *\r
 632  * This function gets the number of bytes that have been written to USART TX\r
 633  * register by interrupt method.\r
 634  *\r
 635  * @param base USART peripheral base address.\r
 636  * @param handle USART handle pointer.\r
 637  * @param count Send bytes count.\r
 638  * @retval kStatus_NoTransferInProgress No send in progress.\r
 639  * @retval kStatus_InvalidArgument Parameter is invalid.\r
 640  * @retval kStatus_Success Get successfully through the parameter \p count;\r
 641  */\r
 642 status_t USART_TransferGetSendCount(USART_Type *base, usart_handle_t *handle, uint32_t *count);\r
 643 \r
 644 /*!\r
 645  * @brief Receives a buffer of data using an interrupt method.\r
 646  *\r
 647  * This function receives data using an interrupt method. This is a non-blocking function, which\r
 648  *  returns without waiting for all data to be received.\r
 649  * If the RX ring buffer is used and not empty, the data in the ring buffer is copied and\r
 650  * the parameter @p receivedBytes shows how many bytes are copied from the ring buffer.\r
 651  * After copying, if the data in the ring buffer is not enough to read, the receive\r
 652  * request is saved by the USART driver. When the new data arrives, the receive request\r
 653  * is serviced first. When all data is received, the USART driver notifies the upper layer\r
 654  * through a callback function and passes the status parameter @ref kStatus_USART_RxIdle.\r
 655  * For example, the upper layer needs 10 bytes but there are only 5 bytes in the ring buffer.\r
 656  * The 5 bytes are copied to the xfer->data and this function returns with the\r
 657  * parameter @p receivedBytes set to 5. For the left 5 bytes, newly arrived data is\r
 658  * saved from the xfer->data[5]. When 5 bytes are received, the USART driver notifies the upper layer.\r
 659  * If the RX ring buffer is not enabled, this function enables the RX and RX interrupt\r
 660  * to receive data to the xfer->data. When all data is received, the upper layer is notified.\r
 661  *\r
 662  * @param base USART peripheral base address.\r
 663  * @param handle USART handle pointer.\r
 664  * @param xfer USART transfer structure, see #usart_transfer_t.\r
 665  * @param receivedBytes Bytes received from the ring buffer directly.\r
 666  * @retval kStatus_Success Successfully queue the transfer into transmit queue.\r
 667  * @retval kStatus_USART_RxBusy Previous receive request is not finished.\r
 668  * @retval kStatus_InvalidArgument Invalid argument.\r
 669  */\r
 670 status_t USART_TransferReceiveNonBlocking(USART_Type *base,\r
 671                                           usart_handle_t *handle,\r
 672                                           usart_transfer_t *xfer,\r
 673                                           size_t *receivedBytes);\r
 674 \r
 675 /*!\r
 676  * @brief Aborts the interrupt-driven data receiving.\r
 677  *\r
 678  * This function aborts the interrupt-driven data receiving. The user can get the remainBytes to find out\r
 679  * how many bytes not received yet.\r
 680  *\r
 681  * @param base USART peripheral base address.\r
 682  * @param handle USART handle pointer.\r
 683  */\r
 684 void USART_TransferAbortReceive(USART_Type *base, usart_handle_t *handle);\r
 685 \r
 686 /*!\r
 687  * @brief Get the number of bytes that have been received.\r
 688  *\r
 689  * This function gets the number of bytes that have been received.\r
 690  *\r
 691  * @param base USART peripheral base address.\r
 692  * @param handle USART handle pointer.\r
 693  * @param count Receive bytes count.\r
 694  * @retval kStatus_NoTransferInProgress No receive in progress.\r
 695  * @retval kStatus_InvalidArgument Parameter is invalid.\r
 696  * @retval kStatus_Success Get successfully through the parameter \p count;\r
 697  */\r
 698 status_t USART_TransferGetReceiveCount(USART_Type *base, usart_handle_t *handle, uint32_t *count);\r
 699 \r
 700 /*!\r
 701  * @brief USART IRQ handle function.\r
 702  *\r
 703  * This function handles the USART transmit and receive IRQ request.\r
 704  *\r
 705  * @param base USART peripheral base address.\r
 706  * @param handle USART handle pointer.\r
 707  */\r
 708 void USART_TransferHandleIRQ(USART_Type *base, usart_handle_t *handle);\r
 709 \r
 710 /* @} */\r
 711 \r
 712 #if defined(__cplusplus)\r
 713 }\r
 714 #endif\r
 715 \r
 716 /*! @}*/\r
 717 \r
 718 #endif /* _FSL_USART_H_ */\r