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 /*******************************************************************************
\r
14 ******************************************************************************/
\r
16 #ifdef DEBUG_CONSOLE_TRANSFER_NON_BLOCKING
\r
17 #define UART_ADAPTER_NON_BLOCKING_MODE \
\r
18 (1U) /* Enable or disable Uart adapter non-blocking mode (1 - enable, 0 - disable) */
\r
20 #ifndef SERIAL_MANAGER_NON_BLOCKING_MODE
\r
21 #define UART_ADAPTER_NON_BLOCKING_MODE \
\r
22 (0U) /* Enable or disable Uart adapter non-blocking mode (1 - enable, 0 - disable) */
\r
24 #define UART_ADAPTER_NON_BLOCKING_MODE SERIAL_MANAGER_NON_BLOCKING_MODE
\r
28 #if (defined(UART_ADAPTER_NON_BLOCKING_MODE) && (UART_ADAPTER_NON_BLOCKING_MODE > 0U))
\r
29 #define HAL_UART_HANDLE_SIZE (90U)
\r
31 #define HAL_UART_HANDLE_SIZE (4U)
\r
34 #define HAL_UART_TRANSFER_MODE \
\r
35 (0U) /*!< Whether enable transactional function of the uart. (0 - disable, 1 - enable) \ \
\r
38 typedef void *hal_uart_handle_t;
\r
40 /*! @brief uart status */
\r
41 typedef enum _hal_uart_status
\r
43 kStatus_HAL_UartSuccess = kStatus_Success, /*!< Successfully */
\r
44 kStatus_HAL_UartTxBusy = MAKE_STATUS(kStatusGroup_HAL_UART, 1), /*!< TX busy */
\r
45 kStatus_HAL_UartRxBusy = MAKE_STATUS(kStatusGroup_HAL_UART, 2), /*!< RX busy */
\r
46 kStatus_HAL_UartTxIdle = MAKE_STATUS(kStatusGroup_HAL_UART, 3), /*!< HAL uart transmitter is idle. */
\r
47 kStatus_HAL_UartRxIdle = MAKE_STATUS(kStatusGroup_HAL_UART, 4), /*!< HAL uart receiver is idle */
\r
48 kStatus_HAL_UartBaudrateNotSupport =
\r
49 MAKE_STATUS(kStatusGroup_HAL_UART, 5), /*!< Baudrate is not support in current clock source */
\r
50 kStatus_HAL_UartProtocolError = MAKE_STATUS(
\r
51 kStatusGroup_HAL_UART,
\r
52 6), /*!< Error occurs for Noise, Framing, Parity, etc.
\r
53 For transcational transfer, The up layer needs to abort the transfer and then starts again */
\r
54 kStatus_HAL_UartError = MAKE_STATUS(kStatusGroup_HAL_UART, 7), /*!< Error occurs on HAL uart */
\r
55 } hal_uart_status_t;
\r
57 /*! @brief uart parity mode. */
\r
58 typedef enum _hal_uart_parity_mode
\r
60 kHAL_UartParityDisabled = 0x0U, /*!< Parity disabled */
\r
61 kHAL_UartParityEven = 0x1U, /*!< Parity even enabled */
\r
62 kHAL_UartParityOdd = 0x2U, /*!< Parity odd enabled */
\r
63 } hal_uart_parity_mode_t;
\r
65 /*! @brief uart stop bit count. */
\r
66 typedef enum _hal_uart_stop_bit_count
\r
68 kHAL_UartOneStopBit = 0U, /*!< One stop bit */
\r
69 kHAL_UartTwoStopBit = 1U, /*!< Two stop bits */
\r
70 } hal_uart_stop_bit_count_t;
\r
72 /*! @brief uart configuration structure. */
\r
73 typedef struct _hal_uart_config
\r
75 uint32_t srcClock_Hz; /*!< Source clock */
\r
76 uint32_t baudRate_Bps; /*!< Baud rate */
\r
77 hal_uart_parity_mode_t parityMode; /*!< Parity mode, disabled (default), even, odd */
\r
78 hal_uart_stop_bit_count_t stopBitCount; /*!< Number of stop bits, 1 stop bit (default) or 2 stop bits */
\r
79 uint8_t enableRx; /*!< Enable RX */
\r
80 uint8_t enableTx; /*!< Enable TX */
\r
81 uint8_t instance; /*!< Instance (0 - UART0, 1 - UART1, ...), detail information please refer to the
\r
82 SOC corresponding RM.
\r
83 Invalid instance value will cause initialization failure. */
\r
84 } hal_uart_config_t;
\r
86 /*! @brief uart transfer callback function. */
\r
87 typedef void (*hal_uart_transfer_callback_t)(hal_uart_handle_t handle, hal_uart_status_t status, void *callbackParam);
\r
89 /*! @brief uart transfer structure. */
\r
90 typedef struct _hal_uart_transfer
\r
92 uint8_t *data; /*!< The buffer of data to be transfer.*/
\r
93 size_t dataSize; /*!< The byte count to be transfer. */
\r
94 } hal_uart_transfer_t;
\r
96 /*******************************************************************************
\r
98 ******************************************************************************/
\r
100 #if defined(__cplusplus)
\r
102 #endif /* _cplusplus */
\r
105 * @name Initialization and deinitialization
\r
110 * @brief Initializes a uart instance with the uart handle and the user configuration structure.
\r
112 * This function configures the uart module with user-defined settings. The user can configure the configuration
\r
113 * structure. The parameter handle is a pointer to point to a memory space of size #HAL_UART_HANDLE_SIZE allocated by the
\r
115 * Example below shows how to use this API to configure the uart.
\r
117 * uint8_t g_UartHandleBuffer[HAL_UART_HANDLE_SIZE];
\r
118 * hal_uart_handle_t g_UartHandle = &g_UartHandleBuffer[0];
\r
119 * hal_uart_config_t config;
\r
120 * config.srcClock_Hz = 48000000;
\r
121 * config.baudRate_Bps = 115200U;
\r
122 * config.parityMode = kHAL_UartParityDisabled;
\r
123 * config.stopBitCount = kHAL_UartOneStopBit;
\r
124 * config.enableRx = 1;
\r
125 * config.enableTx = 1;
\r
126 * config.instance = 0;
\r
127 * HAL_UartInit(g_UartHandle, &config);
\r
130 * @param handle Pointer to point to a memory space of size #HAL_UART_HANDLE_SIZE allocated by the caller.
\r
131 * @param config Pointer to user-defined configuration structure.
\r
132 * @retval kStatus_HAL_UartBaudrateNotSupport Baudrate is not support in current clock source.
\r
133 * @retval kStatus_HAL_UartSuccess uart initialization succeed
\r
135 hal_uart_status_t HAL_UartInit(hal_uart_handle_t handle, hal_uart_config_t *config);
\r
138 * @brief Deinitializes a uart instance.
\r
140 * This function waits for TX complete, disables TX and RX, and disables the uart clock.
\r
142 * @param handle uart handle pointer.
\r
143 * @retval kStatus_HAL_UartSuccess uart de-initialization succeed
\r
145 hal_uart_status_t HAL_UartDeinit(hal_uart_handle_t handle);
\r
150 * @name Blocking bus Operations
\r
155 * @brief Reads RX data register using a blocking method.
\r
157 * This function polls the RX register, waits for the RX register to be full or for RX FIFO to
\r
158 * have data, and reads data from the RX register.
\r
160 * @note The function #HAL_UartReceiveBlocking and the function #HAL_UartTransferReceiveNonBlocking
\r
161 * cannot be used at the same time.
\r
162 * And, the function #HAL_UartTransferAbortReceive cannot be used to abort the transmission of this function.
\r
164 * @param handle uart handle pointer.
\r
165 * @param data Start address of the buffer to store the received data.
\r
166 * @param length Size of the buffer.
\r
167 * @retval kStatus_HAL_UartError An error occurred while receiving data.
\r
168 * @retval kStatus_HAL_UartParityError A parity error occurred while receiving data.
\r
169 * @retval kStatus_HAL_UartSuccess Successfully received all data.
\r
171 hal_uart_status_t HAL_UartReceiveBlocking(hal_uart_handle_t handle, uint8_t *data, size_t length);
\r
174 * @brief Writes to the TX register using a blocking method.
\r
176 * This function polls the TX register, waits for the TX register to be empty or for the TX FIFO
\r
177 * to have room and writes data to the TX buffer.
\r
179 * @note The function #HAL_UartSendBlocking and the function #HAL_UartTransferSendNonBlocking
\r
180 * cannot be used at the same time.
\r
181 * And, the function #HAL_UartTransferAbortSend cannot be used to abort the transmission of this function.
\r
183 * @param handle uart handle pointer.
\r
184 * @param data Start address of the data to write.
\r
185 * @param length Size of the data to write.
\r
186 * @retval kStatus_HAL_UartSuccess Successfully sent all data.
\r
188 hal_uart_status_t HAL_UartSendBlocking(hal_uart_handle_t handle, const uint8_t *data, size_t length);
\r
192 #if (defined(HAL_UART_TRANSFER_MODE) && (HAL_UART_TRANSFER_MODE > 0U))
\r
195 * @name Transactional
\r
196 * @note The transactional API and the functional API cannot be used at the same time. The macro
\r
197 * #HAL_UART_TRANSFER_MODE is used to set which one will be used. If #HAL_UART_TRANSFER_MODE is zero, the
\r
198 * functional API with non-blocking mode will be used. Otherwise, transactional API will be used.
\r
203 * @brief Installs a callback and callback parameter.
\r
205 * This function is used to install the callback and callback parameter for uart module.
\r
206 * When any status of the uart changed, the driver will notify the upper layer by the installed callback
\r
207 * function. And the status is also passed as status parameter when the callback is called.
\r
209 * @param handle uart handle pointer.
\r
210 * @param callback The callback function.
\r
211 * @param callbackParam The parameter of the callback function.
\r
212 * @retval kStatus_HAL_UartSuccess Successfully install the callback.
\r
214 hal_uart_status_t HAL_UartTransferInstallCallback(hal_uart_handle_t handle,
\r
215 hal_uart_transfer_callback_t callback,
\r
216 void *callbackParam);
\r
219 * @brief Receives a buffer of data using an interrupt method.
\r
221 * This function receives data using an interrupt method. This is a non-blocking function, which
\r
222 * returns directly without waiting for all data to be received.
\r
223 * The receive request is saved by the uart driver.
\r
224 * When the new data arrives, the receive request is serviced first.
\r
225 * When all data is received, the uart driver notifies the upper layer
\r
226 * through a callback function and passes the status parameter @ref kStatus_UART_RxIdle.
\r
228 * @note The function #HAL_UartReceiveBlocking and the function #HAL_UartTransferReceiveNonBlocking
\r
229 * cannot be used at the same time.
\r
231 * @param handle uart handle pointer.
\r
232 * @param transfer uart transfer structure, see #hal_uart_transfer_t.
\r
233 * @retval kStatus_HAL_UartSuccess Successfully queue the transfer into transmit queue.
\r
234 * @retval kStatus_HAL_UartRxBusy Previous receive request is not finished.
\r
235 * @retval kStatus_HAL_UartError An error occurred.
\r
237 hal_uart_status_t HAL_UartTransferReceiveNonBlocking(hal_uart_handle_t handle, hal_uart_transfer_t *transfer);
\r
240 * @brief Transmits a buffer of data using the interrupt method.
\r
242 * This function sends data using an interrupt method. This is a non-blocking function, which
\r
243 * returns directly without waiting for all data to be written to the TX register. When
\r
244 * all data is written to the TX register in the ISR, the uart driver calls the callback
\r
245 * function and passes the @ref kStatus_UART_TxIdle as status parameter.
\r
247 * @note The function #HAL_UartSendBlocking and the function #HAL_UartTransferSendNonBlocking
\r
248 * cannot be used at the same time.
\r
250 * @param handle uart handle pointer.
\r
251 * @param transfer uart transfer structure. See #hal_uart_transfer_t.
\r
252 * @retval kStatus_HAL_UartSuccess Successfully start the data transmission.
\r
253 * @retval kStatus_HAL_UartTxBusy Previous transmission still not finished; data not all written to TX register yet.
\r
254 * @retval kStatus_HAL_UartError An error occurred.
\r
256 hal_uart_status_t HAL_UartTransferSendNonBlocking(hal_uart_handle_t handle, hal_uart_transfer_t *transfer);
\r
259 * @brief Gets the number of bytes that have been received.
\r
261 * This function gets the number of bytes that have been received.
\r
263 * @param handle uart handle pointer.
\r
264 * @param count Receive bytes count.
\r
265 * @retval kStatus_HAL_UartError An error occurred.
\r
266 * @retval kStatus_Success Get successfully through the parameter \p count.
\r
268 hal_uart_status_t HAL_UartTransferGetReceiveCount(hal_uart_handle_t handle, uint32_t *count);
\r
271 * @brief Gets the number of bytes written to the uart TX register.
\r
273 * This function gets the number of bytes written to the uart TX
\r
274 * register by using the interrupt method.
\r
276 * @param handle uart handle pointer.
\r
277 * @param count Send bytes count.
\r
278 * @retval kStatus_HAL_UartError An error occurred.
\r
279 * @retval kStatus_Success Get successfully through the parameter \p count.
\r
281 hal_uart_status_t HAL_UartTransferGetSendCount(hal_uart_handle_t handle, uint32_t *count);
\r
284 * @brief Aborts the interrupt-driven data receiving.
\r
286 * This function aborts the interrupt-driven data receiving. The user can get the remainBytes to know
\r
287 * how many bytes are not received yet.
\r
289 * @note The function #HAL_UartTransferAbortReceive cannot be used to abort the transmission of
\r
290 * the function #HAL_UartReceiveBlocking.
\r
292 * @param handle uart handle pointer.
\r
293 * @retval kStatus_Success Get successfully abort the receiving.
\r
295 hal_uart_status_t HAL_UartTransferAbortReceive(hal_uart_handle_t handle);
\r
298 * @brief Aborts the interrupt-driven data sending.
\r
300 * This function aborts the interrupt-driven data sending. The user can get the remainBytes to find out
\r
301 * how many bytes are not sent out.
\r
303 * @note The function #HAL_UartTransferAbortSend cannot be used to abort the transmission of
\r
304 * the function #HAL_UartSendBlocking.
\r
306 * @param handle uart handle pointer.
\r
307 * @retval kStatus_Success Get successfully abort the sending.
\r
309 hal_uart_status_t HAL_UartTransferAbortSend(hal_uart_handle_t handle);
\r
316 * @name Functional API with non-blocking mode.
\r
317 * @note The functional API and the transactional API cannot be used at the same time. The macro
\r
318 * #HAL_UART_TRANSFER_MODE is used to set which one will be used. If #HAL_UART_TRANSFER_MODE is zero, the
\r
319 * functional API with non-blocking mode will be used. Otherwise, transactional API will be used.
\r
324 * @brief Installs a callback and callback parameter.
\r
326 * This function is used to install the callback and callback parameter for uart module.
\r
327 * When non-blocking sending or receiving finished, the adapter will notify the upper layer by the installed callback
\r
328 * function. And the status is also passed as status parameter when the callback is called.
\r
330 * @param handle uart handle pointer.
\r
331 * @param callback The callback function.
\r
332 * @param callbackParam The parameter of the callback function.
\r
333 * @retval kStatus_HAL_UartSuccess Successfully install the callback.
\r
335 hal_uart_status_t HAL_UartInstallCallback(hal_uart_handle_t handle,
\r
336 hal_uart_transfer_callback_t callback,
\r
337 void *callbackParam);
\r
340 * @brief Receives a buffer of data using an interrupt method.
\r
342 * This function receives data using an interrupt method. This is a non-blocking function, which
\r
343 * returns directly without waiting for all data to be received.
\r
344 * The receive request is saved by the uart adapter.
\r
345 * When the new data arrives, the receive request is serviced first.
\r
346 * When all data is received, the uart adapter notifies the upper layer
\r
347 * through a callback function and passes the status parameter @ref kStatus_UART_RxIdle.
\r
349 * @note The function #HAL_UartReceiveBlocking and the function #HAL_UartReceiveNonBlocking
\r
350 * cannot be used at the same time.
\r
352 * @param handle uart handle pointer.
\r
353 * @param data Start address of the data to write.
\r
354 * @param length Size of the data to write.
\r
355 * @retval kStatus_HAL_UartSuccess Successfully queue the transfer into transmit queue.
\r
356 * @retval kStatus_HAL_UartRxBusy Previous receive request is not finished.
\r
357 * @retval kStatus_HAL_UartError An error occurred.
\r
359 hal_uart_status_t HAL_UartReceiveNonBlocking(hal_uart_handle_t handle, uint8_t *data, size_t length);
\r
362 * @brief Transmits a buffer of data using the interrupt method.
\r
364 * This function sends data using an interrupt method. This is a non-blocking function, which
\r
365 * returns directly without waiting for all data to be written to the TX register. When
\r
366 * all data is written to the TX register in the ISR, the uart driver calls the callback
\r
367 * function and passes the @ref kStatus_UART_TxIdle as status parameter.
\r
369 * @note The function #HAL_UartSendBlocking and the function #HAL_UartSendNonBlocking
\r
370 * cannot be used at the same time.
\r
372 * @param handle uart handle pointer.
\r
373 * @param data Start address of the data to write.
\r
374 * @param length Size of the data to write.
\r
375 * @retval kStatus_HAL_UartSuccess Successfully start the data transmission.
\r
376 * @retval kStatus_HAL_UartTxBusy Previous transmission still not finished; data not all written to TX register yet.
\r
377 * @retval kStatus_HAL_UartError An error occurred.
\r
379 hal_uart_status_t HAL_UartSendNonBlocking(hal_uart_handle_t handle, const uint8_t *data, size_t length);
\r
382 * @brief Gets the number of bytes that have been received.
\r
384 * This function gets the number of bytes that have been received.
\r
386 * @param handle uart handle pointer.
\r
387 * @param count Receive bytes count.
\r
388 * @retval kStatus_HAL_UartError An error occurred.
\r
389 * @retval kStatus_Success Get successfully through the parameter \p count.
\r
391 hal_uart_status_t HAL_UartGetReceiveCount(hal_uart_handle_t handle, uint32_t *count);
\r
394 * @brief Gets the number of bytes written to the uart TX register.
\r
396 * This function gets the number of bytes written to the uart TX
\r
397 * register by using the interrupt method.
\r
399 * @param handle uart handle pointer.
\r
400 * @param count Send bytes count.
\r
401 * @retval kStatus_HAL_UartError An error occurred.
\r
402 * @retval kStatus_Success Get successfully through the parameter \p count.
\r
404 hal_uart_status_t HAL_UartGetSendCount(hal_uart_handle_t handle, uint32_t *count);
\r
407 * @brief Aborts the interrupt-driven data receiving.
\r
409 * This function aborts the interrupt-driven data receiving. The user can get the remainBytes to know
\r
410 * how many bytes are not received yet.
\r
412 * @note The function #HAL_UartAbortReceive cannot be used to abort the transmission of
\r
413 * the function #HAL_UartReceiveBlocking.
\r
415 * @param handle uart handle pointer.
\r
416 * @retval kStatus_Success Get successfully abort the receiving.
\r
418 hal_uart_status_t HAL_UartAbortReceive(hal_uart_handle_t handle);
\r
421 * @brief Aborts the interrupt-driven data sending.
\r
423 * This function aborts the interrupt-driven data sending. The user can get the remainBytes to find out
\r
424 * how many bytes are not sent out.
\r
426 * @note The function #HAL_UartAbortSend cannot be used to abort the transmission of
\r
427 * the function #HAL_UartSendBlocking.
\r
429 * @param handle uart handle pointer.
\r
430 * @retval kStatus_Success Get successfully abort the sending.
\r
432 hal_uart_status_t HAL_UartAbortSend(hal_uart_handle_t handle);
\r
439 * @brief uart IRQ handle function.
\r
441 * This function handles the uart transmit and receive IRQ request.
\r
443 * @param handle uart handle pointer.
\r
445 void HAL_UartIsrFunction(hal_uart_handle_t handle);
\r
447 #if defined(__cplusplus)
\r
451 #endif /* __HAL_UART_ADAPTER_H__ */
\r