1 /*
2  * Copyright (c) 2015-2016, Freescale Semiconductor, Inc.
3  * Copyright 2016-2021 NXP
4  * All rights reserved.
5  *
6  * SPDX-License-Identifier: BSD-3-Clause
7  */
8 #ifndef FSL_UART_H_
9 #define FSL_UART_H_
10 
11 #include "fsl_common.h"
12 
13 /*!
14  * @addtogroup uart_driver
15  * @{
16  */
17 
18 /*******************************************************************************
19  * Definitions
20  ******************************************************************************/
21 
22 /*! @name Driver version */
23 /*! @{ */
24 /*! @brief UART driver version. */
25 #define FSL_UART_DRIVER_VERSION (MAKE_VERSION(2, 5, 1))
26 /*! @} */
27 
28 /*! @brief Retry times for waiting flag. */
29 #ifndef UART_RETRY_TIMES
30 #define UART_RETRY_TIMES 0U /* Defining to zero means to keep waiting for the flag until it is assert/deassert. */
31 #endif
32 
33 /*! @brief Error codes for the UART driver. */
34 enum
35 {
36     kStatus_UART_TxBusy              = MAKE_STATUS(kStatusGroup_UART, 0), /*!< Transmitter is busy. */
37     kStatus_UART_RxBusy              = MAKE_STATUS(kStatusGroup_UART, 1), /*!< Receiver is busy. */
38     kStatus_UART_TxIdle              = MAKE_STATUS(kStatusGroup_UART, 2), /*!< UART transmitter is idle. */
39     kStatus_UART_RxIdle              = MAKE_STATUS(kStatusGroup_UART, 3), /*!< UART receiver is idle. */
40     kStatus_UART_TxWatermarkTooLarge = MAKE_STATUS(kStatusGroup_UART, 4), /*!< TX FIFO watermark too large  */
41     kStatus_UART_RxWatermarkTooLarge = MAKE_STATUS(kStatusGroup_UART, 5), /*!< RX FIFO watermark too large  */
42     kStatus_UART_FlagCannotClearManually =
43         MAKE_STATUS(kStatusGroup_UART, 6),                                 /*!< UART flag can't be manually cleared. */
44     kStatus_UART_Error               = MAKE_STATUS(kStatusGroup_UART, 7),  /*!< Error happens on UART. */
45     kStatus_UART_RxRingBufferOverrun = MAKE_STATUS(kStatusGroup_UART, 8),  /*!< UART RX software ring buffer overrun. */
46     kStatus_UART_RxHardwareOverrun   = MAKE_STATUS(kStatusGroup_UART, 9),  /*!< UART RX receiver overrun. */
47     kStatus_UART_NoiseError          = MAKE_STATUS(kStatusGroup_UART, 10), /*!< UART noise error. */
48     kStatus_UART_FramingError        = MAKE_STATUS(kStatusGroup_UART, 11), /*!< UART framing error. */
49     kStatus_UART_ParityError         = MAKE_STATUS(kStatusGroup_UART, 12), /*!< UART parity error. */
50     kStatus_UART_BaudrateNotSupport =
51         MAKE_STATUS(kStatusGroup_UART, 13), /*!< Baudrate is not support in current clock source */
52     kStatus_UART_IdleLineDetected = MAKE_STATUS(kStatusGroup_UART, 14), /*!< UART IDLE line detected. */
53     kStatus_UART_Timeout          = MAKE_STATUS(kStatusGroup_UART, 15), /*!< UART times out. */
54 };
55 
56 /*! @brief UART parity mode. */
57 typedef enum _uart_parity_mode
58 {
59     kUART_ParityDisabled = 0x0U, /*!< Parity disabled */
60     kUART_ParityEven     = 0x2U, /*!< Parity enabled, type even, bit setting: PE|PT = 10 */
61     kUART_ParityOdd      = 0x3U, /*!< Parity enabled, type odd,  bit setting: PE|PT = 11 */
62 } uart_parity_mode_t;
63 
64 /*! @brief UART stop bit count. */
65 typedef enum _uart_stop_bit_count
66 {
67     kUART_OneStopBit = 0U, /*!< One stop bit */
68     kUART_TwoStopBit = 1U, /*!< Two stop bits */
69 } uart_stop_bit_count_t;
70 
71 /*! @brief UART idle type select. */
72 typedef enum _uart_idle_type_select
73 {
74     kUART_IdleTypeStartBit = 0U, /*!< Start counting after a valid start bit. */
75     kUART_IdleTypeStopBit  = 1U, /*!< Start counting after a stop bit. */
76 } uart_idle_type_select_t;
77 
78 /*!
79  * @brief UART interrupt configuration structure, default settings all disabled.
80  *
81  * This structure contains the settings for all of the UART interrupt configurations.
82  */
83 enum _uart_interrupt_enable
84 {
85 #if defined(FSL_FEATURE_UART_HAS_LIN_BREAK_DETECT) && FSL_FEATURE_UART_HAS_LIN_BREAK_DETECT
86     kUART_LinBreakInterruptEnable = (UART_BDH_LBKDIE_MASK), /*!< LIN break detect interrupt. */
87 #endif
88     kUART_RxActiveEdgeInterruptEnable         = (UART_BDH_RXEDGIE_MASK), /*!< RX active edge interrupt. */
89     kUART_TxDataRegEmptyInterruptEnable       = (UART_C2_TIE_MASK << 8), /*!< Transmit data register empty interrupt. */
90     kUART_TransmissionCompleteInterruptEnable = (UART_C2_TCIE_MASK << 8), /*!< Transmission complete interrupt. */
91     kUART_RxDataRegFullInterruptEnable        = (UART_C2_RIE_MASK << 8),  /*!< Receiver data register full interrupt. */
92     kUART_IdleLineInterruptEnable             = (UART_C2_ILIE_MASK << 8), /*!< Idle line interrupt. */
93     kUART_RxOverrunInterruptEnable            = (UART_C3_ORIE_MASK << 16), /*!< Receiver overrun interrupt. */
94     kUART_NoiseErrorInterruptEnable           = (UART_C3_NEIE_MASK << 16), /*!< Noise error flag interrupt. */
95     kUART_FramingErrorInterruptEnable         = (UART_C3_FEIE_MASK << 16), /*!< Framing error flag interrupt. */
96     kUART_ParityErrorInterruptEnable          = (UART_C3_PEIE_MASK << 16), /*!< Parity error flag interrupt. */
97 #if defined(FSL_FEATURE_UART_HAS_FIFO) && FSL_FEATURE_UART_HAS_FIFO
98     kUART_RxFifoOverflowInterruptEnable  = (UART_CFIFO_RXOFE_MASK << 24), /*!< RX FIFO overflow interrupt. */
99     kUART_TxFifoOverflowInterruptEnable  = (UART_CFIFO_TXOFE_MASK << 24), /*!< TX FIFO overflow interrupt. */
100     kUART_RxFifoUnderflowInterruptEnable = (UART_CFIFO_RXUFE_MASK << 24), /*!< RX FIFO underflow interrupt. */
101 #endif
102     kUART_AllInterruptsEnable =
103 #if defined(FSL_FEATURE_UART_HAS_LIN_BREAK_DETECT) && FSL_FEATURE_UART_HAS_LIN_BREAK_DETECT
104         kUART_LinBreakInterruptEnable |
105 #endif
106         kUART_RxActiveEdgeInterruptEnable | kUART_TxDataRegEmptyInterruptEnable |
107         kUART_TransmissionCompleteInterruptEnable | kUART_RxDataRegFullInterruptEnable | kUART_IdleLineInterruptEnable |
108         kUART_RxOverrunInterruptEnable | kUART_NoiseErrorInterruptEnable | kUART_FramingErrorInterruptEnable |
109         kUART_ParityErrorInterruptEnable
110 #if defined(FSL_FEATURE_UART_HAS_FIFO) && FSL_FEATURE_UART_HAS_FIFO
111         | kUART_RxFifoOverflowInterruptEnable | kUART_TxFifoOverflowInterruptEnable |
112         kUART_RxFifoUnderflowInterruptEnable
113 #endif
114     ,
115 };
116 
117 /*!
118  * @brief UART status flags.
119  *
120  * This provides constants for the UART status flags for use in the UART functions.
121  */
122 enum
123 {
124     kUART_TxDataRegEmptyFlag       = (UART_S1_TDRE_MASK), /*!< TX data register empty flag. */
125     kUART_TransmissionCompleteFlag = (UART_S1_TC_MASK),   /*!< Transmission complete flag. */
126     kUART_RxDataRegFullFlag        = (UART_S1_RDRF_MASK), /*!< RX data register full flag. */
127     kUART_IdleLineFlag             = (UART_S1_IDLE_MASK), /*!< Idle line detect flag. */
128     kUART_RxOverrunFlag            = (UART_S1_OR_MASK),   /*!< RX overrun flag. */
129     kUART_NoiseErrorFlag           = (UART_S1_NF_MASK),   /*!< RX takes 3 samples of each received bit.
130                                                                If any of these samples differ, noise flag sets */
131     kUART_FramingErrorFlag = (UART_S1_FE_MASK),           /*!< Frame error flag, sets if logic 0 was detected
132                                                                where stop bit expected */
133     kUART_ParityErrorFlag = (UART_S1_PF_MASK),            /*!< If parity enabled, sets upon parity error detection */
134 #if defined(FSL_FEATURE_UART_HAS_LIN_BREAK_DETECT) && FSL_FEATURE_UART_HAS_LIN_BREAK_DETECT
135     kUART_LinBreakFlag =
136         (UART_S2_LBKDIF_MASK
137          << 8), /*!< LIN break detect interrupt flag, sets when LIN break char detected and LIN circuit enabled */
138 #endif
139     kUART_RxActiveEdgeFlag =
140         (UART_S2_RXEDGIF_MASK << 8), /*!< RX pin active edge interrupt flag,sets when active edge detected */
141     kUART_RxActiveFlag =
142         (UART_S2_RAF_MASK << 8), /*!< Receiver Active Flag (RAF), sets at beginning of valid start bit */
143 #if defined(FSL_FEATURE_UART_HAS_EXTENDED_DATA_REGISTER_FLAGS) && FSL_FEATURE_UART_HAS_EXTENDED_DATA_REGISTER_FLAGS
144     kUART_NoiseErrorInRxDataRegFlag  = (UART_ED_NOISY_MASK << 16),   /*!< Noisy bit, sets if noise detected. */
145     kUART_ParityErrorInRxDataRegFlag = (UART_ED_PARITYE_MASK << 16), /*!< Parity bit, sets if parity error detected. */
146 #endif
147 #if defined(FSL_FEATURE_UART_HAS_FIFO) && FSL_FEATURE_UART_HAS_FIFO
148     kUART_TxFifoEmptyFlag     = (int)(UART_SFIFO_TXEMPT_MASK << 24), /*!< TXEMPT bit, sets if TX buffer is empty */
149     kUART_RxFifoEmptyFlag     = (UART_SFIFO_RXEMPT_MASK << 24),      /*!< RXEMPT bit, sets if RX buffer is empty */
150     kUART_TxFifoOverflowFlag  = (UART_SFIFO_TXOF_MASK << 24), /*!< TXOF bit, sets if TX buffer overflow occurred */
151     kUART_RxFifoOverflowFlag  = (UART_SFIFO_RXOF_MASK << 24), /*!< RXOF bit, sets if receive buffer overflow */
152     kUART_RxFifoUnderflowFlag = (UART_SFIFO_RXUF_MASK << 24), /*!< RXUF bit, sets if receive buffer underflow */
153 #endif
154 };
155 
156 /*! @brief UART configuration structure. */
157 typedef struct _uart_config
158 {
159     uint32_t baudRate_Bps;         /*!< UART baud rate  */
160     uart_parity_mode_t parityMode; /*!< Parity mode, disabled (default), even, odd */
161 #if defined(FSL_FEATURE_UART_HAS_STOP_BIT_CONFIG_SUPPORT) && FSL_FEATURE_UART_HAS_STOP_BIT_CONFIG_SUPPORT
162     uart_stop_bit_count_t stopBitCount; /*!< Number of stop bits, 1 stop bit (default) or 2 stop bits  */
163 #endif
164 #if defined(FSL_FEATURE_UART_HAS_FIFO) && FSL_FEATURE_UART_HAS_FIFO
165     uint8_t txFifoWatermark; /*!< TX FIFO watermark */
166     uint8_t rxFifoWatermark; /*!< RX FIFO watermark */
167 #endif
168 #if defined(FSL_FEATURE_UART_HAS_MODEM_SUPPORT) && FSL_FEATURE_UART_HAS_MODEM_SUPPORT
169     bool enableRxRTS; /*!< RX RTS enable */
170     bool enableTxCTS; /*!< TX CTS enable */
171 #endif
172     uart_idle_type_select_t idleType; /*!< IDLE type select. */
173     bool enableTx;                    /*!< Enable TX */
174     bool enableRx;                    /*!< Enable RX */
175 } uart_config_t;
176 
177 /*! @brief UART transfer structure. */
178 typedef struct _uart_transfer
179 {
180     /*
181      * Use separate TX and RX data pointer, because TX data is const data.
182      * The member data is kept for backward compatibility.
183      */
184     union
185     {
186         uint8_t *data;         /*!< The buffer of data to be transfer.*/
187         uint8_t *rxData;       /*!< The buffer to receive data. */
188         const uint8_t *txData; /*!< The buffer of data to be sent. */
189     };
190     size_t dataSize; /*!< The byte count to be transfer. */
191 } uart_transfer_t;
192 
193 /* Forward declaration of the handle typedef. */
194 typedef struct _uart_handle uart_handle_t;
195 
196 /*! @brief UART transfer callback function. */
197 typedef void (*uart_transfer_callback_t)(UART_Type *base, uart_handle_t *handle, status_t status, void *userData);
198 
199 /*! @brief UART handle structure. */
200 struct _uart_handle
201 {
202     const uint8_t *volatile txData; /*!< Address of remaining data to send. */
203     volatile size_t txDataSize;     /*!< Size of the remaining data to send. */
204     size_t txDataSizeAll;           /*!< Size of the data to send out. */
205     uint8_t *volatile rxData;       /*!< Address of remaining data to receive. */
206     volatile size_t rxDataSize;     /*!< Size of the remaining data to receive. */
207     size_t rxDataSizeAll;           /*!< Size of the data to receive. */
208 
209     uint8_t *rxRingBuffer;              /*!< Start address of the receiver ring buffer. */
210     size_t rxRingBufferSize;            /*!< Size of the ring buffer. */
211     volatile uint16_t rxRingBufferHead; /*!< Index for the driver to store received data into ring buffer. */
212     volatile uint16_t rxRingBufferTail; /*!< Index for the user to get data from the ring buffer. */
213 
214     uart_transfer_callback_t callback; /*!< Callback function. */
215     void *userData;                    /*!< UART callback function parameter.*/
216 
217     volatile uint8_t txState; /*!< TX transfer state. */
218     volatile uint8_t rxState; /*!< RX transfer state */
219 };
220 
221 /* Typedef for interrupt handler. */
222 typedef void (*uart_isr_t)(UART_Type *base, void *handle);
223 
224 /*******************************************************************************
225  * Variables
226  ******************************************************************************/
227 /*! Pointers to uart handles for each instance. */
228 extern void *s_uartHandle[];
229 
230 /* Array of UART IRQs. */
231 extern const IRQn_Type s_uartIRQ[];
232 
233 /*! Pointer to uart IRQ handler for each instance. */
234 extern uart_isr_t s_uartIsr;
235 
236 /*******************************************************************************
237  * API
238  ******************************************************************************/
239 
240 #if defined(__cplusplus)
241 extern "C" {
242 #endif /* _cplusplus */
243 
244 /*!
245  * @brief Get the UART instance from peripheral base address.
246  *
247  * @param base UART peripheral base address.
248  * @return UART instance.
249  */
250 uint32_t UART_GetInstance(UART_Type *base);
251 
252 /*!
253  * @name Initialization and deinitialization
254  * @{
255  */
256 
257 /*!
258  * @brief Initializes a UART instance with a user configuration structure and peripheral clock.
259  *
260  * This function configures the UART module with the user-defined settings. The user can configure the configuration
261  * structure and also get the default configuration by using the UART_GetDefaultConfig() function.
262  * The example below shows how to use this API to configure UART.
263  * @code
264  *  uart_config_t uartConfig;
265  *  uartConfig.baudRate_Bps = 115200U;
266  *  uartConfig.parityMode = kUART_ParityDisabled;
267  *  uartConfig.stopBitCount = kUART_OneStopBit;
268  *  uartConfig.txFifoWatermark = 0;
269  *  uartConfig.rxFifoWatermark = 1;
270  *  UART_Init(UART1, &uartConfig, 20000000U);
271  * @endcode
272  *
273  * @param base UART peripheral base address.
274  * @param config Pointer to the user-defined configuration structure.
275  * @param srcClock_Hz UART clock source frequency in HZ.
276  * @retval kStatus_UART_BaudrateNotSupport Baudrate is not support in current clock source.
277  * @retval kStatus_Success Status UART initialize succeed
278  */
279 status_t UART_Init(UART_Type *base, const uart_config_t *config, uint32_t srcClock_Hz);
280 
281 /*!
282  * @brief Deinitializes a UART instance.
283  *
284  * This function waits for TX complete, disables TX and RX, and disables the UART clock.
285  *
286  * @param base UART peripheral base address.
287  */
288 void UART_Deinit(UART_Type *base);
289 
290 /*!
291  * @brief Gets the default configuration structure.
292  *
293  * This function initializes the UART configuration structure to a default value. The default
294  * values are as follows.
295  *   uartConfig->baudRate_Bps = 115200U;
296  *   uartConfig->bitCountPerChar = kUART_8BitsPerChar;
297  *   uartConfig->parityMode = kUART_ParityDisabled;
298  *   uartConfig->stopBitCount = kUART_OneStopBit;
299  *   uartConfig->txFifoWatermark = 0;
300  *   uartConfig->rxFifoWatermark = 1;
301  *   uartConfig->idleType = kUART_IdleTypeStartBit;
302  *   uartConfig->enableTx = false;
303  *   uartConfig->enableRx = false;
304  *
305  * @param config Pointer to configuration structure.
306  */
307 void UART_GetDefaultConfig(uart_config_t *config);
308 
309 /*!
310  * @brief Sets the UART instance baud rate.
311  *
312  * This function configures the UART module baud rate. This function is used to update
313  * the UART module baud rate after the UART module is initialized by the UART_Init.
314  * @code
315  *  UART_SetBaudRate(UART1, 115200U, 20000000U);
316  * @endcode
317  *
318  * @param base UART peripheral base address.
319  * @param baudRate_Bps UART baudrate to be set.
320  * @param srcClock_Hz UART clock source frequency in Hz.
321  * @retval kStatus_UART_BaudrateNotSupport Baudrate is not support in the current clock source.
322  * @retval kStatus_Success Set baudrate succeeded.
323  */
324 status_t UART_SetBaudRate(UART_Type *base, uint32_t baudRate_Bps, uint32_t srcClock_Hz);
325 
326 /*!
327  * @brief Enable 9-bit data mode for UART.
328  *
329  * This function set the 9-bit mode for UART module. The 9th bit is not used for parity thus can be modified by user.
330  *
331  * @param base UART peripheral base address.
332  * @param enable true to enable, flase to disable.
333  */
334 void UART_Enable9bitMode(UART_Type *base, bool enable);
335 
336 #if defined(FSL_FEATURE_UART_HAS_ADDRESS_MATCHING) && FSL_FEATURE_UART_HAS_ADDRESS_MATCHING
337 /*!
338  * @brief Set the UART slave address.
339  *
340  * This function configures the address for UART module that works as slave in 9-bit data mode. One or two address
341  * fields can be configured. When the address field's match enable bit is set, the frame it receices with MSB being
342  * 1 is considered as an address frame, otherwise it is considered as data frame. Once the address frame matches one
343  * of slave's own addresses, this slave is addressed. This address frame and its following data frames are stored in
344  * the receive buffer, otherwise the frames will be discarded. To un-address a slave, just send an address frame with
345  * unmatched address.
346  *
347  * @note Any UART instance joined in the multi-slave system can work as slave. The position of the address mark is the
348  * same as the parity bit when parity is enabled for 8 bit and 9 bit data formats.
349  *
350  * @param base UART peripheral base address.
351  * @param address1 UART slave address 1.
352  * @param address2 UART slave address 2.
353  */
UART_SetMatchAddress(UART_Type * base,uint8_t address1,uint8_t address2)354 static inline void UART_SetMatchAddress(UART_Type *base, uint8_t address1, uint8_t address2)
355 {
356     /* Configure match address. */
357     base->MA1 = address1;
358     base->MA2 = address2;
359 }
360 
361 /*!
362  * @brief Enable the UART match address feature.
363  *
364  * @param base UART peripheral base address.
365  * @param match1 true to enable match address1, false to disable.
366  * @param match2 true to enable match address2, false to disable.
367  */
UART_EnableMatchAddress(UART_Type * base,bool match1,bool match2)368 static inline void UART_EnableMatchAddress(UART_Type *base, bool match1, bool match2)
369 {
370     /* Configure match address1 enable bit. */
371     if (match1)
372     {
373         base->C4 |= (uint8_t)UART_C4_MAEN1_MASK;
374     }
375     else
376     {
377         base->C4 &= ~(uint8_t)UART_C4_MAEN1_MASK;
378     }
379     /* Configure match address2 enable bit. */
380     if (match2)
381     {
382         base->C4 |= (uint8_t)UART_C4_MAEN2_MASK;
383     }
384     else
385     {
386         base->C4 &= ~(uint8_t)UART_C4_MAEN2_MASK;
387     }
388 }
389 #endif
390 
391 /*!
392  * @brief Set UART 9th transmit bit.
393  *
394  * @param base UART peripheral base address.
395  */
UART_Set9thTransmitBit(UART_Type * base)396 static inline void UART_Set9thTransmitBit(UART_Type *base)
397 {
398     base->C3 |= (uint8_t)UART_C3_T8_MASK;
399 }
400 
401 /*!
402  * @brief Clear UART 9th transmit bit.
403  *
404  * @param base UART peripheral base address.
405  */
UART_Clear9thTransmitBit(UART_Type * base)406 static inline void UART_Clear9thTransmitBit(UART_Type *base)
407 {
408     base->C3 &= ~(uint8_t)UART_C3_T8_MASK;
409 }
410 
411 /*! @} */
412 
413 /*!
414  * @name Status
415  * @{
416  */
417 
418 /*!
419  * @brief Gets UART status flags.
420  *
421  * This function gets all UART status flags. The flags are returned as the logical
422  * OR value of the enumerators _uart_flags. To check a specific status,
423  * compare the return value with enumerators in _uart_flags.
424  * For example, to check whether the TX is empty, do the following.
425  * @code
426  *     if (kUART_TxDataRegEmptyFlag & UART_GetStatusFlags(UART1))
427  *     {
428  *         ...
429  *     }
430  * @endcode
431  *
432  * @param base UART peripheral base address.
433  * @return UART status flags which are ORed by the enumerators in the _uart_flags.
434  */
435 uint32_t UART_GetStatusFlags(UART_Type *base);
436 
437 /*!
438  * @brief Clears status flags with the provided mask.
439  *
440  * This function clears UART status flags with a provided mask. An automatically cleared flag
441  * can't be cleared by this function.
442  * These flags can only be cleared or set by hardware.
443  *    kUART_TxDataRegEmptyFlag, kUART_TransmissionCompleteFlag, kUART_RxDataRegFullFlag,
444  *    kUART_RxActiveFlag, kUART_NoiseErrorInRxDataRegFlag, kUART_ParityErrorInRxDataRegFlag,
445  *    kUART_TxFifoEmptyFlag,kUART_RxFifoEmptyFlag
446  * @note that this API should be called when the Tx/Rx is idle. Otherwise it has no effect.
447  *
448  * @param base UART peripheral base address.
449  * @param mask The status flags to be cleared; it is logical OR value of _uart_flags.
450  * @retval kStatus_UART_FlagCannotClearManually The flag can't be cleared by this function but
451  *         it is cleared automatically by hardware.
452  * @retval kStatus_Success Status in the mask is cleared.
453  */
454 status_t UART_ClearStatusFlags(UART_Type *base, uint32_t mask);
455 
456 /*! @} */
457 
458 /*!
459  * @name Interrupts
460  * @{
461  */
462 
463 /*!
464  * @brief Enables UART interrupts according to the provided mask.
465  *
466  * This function enables the UART interrupts according to the provided mask. The mask
467  * is a logical OR of enumeration members. See @ref _uart_interrupt_enable.
468  * For example, to enable TX empty interrupt and RX full interrupt, do the following.
469  * @code
470  *     UART_EnableInterrupts(UART1,kUART_TxDataRegEmptyInterruptEnable | kUART_RxDataRegFullInterruptEnable);
471  * @endcode
472  *
473  * @param base UART peripheral base address.
474  * @param mask The interrupts to enable. Logical OR of @ref _uart_interrupt_enable.
475  */
476 void UART_EnableInterrupts(UART_Type *base, uint32_t mask);
477 
478 /*!
479  * @brief Disables the UART interrupts according to the provided mask.
480  *
481  * This function disables the UART interrupts according to the provided mask. The mask
482  * is a logical OR of enumeration members. See @ref _uart_interrupt_enable.
483  * For example, to disable TX empty interrupt and RX full interrupt do the following.
484  * @code
485  *     UART_DisableInterrupts(UART1,kUART_TxDataRegEmptyInterruptEnable | kUART_RxDataRegFullInterruptEnable);
486  * @endcode
487  *
488  * @param base UART peripheral base address.
489  * @param mask The interrupts to disable. Logical OR of @ref _uart_interrupt_enable.
490  */
491 void UART_DisableInterrupts(UART_Type *base, uint32_t mask);
492 
493 /*!
494  * @brief Gets the enabled UART interrupts.
495  *
496  * This function gets the enabled UART interrupts. The enabled interrupts are returned
497  * as the logical OR value of the enumerators @ref _uart_interrupt_enable. To check
498  * a specific interrupts enable status, compare the return value with enumerators
499  * in @ref _uart_interrupt_enable.
500  * For example, to check whether TX empty interrupt is enabled, do the following.
501  * @code
502  *     uint32_t enabledInterrupts = UART_GetEnabledInterrupts(UART1);
503  *
504  *     if (kUART_TxDataRegEmptyInterruptEnable & enabledInterrupts)
505  *     {
506  *         ...
507  *     }
508  * @endcode
509  *
510  * @param base UART peripheral base address.
511  * @return UART interrupt flags which are logical OR of the enumerators in @ref _uart_interrupt_enable.
512  */
513 uint32_t UART_GetEnabledInterrupts(UART_Type *base);
514 
515 /*! @} */
516 
517 #if defined(FSL_FEATURE_UART_HAS_DMA_SELECT) && FSL_FEATURE_UART_HAS_DMA_SELECT
518 /*!
519  * @name DMA Control
520  * @{
521  */
522 
523 /*!
524  * @brief Gets the UART data register address.
525  *
526  * This function returns the UART data register address, which is mainly used by DMA/eDMA.
527  *
528  * @param base UART peripheral base address.
529  * @return UART data register addresses which are used both by the transmitter and the receiver.
530  */
UART_GetDataRegisterAddress(UART_Type * base)531 static inline uint32_t UART_GetDataRegisterAddress(UART_Type *base)
532 {
533     return (uint32_t) & (base->D);
534 }
535 
536 /*!
537  * @brief Enables or disables the UART transmitter DMA request.
538  *
539  * This function enables or disables the transmit data register empty flag, S1[TDRE], to generate the DMA requests.
540  *
541  * @param base UART peripheral base address.
542  * @param enable True to enable, false to disable.
543  */
UART_EnableTxDMA(UART_Type * base,bool enable)544 static inline void UART_EnableTxDMA(UART_Type *base, bool enable)
545 {
546     if (enable)
547     {
548 #if (defined(FSL_FEATURE_UART_IS_SCI) && FSL_FEATURE_UART_IS_SCI)
549         base->C4 |= (uint8_t)UART_C4_TDMAS_MASK;
550 #else
551         base->C5 |= (uint8_t)UART_C5_TDMAS_MASK;
552 #endif
553         base->C2 |= (uint8_t)UART_C2_TIE_MASK;
554     }
555     else
556     {
557 #if (defined(FSL_FEATURE_UART_IS_SCI) && FSL_FEATURE_UART_IS_SCI)
558         base->C4 &= ~(uint8_t)UART_C4_TDMAS_MASK;
559 #else
560         base->C5 &= ~(uint8_t)UART_C5_TDMAS_MASK;
561 #endif
562         base->C2 &= ~(uint8_t)UART_C2_TIE_MASK;
563     }
564 }
565 
566 /*!
567  * @brief Enables or disables the UART receiver DMA.
568  *
569  * This function enables or disables the receiver data register full flag, S1[RDRF], to generate DMA requests.
570  *
571  * @param base UART peripheral base address.
572  * @param enable True to enable, false to disable.
573  */
UART_EnableRxDMA(UART_Type * base,bool enable)574 static inline void UART_EnableRxDMA(UART_Type *base, bool enable)
575 {
576     if (enable)
577     {
578 #if (defined(FSL_FEATURE_UART_IS_SCI) && FSL_FEATURE_UART_IS_SCI)
579         base->C4 |= (uint8_t)UART_C4_RDMAS_MASK;
580 #else
581         base->C5 |= (uint8_t)UART_C5_RDMAS_MASK;
582 #endif
583         base->C2 |= (uint8_t)UART_C2_RIE_MASK;
584     }
585     else
586     {
587 #if (defined(FSL_FEATURE_UART_IS_SCI) && FSL_FEATURE_UART_IS_SCI)
588         base->C4 &= ~(uint8_t)UART_C4_RDMAS_MASK;
589 #else
590         base->C5 &= ~(uint8_t)UART_C5_RDMAS_MASK;
591 #endif
592         base->C2 &= ~(uint8_t)UART_C2_RIE_MASK;
593     }
594 }
595 
596 /*! @} */
597 #endif /* FSL_FEATURE_UART_HAS_DMA_SELECT */
598 
599 /*!
600  * @name Bus Operations
601  * @{
602  */
603 
604 /*!
605  * @brief Enables or disables the UART transmitter.
606  *
607  * This function enables or disables the UART transmitter.
608  *
609  * @param base UART peripheral base address.
610  * @param enable True to enable, false to disable.
611  */
UART_EnableTx(UART_Type * base,bool enable)612 static inline void UART_EnableTx(UART_Type *base, bool enable)
613 {
614     if (enable)
615     {
616         base->C2 |= (uint8_t)UART_C2_TE_MASK;
617     }
618     else
619     {
620         base->C2 &= ~(uint8_t)UART_C2_TE_MASK;
621     }
622 }
623 
624 /*!
625  * @brief Enables or disables the UART receiver.
626  *
627  * This function enables or disables the UART receiver.
628  *
629  * @param base UART peripheral base address.
630  * @param enable True to enable, false to disable.
631  */
UART_EnableRx(UART_Type * base,bool enable)632 static inline void UART_EnableRx(UART_Type *base, bool enable)
633 {
634     if (enable)
635     {
636         base->C2 |= (uint8_t)UART_C2_RE_MASK;
637     }
638     else
639     {
640         base->C2 &= ~(uint8_t)UART_C2_RE_MASK;
641     }
642 }
643 
644 /*!
645  * @brief Writes to the TX register.
646  *
647  * This function writes data to the TX register directly. The upper layer must ensure
648  * that the TX register is empty or TX FIFO has empty room before calling this function.
649  *
650  * @param base UART peripheral base address.
651  * @param data The byte to write.
652  */
UART_WriteByte(UART_Type * base,uint8_t data)653 static inline void UART_WriteByte(UART_Type *base, uint8_t data)
654 {
655     base->D = data;
656 }
657 
658 /*!
659  * @brief Reads the RX register directly.
660  *
661  * This function reads data from the RX register directly. The upper layer must
662  * ensure that the RX register is full or that the TX FIFO has data before calling this function.
663  *
664  * @param base UART peripheral base address.
665  * @return The byte read from UART data register.
666  */
UART_ReadByte(UART_Type * base)667 static inline uint8_t UART_ReadByte(UART_Type *base)
668 {
669     return base->D;
670 }
671 
672 #if defined(FSL_FEATURE_UART_HAS_FIFO) && FSL_FEATURE_UART_HAS_FIFO
673 /*!
674  * @brief Gets the rx FIFO data count.
675  *
676  * @param base UART peripheral base address.
677  * @return rx FIFO data count.
678  */
UART_GetRxFifoCount(UART_Type * base)679 static inline uint8_t UART_GetRxFifoCount(UART_Type *base)
680 {
681     return (uint8_t)base->RCFIFO;
682 }
683 
684 /*!
685  * @brief Gets the tx FIFO data count.
686  *
687  * @param base UART peripheral base address.
688  * @return tx FIFO data count.
689  */
UART_GetTxFifoCount(UART_Type * base)690 static inline uint8_t UART_GetTxFifoCount(UART_Type *base)
691 {
692     return (uint8_t)base->TCFIFO;
693 }
694 #endif /* FSL_FEATURE_UART_HAS_FIFO */
695 
696 #if defined(FSL_FEATURE_UART_HAS_ADDRESS_MATCHING) && FSL_FEATURE_UART_HAS_ADDRESS_MATCHING
697 /*!
698  * @brief Transmit an address frame in 9-bit data mode.
699  *
700  * @param base UART peripheral base address.
701  * @param address UART slave address.
702  */
703 void UART_SendAddress(UART_Type *base, uint8_t address);
704 #endif
705 
706 /*!
707  * @brief Writes to the TX register using a blocking method.
708  *
709  * This function polls the TX register, waits for the TX register to be empty or for the TX FIFO
710  * to have room and writes data to the TX buffer.
711  *
712  * @param base UART peripheral base address.
713  * @param data Start address of the data to write.
714  * @param length Size of the data to write.
715  * @retval kStatus_UART_Timeout Transmission timed out and was aborted.
716  * @retval kStatus_Success Successfully wrote all data.
717  */
718 status_t UART_WriteBlocking(UART_Type *base, const uint8_t *data, size_t length);
719 
720 /*!
721  * @brief Read RX data register using a blocking method.
722  *
723  * This function polls the RX register, waits for the RX register to be full or for RX FIFO to
724  * have data, and reads data from the TX register.
725  *
726  * @param base UART peripheral base address.
727  * @param data Start address of the buffer to store the received data.
728  * @param length Size of the buffer.
729  * @retval kStatus_UART_RxHardwareOverrun Receiver overrun occurred while receiving data.
730  * @retval kStatus_UART_NoiseError A noise error occurred while receiving data.
731  * @retval kStatus_UART_FramingError A framing error occurred while receiving data.
732  * @retval kStatus_UART_ParityError A parity error occurred while receiving data.
733  * @retval kStatus_UART_Timeout Transmission timed out and was aborted.
734  * @retval kStatus_Success Successfully received all data.
735  */
736 status_t UART_ReadBlocking(UART_Type *base, uint8_t *data, size_t length);
737 
738 /*! @} */
739 
740 /*!
741  * @name Transactional
742  * @{
743  */
744 
745 /*!
746  * @brief Initializes the UART handle.
747  *
748  * This function initializes the UART handle which can be used for other UART
749  * transactional APIs. Usually, for a specified UART instance,
750  * call this API once to get the initialized handle.
751  *
752  * @param base UART peripheral base address.
753  * @param handle UART handle pointer.
754  * @param callback The callback function.
755  * @param userData The parameter of the callback function.
756  */
757 void UART_TransferCreateHandle(UART_Type *base,
758                                uart_handle_t *handle,
759                                uart_transfer_callback_t callback,
760                                void *userData);
761 
762 /*!
763  * @brief Sets up the RX ring buffer.
764  *
765  * This function sets up the RX ring buffer to a specific UART handle.
766  *
767  * When the RX ring buffer is used, data received are stored into the ring buffer even when the
768  * user doesn't call the UART_TransferReceiveNonBlocking() API. If data is already received
769  * in the ring buffer, the user can get the received data from the ring buffer directly.
770  *
771  * @note When using the RX ring buffer, one byte is reserved for internal use. In other
772  * words, if @p ringBufferSize is 32, only 31 bytes are used for saving data.
773  *
774  * @param base UART peripheral base address.
775  * @param handle UART handle pointer.
776  * @param ringBuffer Start address of the ring buffer for background receiving. Pass NULL to disable the ring buffer.
777  * @param ringBufferSize Size of the ring buffer.
778  */
779 void UART_TransferStartRingBuffer(UART_Type *base, uart_handle_t *handle, uint8_t *ringBuffer, size_t ringBufferSize);
780 
781 /*!
782  * @brief Aborts the background transfer and uninstalls the ring buffer.
783  *
784  * This function aborts the background transfer and uninstalls the ring buffer.
785  *
786  * @param base UART peripheral base address.
787  * @param handle UART handle pointer.
788  */
789 void UART_TransferStopRingBuffer(UART_Type *base, uart_handle_t *handle);
790 
791 /*!
792  * @brief Get the length of received data in RX ring buffer.
793  *
794  * @param handle UART handle pointer.
795  * @return Length of received data in RX ring buffer.
796  */
797 size_t UART_TransferGetRxRingBufferLength(uart_handle_t *handle);
798 
799 /*!
800  * @brief Transmits a buffer of data using the interrupt method.
801  *
802  * This function sends data using an interrupt method. This is a non-blocking function, which
803  * returns directly without waiting for all data to be written to the TX register. When
804  * all data is written to the TX register in the ISR, the UART driver calls the callback
805  * function and passes the @ref kStatus_UART_TxIdle as status parameter.
806  *
807  * @note The kStatus_UART_TxIdle is passed to the upper layer when all data is written
808  * to the TX register. However, it does not ensure that all data is sent out. Before disabling the TX,
809  * check the kUART_TransmissionCompleteFlag to ensure that the TX is finished.
810  *
811  * @param base UART peripheral base address.
812  * @param handle UART handle pointer.
813  * @param xfer UART transfer structure. See  #uart_transfer_t.
814  * @retval kStatus_Success Successfully start the data transmission.
815  * @retval kStatus_UART_TxBusy Previous transmission still not finished; data not all written to TX register yet.
816  * @retval kStatus_InvalidArgument Invalid argument.
817  */
818 status_t UART_TransferSendNonBlocking(UART_Type *base, uart_handle_t *handle, uart_transfer_t *xfer);
819 
820 /*!
821  * @brief Aborts the interrupt-driven data transmit.
822  *
823  * This function aborts the interrupt-driven data sending. The user can get the remainBytes to find out
824  * how many bytes are not sent out.
825  *
826  * @param base UART peripheral base address.
827  * @param handle UART handle pointer.
828  */
829 void UART_TransferAbortSend(UART_Type *base, uart_handle_t *handle);
830 
831 /*!
832  * @brief Gets the number of bytes sent out to bus.
833  *
834  * This function gets the number of bytes sent out to bus by using the interrupt method.
835  *
836  * @param base UART peripheral base address.
837  * @param handle UART handle pointer.
838  * @param count Send bytes count.
839  * @retval kStatus_NoTransferInProgress No send in progress.
840  * @retval kStatus_InvalidArgument The parameter is invalid.
841  * @retval kStatus_Success Get successfully through the parameter \p count;
842  */
843 status_t UART_TransferGetSendCount(UART_Type *base, uart_handle_t *handle, uint32_t *count);
844 
845 /*!
846  * @brief Receives a buffer of data using an interrupt method.
847  *
848  * This function receives data using an interrupt method. This is a non-blocking function, which
849  *  returns without waiting for all data to be received.
850  * If the RX ring buffer is used and not empty, the data in the ring buffer is copied and
851  * the parameter @p receivedBytes shows how many bytes are copied from the ring buffer.
852  * After copying, if the data in the ring buffer is not enough to read, the receive
853  * request is saved by the UART driver. When the new data arrives, the receive request
854  * is serviced first. When all data is received, the UART driver notifies the upper layer
855  * through a callback function and passes the status parameter @ref kStatus_UART_RxIdle.
856  * For example, the upper layer needs 10 bytes but there are only 5 bytes in the ring buffer.
857  * The 5 bytes are copied to the xfer->data and this function returns with the
858  * parameter @p receivedBytes set to 5. For the left 5 bytes, newly arrived data is
859  * saved from the xfer->data[5]. When 5 bytes are received, the UART driver notifies the upper layer.
860  * If the RX ring buffer is not enabled, this function enables the RX and RX interrupt
861  * to receive data to the xfer->data. When all data is received, the upper layer is notified.
862  *
863  * @param base UART peripheral base address.
864  * @param handle UART handle pointer.
865  * @param xfer UART transfer structure, see #uart_transfer_t.
866  * @param receivedBytes Bytes received from the ring buffer directly.
867  * @retval kStatus_Success Successfully queue the transfer into transmit queue.
868  * @retval kStatus_UART_RxBusy Previous receive request is not finished.
869  * @retval kStatus_InvalidArgument Invalid argument.
870  */
871 status_t UART_TransferReceiveNonBlocking(UART_Type *base,
872                                          uart_handle_t *handle,
873                                          uart_transfer_t *xfer,
874                                          size_t *receivedBytes);
875 
876 /*!
877  * @brief Aborts the interrupt-driven data receiving.
878  *
879  * This function aborts the interrupt-driven data receiving. The user can get the remainBytes to know
880  * how many bytes are not received yet.
881  *
882  * @param base UART peripheral base address.
883  * @param handle UART handle pointer.
884  */
885 void UART_TransferAbortReceive(UART_Type *base, uart_handle_t *handle);
886 
887 /*!
888  * @brief Gets the number of bytes that have been received.
889  *
890  * This function gets the number of bytes that have been received.
891  *
892  * @param base UART peripheral base address.
893  * @param handle UART handle pointer.
894  * @param count Receive bytes count.
895  * @retval kStatus_NoTransferInProgress No receive in progress.
896  * @retval kStatus_InvalidArgument Parameter is invalid.
897  * @retval kStatus_Success Get successfully through the parameter \p count;
898  */
899 status_t UART_TransferGetReceiveCount(UART_Type *base, uart_handle_t *handle, uint32_t *count);
900 
901 #if defined(FSL_FEATURE_UART_HAS_FIFO) && FSL_FEATURE_UART_HAS_FIFO
902 /*!
903  * @brief Enables or disables the UART Tx FIFO.
904  *
905  * This function enables or disables the UART Tx FIFO.
906  *
907  * param base UART peripheral base address.
908  * param enable true to enable, false to disable.
909  * retval kStatus_Success Successfully turn on or turn off Tx FIFO.
910  * retval kStatus_Fail Fail to turn on or turn off Tx FIFO.
911  */
912 status_t UART_EnableTxFIFO(UART_Type *base, bool enable);
913 
914 /*!
915  * @brief Enables or disables the UART Rx FIFO.
916  *
917  * This function enables or disables the UART Rx FIFO.
918  *
919  * param base UART peripheral base address.
920  * param enable true to enable, false to disable.
921  * retval kStatus_Success Successfully turn on or turn off Rx FIFO.
922  * retval kStatus_Fail Fail to turn on or turn off Rx FIFO.
923  */
924 status_t UART_EnableRxFIFO(UART_Type *base, bool enable);
925 
926 /*!
927  * @brief Sets the rx FIFO watermark.
928  *
929  * @param base UART peripheral base address.
930  * @param water Rx FIFO watermark.
931  */
UART_SetRxFifoWatermark(UART_Type * base,uint8_t water)932 static inline void UART_SetRxFifoWatermark(UART_Type *base, uint8_t water)
933 {
934     assert((uint8_t)FSL_FEATURE_UART_FIFO_SIZEn(base) >= water);
935     base->RWFIFO = water;
936 }
937 
938 /*!
939  * @brief Sets the tx FIFO watermark.
940  *
941  * @param base UART peripheral base address.
942  * @param water Tx FIFO watermark.
943  */
UART_SetTxFifoWatermark(UART_Type * base,uint8_t water)944 static inline void UART_SetTxFifoWatermark(UART_Type *base, uint8_t water)
945 {
946     assert((uint8_t)FSL_FEATURE_UART_FIFO_SIZEn(base) >= water);
947     base->TWFIFO = water;
948 }
949 #endif /* FSL_FEATURE_UART_HAS_FIFO */
950 
951 /*!
952  * @brief UART IRQ handle function.
953  *
954  * This function handles the UART transmit and receive IRQ request.
955  *
956  * @param base UART peripheral base address.
957  * @param irqHandle UART handle pointer.
958  */
959 void UART_TransferHandleIRQ(UART_Type *base, void *irqHandle);
960 
961 /*!
962  * @brief UART Error IRQ handle function.
963  *
964  * This function handles the UART error IRQ request.
965  *
966  * @param base UART peripheral base address.
967  * @param irqHandle UART handle pointer.
968  */
969 void UART_TransferHandleErrorIRQ(UART_Type *base, void *irqHandle);
970 
971 /*! @} */
972 
973 #if defined(__cplusplus)
974 }
975 #endif
976 
977 /*! @}*/
978 
979 #endif /* FSL_UART_H_ */
980