3 * All rights reserved.
\r
6 * SPDX-License-Identifier: BSD-3-Clause
\r
9 #ifndef __HAL_UART_ADAPTER_H__
\r
10 #define __HAL_UART_ADAPTER_H__
\r
12 #if defined(FSL_RTOS_FREE_RTOS)
\r
13 #include "FreeRTOS.h"
\r
17 * @addtogroup UART_Adapter
\r
21 /*******************************************************************************
\r
23 ******************************************************************************/
\r
25 /*! @brief Enable or disable UART adapter non-blocking mode (1 - enable, 0 - disable) */
\r
26 #ifdef DEBUG_CONSOLE_TRANSFER_NON_BLOCKING
\r
27 #define UART_ADAPTER_NON_BLOCKING_MODE (1U)
\r
29 #ifndef SERIAL_MANAGER_NON_BLOCKING_MODE
\r
30 #define UART_ADAPTER_NON_BLOCKING_MODE (0U)
\r
32 #define UART_ADAPTER_NON_BLOCKING_MODE SERIAL_MANAGER_NON_BLOCKING_MODE
\r
36 #if defined(__GIC_PRIO_BITS)
\r
37 #define HAL_UART_ISR_PRIORITY (25U)
\r
39 #if defined(configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY)
\r
40 #define HAL_UART_ISR_PRIORITY (configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY)
\r
42 /* The default value 3 is used to support different ARM Core, such as CM0P, CM4, CM7, and CM33, etc.
\r
43 * The minimum number of priority bits implemented in the NVIC is 2 on these SOCs. The value of mininum
\r
44 * priority is 3 (2^2 - 1). So, the default value is 3.
\r
46 #define HAL_UART_ISR_PRIORITY (3U)
\r
50 #ifndef HAL_UART_ADAPTER_LOWPOWER
\r
51 #define HAL_UART_ADAPTER_LOWPOWER (0U)
\r
52 #endif /* HAL_UART_ADAPTER_LOWPOWER */
\r
54 #if (defined(UART_ADAPTER_NON_BLOCKING_MODE) && (UART_ADAPTER_NON_BLOCKING_MODE > 0U))
\r
55 #define HAL_UART_HANDLE_SIZE (90U + HAL_UART_ADAPTER_LOWPOWER * 16U)
\r
57 #define HAL_UART_HANDLE_SIZE (4U + HAL_UART_ADAPTER_LOWPOWER * 16U)
\r
60 /*! @brief Whether enable transactional function of the UART. (0 - disable, 1 - enable) */
\r
61 #define HAL_UART_TRANSFER_MODE (0U)
\r
63 typedef void *hal_uart_handle_t;
\r
65 /*! @brief UART status */
\r
66 typedef enum _hal_uart_status
\r
68 kStatus_HAL_UartSuccess = kStatus_Success, /*!< Successfully */
\r
69 kStatus_HAL_UartTxBusy = MAKE_STATUS(kStatusGroup_HAL_UART, 1), /*!< TX busy */
\r
70 kStatus_HAL_UartRxBusy = MAKE_STATUS(kStatusGroup_HAL_UART, 2), /*!< RX busy */
\r
71 kStatus_HAL_UartTxIdle = MAKE_STATUS(kStatusGroup_HAL_UART, 3), /*!< HAL UART transmitter is idle. */
\r
72 kStatus_HAL_UartRxIdle = MAKE_STATUS(kStatusGroup_HAL_UART, 4), /*!< HAL UART receiver is idle */
\r
73 kStatus_HAL_UartBaudrateNotSupport =
\r
74 MAKE_STATUS(kStatusGroup_HAL_UART, 5), /*!< Baudrate is not support in current clock source */
\r
75 kStatus_HAL_UartProtocolError = MAKE_STATUS(
\r
76 kStatusGroup_HAL_UART,
\r
77 6), /*!< Error occurs for Noise, Framing, Parity, etc.
\r
78 For transactional transfer, The up layer needs to abort the transfer and then starts again */
\r
79 kStatus_HAL_UartError = MAKE_STATUS(kStatusGroup_HAL_UART, 7), /*!< Error occurs on HAL UART */
\r
80 } hal_uart_status_t;
\r
82 /*! @brief UART parity mode. */
\r
83 typedef enum _hal_uart_parity_mode
\r
85 kHAL_UartParityDisabled = 0x0U, /*!< Parity disabled */
\r
86 kHAL_UartParityEven = 0x1U, /*!< Parity even enabled */
\r
87 kHAL_UartParityOdd = 0x2U, /*!< Parity odd enabled */
\r
88 } hal_uart_parity_mode_t;
\r
90 /*! @brief UART stop bit count. */
\r
91 typedef enum _hal_uart_stop_bit_count
\r
93 kHAL_UartOneStopBit = 0U, /*!< One stop bit */
\r
94 kHAL_UartTwoStopBit = 1U, /*!< Two stop bits */
\r
95 } hal_uart_stop_bit_count_t;
\r
97 /*! @brief UART configuration structure. */
\r
98 typedef struct _hal_uart_config
\r
100 uint32_t srcClock_Hz; /*!< Source clock */
\r
101 uint32_t baudRate_Bps; /*!< Baud rate */
\r
102 hal_uart_parity_mode_t parityMode; /*!< Parity mode, disabled (default), even, odd */
\r
103 hal_uart_stop_bit_count_t stopBitCount; /*!< Number of stop bits, 1 stop bit (default) or 2 stop bits */
\r
104 uint8_t enableRx; /*!< Enable RX */
\r
105 uint8_t enableTx; /*!< Enable TX */
\r
106 uint8_t instance; /*!< Instance (0 - UART0, 1 - UART1, ...), detail information please refer to the
\r
107 SOC corresponding RM.
\r
108 Invalid instance value will cause initialization failure. */
\r
109 } hal_uart_config_t;
\r
111 /*! @brief UART transfer callback function. */
\r
112 typedef void (*hal_uart_transfer_callback_t)(hal_uart_handle_t handle, hal_uart_status_t status, void *callbackParam);
\r
114 /*! @brief UART transfer structure. */
\r
115 typedef struct _hal_uart_transfer
\r
117 uint8_t *data; /*!< The buffer of data to be transfer.*/
\r
118 size_t dataSize; /*!< The byte count to be transfer. */
\r
119 } hal_uart_transfer_t;
\r
121 /*******************************************************************************
\r
123 ******************************************************************************/
\r
125 #if defined(__cplusplus)
\r
127 #endif /* _cplusplus */
\r
130 * @name Initialization and deinitialization
\r
135 * @brief Initializes a UART instance with the UART handle and the user configuration structure.
\r
137 * This function configures the UART module with user-defined settings. The user can configure the configuration
\r
138 * structure. The parameter handle is a pointer to point to a memory space of size #HAL_UART_HANDLE_SIZE allocated by
\r
139 * the caller. Example below shows how to use this API to configure the UART.
\r
141 * uint32_t g_UartHandleBuffer[((HAL_UART_HANDLE_SIZE + sizeof(uint32_t) - 1) / sizeof(uitn32_t))];
\r
142 * hal_uart_handle_t g_UartHandle = (hal_uart_handle_t)&g_UartHandleBuffer[0];
\r
143 * hal_uart_config_t config;
\r
144 * config.srcClock_Hz = 48000000;
\r
145 * config.baudRate_Bps = 115200U;
\r
146 * config.parityMode = kHAL_UartParityDisabled;
\r
147 * config.stopBitCount = kHAL_UartOneStopBit;
\r
148 * config.enableRx = 1;
\r
149 * config.enableTx = 1;
\r
150 * config.instance = 0;
\r
151 * HAL_UartInit(g_UartHandle, &config);
\r
154 * @param handle Pointer to point to a memory space of size #HAL_UART_HANDLE_SIZE allocated by the caller.
\r
155 * The handle should be 4 byte aligned, because unaligned access does not support on some devices.
\r
156 * @param config Pointer to user-defined configuration structure.
\r
157 * @retval kStatus_HAL_UartBaudrateNotSupport Baudrate is not support in current clock source.
\r
158 * @retval kStatus_HAL_UartSuccess UART initialization succeed
\r
160 hal_uart_status_t HAL_UartInit(hal_uart_handle_t handle, hal_uart_config_t *config);
\r
163 * @brief Deinitializes a UART instance.
\r
165 * This function waits for TX complete, disables TX and RX, and disables the UART clock.
\r
167 * @param handle UART handle pointer.
\r
168 * @retval kStatus_HAL_UartSuccess UART de-initialization succeed
\r
170 hal_uart_status_t HAL_UartDeinit(hal_uart_handle_t handle);
\r
175 * @name Blocking bus Operations
\r
180 * @brief Reads RX data register using a blocking method.
\r
182 * This function polls the RX register, waits for the RX register to be full or for RX FIFO to
\r
183 * have data, and reads data from the RX register.
\r
185 * @note The function #HAL_UartReceiveBlocking and the function #HAL_UartTransferReceiveNonBlocking
\r
186 * cannot be used at the same time.
\r
187 * And, the function #HAL_UartTransferAbortReceive cannot be used to abort the transmission of this function.
\r
189 * @param handle UART handle pointer.
\r
190 * @param data Start address of the buffer to store the received data.
\r
191 * @param length Size of the buffer.
\r
192 * @retval kStatus_HAL_UartError An error occurred while receiving data.
\r
193 * @retval kStatus_HAL_UartParityError A parity error occurred while receiving data.
\r
194 * @retval kStatus_HAL_UartSuccess Successfully received all data.
\r
196 hal_uart_status_t HAL_UartReceiveBlocking(hal_uart_handle_t handle, uint8_t *data, size_t length);
\r
199 * @brief Writes to the TX register using a blocking method.
\r
201 * This function polls the TX register, waits for the TX register to be empty or for the TX FIFO
\r
202 * to have room and writes data to the TX buffer.
\r
204 * @note The function #HAL_UartSendBlocking and the function #HAL_UartTransferSendNonBlocking
\r
205 * cannot be used at the same time.
\r
206 * And, the function #HAL_UartTransferAbortSend cannot be used to abort the transmission of this function.
\r
208 * @param handle UART handle pointer.
\r
209 * @param data Start address of the data to write.
\r
210 * @param length Size of the data to write.
\r
211 * @retval kStatus_HAL_UartSuccess Successfully sent all data.
\r
213 hal_uart_status_t HAL_UartSendBlocking(hal_uart_handle_t handle, const uint8_t *data, size_t length);
\r
217 #if (defined(UART_ADAPTER_NON_BLOCKING_MODE) && (UART_ADAPTER_NON_BLOCKING_MODE > 0U))
\r
218 #if (defined(HAL_UART_TRANSFER_MODE) && (HAL_UART_TRANSFER_MODE > 0U))
\r
221 * @name Transactional
\r
222 * @note The transactional API and the functional API cannot be used at the same time. The macro
\r
223 * #HAL_UART_TRANSFER_MODE is used to set which one will be used. If #HAL_UART_TRANSFER_MODE is zero, the
\r
224 * functional API with non-blocking mode will be used. Otherwise, transactional API will be used.
\r
229 * @brief Installs a callback and callback parameter.
\r
231 * This function is used to install the callback and callback parameter for UART module.
\r
232 * When any status of the UART changed, the driver will notify the upper layer by the installed callback
\r
233 * function. And the status is also passed as status parameter when the callback is called.
\r
235 * @param handle UART handle pointer.
\r
236 * @param callback The callback function.
\r
237 * @param callbackParam The parameter of the callback function.
\r
238 * @retval kStatus_HAL_UartSuccess Successfully install the callback.
\r
240 hal_uart_status_t HAL_UartTransferInstallCallback(hal_uart_handle_t handle,
\r
241 hal_uart_transfer_callback_t callback,
\r
242 void *callbackParam);
\r
245 * @brief Receives a buffer of data using an interrupt method.
\r
247 * This function receives data using an interrupt method. This is a non-blocking function, which
\r
248 * returns directly without waiting for all data to be received.
\r
249 * The receive request is saved by the UART driver.
\r
250 * When the new data arrives, the receive request is serviced first.
\r
251 * When all data is received, the UART driver notifies the upper layer
\r
252 * through a callback function and passes the status parameter @ref kStatus_UART_RxIdle.
\r
254 * @note The function #HAL_UartReceiveBlocking and the function #HAL_UartTransferReceiveNonBlocking
\r
255 * cannot be used at the same time.
\r
257 * @param handle UART handle pointer.
\r
258 * @param transfer UART transfer structure, see #hal_uart_transfer_t.
\r
259 * @retval kStatus_HAL_UartSuccess Successfully queue the transfer into transmit queue.
\r
260 * @retval kStatus_HAL_UartRxBusy Previous receive request is not finished.
\r
261 * @retval kStatus_HAL_UartError An error occurred.
\r
263 hal_uart_status_t HAL_UartTransferReceiveNonBlocking(hal_uart_handle_t handle, hal_uart_transfer_t *transfer);
\r
266 * @brief Transmits a buffer of data using the interrupt method.
\r
268 * This function sends data using an interrupt method. This is a non-blocking function, which
\r
269 * returns directly without waiting for all data to be written to the TX register. When
\r
270 * all data is written to the TX register in the ISR, the UART driver calls the callback
\r
271 * function and passes the @ref kStatus_UART_TxIdle as status parameter.
\r
273 * @note The function #HAL_UartSendBlocking and the function #HAL_UartTransferSendNonBlocking
\r
274 * cannot be used at the same time.
\r
276 * @param handle UART handle pointer.
\r
277 * @param transfer UART transfer structure. See #hal_uart_transfer_t.
\r
278 * @retval kStatus_HAL_UartSuccess Successfully start the data transmission.
\r
279 * @retval kStatus_HAL_UartTxBusy Previous transmission still not finished; data not all written to TX register yet.
\r
280 * @retval kStatus_HAL_UartError An error occurred.
\r
282 hal_uart_status_t HAL_UartTransferSendNonBlocking(hal_uart_handle_t handle, hal_uart_transfer_t *transfer);
\r
285 * @brief Gets the number of bytes that have been received.
\r
287 * This function gets the number of bytes that have been received.
\r
289 * @param handle UART handle pointer.
\r
290 * @param count Receive bytes count.
\r
291 * @retval kStatus_HAL_UartError An error occurred.
\r
292 * @retval kStatus_Success Get successfully through the parameter \p count.
\r
294 hal_uart_status_t HAL_UartTransferGetReceiveCount(hal_uart_handle_t handle, uint32_t *count);
\r
297 * @brief Gets the number of bytes written to the UART TX register.
\r
299 * This function gets the number of bytes written to the UART TX
\r
300 * register by using the interrupt method.
\r
302 * @param handle UART handle pointer.
\r
303 * @param count Send bytes count.
\r
304 * @retval kStatus_HAL_UartError An error occurred.
\r
305 * @retval kStatus_Success Get successfully through the parameter \p count.
\r
307 hal_uart_status_t HAL_UartTransferGetSendCount(hal_uart_handle_t handle, uint32_t *count);
\r
310 * @brief Aborts the interrupt-driven data receiving.
\r
312 * This function aborts the interrupt-driven data receiving. The user can get the remainBytes to know
\r
313 * how many bytes are not received yet.
\r
315 * @note The function #HAL_UartTransferAbortReceive cannot be used to abort the transmission of
\r
316 * the function #HAL_UartReceiveBlocking.
\r
318 * @param handle UART handle pointer.
\r
319 * @retval kStatus_Success Get successfully abort the receiving.
\r
321 hal_uart_status_t HAL_UartTransferAbortReceive(hal_uart_handle_t handle);
\r
324 * @brief Aborts the interrupt-driven data sending.
\r
326 * This function aborts the interrupt-driven data sending. The user can get the remainBytes to find out
\r
327 * how many bytes are not sent out.
\r
329 * @note The function #HAL_UartTransferAbortSend cannot be used to abort the transmission of
\r
330 * the function #HAL_UartSendBlocking.
\r
332 * @param handle UART handle pointer.
\r
333 * @retval kStatus_Success Get successfully abort the sending.
\r
335 hal_uart_status_t HAL_UartTransferAbortSend(hal_uart_handle_t handle);
\r
342 * @name Functional API with non-blocking mode.
\r
343 * @note The functional API and the transactional API cannot be used at the same time. The macro
\r
344 * #HAL_UART_TRANSFER_MODE is used to set which one will be used. If #HAL_UART_TRANSFER_MODE is zero, the
\r
345 * functional API with non-blocking mode will be used. Otherwise, transactional API will be used.
\r
350 * @brief Installs a callback and callback parameter.
\r
352 * This function is used to install the callback and callback parameter for UART module.
\r
353 * When non-blocking sending or receiving finished, the adapter will notify the upper layer by the installed callback
\r
354 * function. And the status is also passed as status parameter when the callback is called.
\r
356 * @param handle UART handle pointer.
\r
357 * @param callback The callback function.
\r
358 * @param callbackParam The parameter of the callback function.
\r
359 * @retval kStatus_HAL_UartSuccess Successfully install the callback.
\r
361 hal_uart_status_t HAL_UartInstallCallback(hal_uart_handle_t handle,
\r
362 hal_uart_transfer_callback_t callback,
\r
363 void *callbackParam);
\r
366 * @brief Receives a buffer of data using an interrupt method.
\r
368 * This function receives data using an interrupt method. This is a non-blocking function, which
\r
369 * returns directly without waiting for all data to be received.
\r
370 * The receive request is saved by the UART adapter.
\r
371 * When the new data arrives, the receive request is serviced first.
\r
372 * When all data is received, the UART adapter notifies the upper layer
\r
373 * through a callback function and passes the status parameter @ref kStatus_UART_RxIdle.
\r
375 * @note The function #HAL_UartReceiveBlocking and the function #HAL_UartReceiveNonBlocking
\r
376 * cannot be used at the same time.
\r
378 * @param handle UART handle pointer.
\r
379 * @param data Start address of the data to write.
\r
380 * @param length Size of the data to write.
\r
381 * @retval kStatus_HAL_UartSuccess Successfully queue the transfer into transmit queue.
\r
382 * @retval kStatus_HAL_UartRxBusy Previous receive request is not finished.
\r
383 * @retval kStatus_HAL_UartError An error occurred.
\r
385 hal_uart_status_t HAL_UartReceiveNonBlocking(hal_uart_handle_t handle, uint8_t *data, size_t length);
\r
388 * @brief Transmits a buffer of data using the interrupt method.
\r
390 * This function sends data using an interrupt method. This is a non-blocking function, which
\r
391 * returns directly without waiting for all data to be written to the TX register. When
\r
392 * all data is written to the TX register in the ISR, the UART driver calls the callback
\r
393 * function and passes the @ref kStatus_UART_TxIdle as status parameter.
\r
395 * @note The function #HAL_UartSendBlocking and the function #HAL_UartSendNonBlocking
\r
396 * cannot be used at the same time.
\r
398 * @param handle UART handle pointer.
\r
399 * @param data Start address of the data to write.
\r
400 * @param length Size of the data to write.
\r
401 * @retval kStatus_HAL_UartSuccess Successfully start the data transmission.
\r
402 * @retval kStatus_HAL_UartTxBusy Previous transmission still not finished; data not all written to TX register yet.
\r
403 * @retval kStatus_HAL_UartError An error occurred.
\r
405 hal_uart_status_t HAL_UartSendNonBlocking(hal_uart_handle_t handle, uint8_t *data, size_t length);
\r
408 * @brief Gets the number of bytes that have been received.
\r
410 * This function gets the number of bytes that have been received.
\r
412 * @param handle UART handle pointer.
\r
413 * @param count Receive bytes count.
\r
414 * @retval kStatus_HAL_UartError An error occurred.
\r
415 * @retval kStatus_Success Get successfully through the parameter \p count.
\r
417 hal_uart_status_t HAL_UartGetReceiveCount(hal_uart_handle_t handle, uint32_t *reCount);
\r
420 * @brief Gets the number of bytes written to the UART TX register.
\r
422 * This function gets the number of bytes written to the UART TX
\r
423 * register by using the interrupt method.
\r
425 * @param handle UART handle pointer.
\r
426 * @param count Send bytes count.
\r
427 * @retval kStatus_HAL_UartError An error occurred.
\r
428 * @retval kStatus_Success Get successfully through the parameter \p count.
\r
430 hal_uart_status_t HAL_UartGetSendCount(hal_uart_handle_t handle, uint32_t *seCount);
\r
433 * @brief Aborts the interrupt-driven data receiving.
\r
435 * This function aborts the interrupt-driven data receiving. The user can get the remainBytes to know
\r
436 * how many bytes are not received yet.
\r
438 * @note The function #HAL_UartAbortReceive cannot be used to abort the transmission of
\r
439 * the function #HAL_UartReceiveBlocking.
\r
441 * @param handle UART handle pointer.
\r
442 * @retval kStatus_Success Get successfully abort the receiving.
\r
444 hal_uart_status_t HAL_UartAbortReceive(hal_uart_handle_t handle);
\r
447 * @brief Aborts the interrupt-driven data sending.
\r
449 * This function aborts the interrupt-driven data sending. The user can get the remainBytes to find out
\r
450 * how many bytes are not sent out.
\r
452 * @note The function #HAL_UartAbortSend cannot be used to abort the transmission of
\r
453 * the function #HAL_UartSendBlocking.
\r
455 * @param handle UART handle pointer.
\r
456 * @retval kStatus_Success Get successfully abort the sending.
\r
458 hal_uart_status_t HAL_UartAbortSend(hal_uart_handle_t handle);
\r
466 * @brief Prepares to enter low power consumption.
\r
468 * This function is used to prepare to enter low power consumption.
\r
470 * @param handle UART handle pointer.
\r
471 * @retval kStatus_HAL_UartSuccess Successful operation.
\r
472 * @retval kStatus_HAL_UartError An error occurred.
\r
474 hal_uart_status_t HAL_UartEnterLowpower(hal_uart_handle_t handle);
\r
477 * @brief Restores from low power consumption.
\r
479 * This function is used to restore from low power consumption.
\r
481 * @param handle UART handle pointer.
\r
482 * @retval kStatus_HAL_UartSuccess Successful operation.
\r
483 * @retval kStatus_HAL_UartError An error occurred.
\r
485 hal_uart_status_t HAL_UartExitLowpower(hal_uart_handle_t handle);
\r
487 #if (defined(UART_ADAPTER_NON_BLOCKING_MODE) && (UART_ADAPTER_NON_BLOCKING_MODE > 0U))
\r
489 * @brief UART IRQ handle function.
\r
491 * This function handles the UART transmit and receive IRQ request.
\r
493 * @param handle UART handle pointer.
\r
495 void HAL_UartIsrFunction(hal_uart_handle_t handle);
\r
498 #if defined(__cplusplus)
\r
502 #endif /* __HAL_UART_ADAPTER_H__ */
\r