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
