diff options
Diffstat (limited to 'FreeRTOS/Demo/Safer_Interrupts_M33F_NXP_LPC55S69_MCUXpresso/NXP_Code/component/uart/fsl_adapter_uart.h')
| -rw-r--r-- | FreeRTOS/Demo/Safer_Interrupts_M33F_NXP_LPC55S69_MCUXpresso/NXP_Code/component/uart/fsl_adapter_uart.h | 812 |
1 files changed, 812 insertions, 0 deletions
diff --git a/FreeRTOS/Demo/Safer_Interrupts_M33F_NXP_LPC55S69_MCUXpresso/NXP_Code/component/uart/fsl_adapter_uart.h b/FreeRTOS/Demo/Safer_Interrupts_M33F_NXP_LPC55S69_MCUXpresso/NXP_Code/component/uart/fsl_adapter_uart.h new file mode 100644 index 000000000..7d8bc4441 --- /dev/null +++ b/FreeRTOS/Demo/Safer_Interrupts_M33F_NXP_LPC55S69_MCUXpresso/NXP_Code/component/uart/fsl_adapter_uart.h @@ -0,0 +1,812 @@ +/* + * Copyright 2018-2020 NXP + * All rights reserved. + * + * + * SPDX-License-Identifier: BSD-3-Clause + */ + +#ifndef __HAL_UART_ADAPTER_H__ +#define __HAL_UART_ADAPTER_H__ + +#include "fsl_common.h" +#if defined(SDK_OS_FREE_RTOS) +#include "FreeRTOS.h" +#endif + +/*! + * @addtogroup UART_Adapter + * @{ + */ + +/******************************************************************************* + * Definitions + ******************************************************************************/ + +/*! @brief Enable or disable UART adapter non-blocking mode (1 - enable, 0 - disable) */ +#ifdef DEBUG_CONSOLE_TRANSFER_NON_BLOCKING +#define UART_ADAPTER_NON_BLOCKING_MODE (1U) +#else +#ifndef SERIAL_MANAGER_NON_BLOCKING_MODE +#define UART_ADAPTER_NON_BLOCKING_MODE (0U) +#else +#define UART_ADAPTER_NON_BLOCKING_MODE SERIAL_MANAGER_NON_BLOCKING_MODE +#endif +#endif + +#if defined(__GIC_PRIO_BITS) +#ifndef HAL_UART_ISR_PRIORITY +#define HAL_UART_ISR_PRIORITY (25U) +#endif +#else +#if defined(configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY) +#ifndef HAL_UART_ISR_PRIORITY +#define HAL_UART_ISR_PRIORITY (configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY) +#endif +#else +/* The default value 3 is used to support different ARM Core, such as CM0P, CM4, CM7, and CM33, etc. + * The minimum number of priority bits implemented in the NVIC is 2 on these SOCs. The value of mininum + * priority is 3 (2^2 - 1). So, the default value is 3. + */ +#ifndef HAL_UART_ISR_PRIORITY +#define HAL_UART_ISR_PRIORITY (3U) +#endif +#endif +#endif + +#ifndef HAL_UART_ADAPTER_LOWPOWER +#define HAL_UART_ADAPTER_LOWPOWER (0U) +#endif /* HAL_UART_ADAPTER_LOWPOWER */ + +#ifndef HAL_UART_ADAPTER_FIFO +#define HAL_UART_ADAPTER_FIFO (0U) +#endif /* HAL_UART_ADAPTER_FIFO */ + +#ifndef HAL_UART_DMA_ENABLE +#define HAL_UART_DMA_ENABLE (0U) +#endif /* HAL_UART_DMA_ENABLE */ + +/*! @brief Definition of uart dma adapter software idleline detection timeout value in ms. */ +#ifndef HAL_UART_DMA_IDLELINE_TIMEOUT +#define HAL_UART_DMA_IDLELINE_TIMEOUT (1U) +#endif /* HAL_UART_DMA_IDLELINE_TIMEOUT */ + +/*! @brief Definition of uart adapter handle size. */ +#if (defined(UART_ADAPTER_NON_BLOCKING_MODE) && (UART_ADAPTER_NON_BLOCKING_MODE > 0U)) +#define HAL_UART_HANDLE_SIZE (92U + HAL_UART_ADAPTER_LOWPOWER * 16U + HAL_UART_DMA_ENABLE * 4) +#define HAL_UART_BLOCK_HANDLE_SIZE (8U + HAL_UART_ADAPTER_LOWPOWER * 16U + HAL_UART_DMA_ENABLE * 4) +#else +#define HAL_UART_HANDLE_SIZE (8U + HAL_UART_ADAPTER_LOWPOWER * 16U + HAL_UART_DMA_ENABLE * 4) +#endif + +/*! @brief Definition of uart dma adapter handle size. */ +#if (defined(HAL_UART_DMA_ENABLE) && (HAL_UART_DMA_ENABLE > 0U)) +#if (defined(FSL_FEATURE_SOC_DMA_COUNT) && (FSL_FEATURE_SOC_DMA_COUNT > 0U)) +#define HAL_UART_DMA_HANDLE_SIZE (124U) +#elif (defined(FSL_FEATURE_SOC_EDMA_COUNT) && (FSL_FEATURE_SOC_EDMA_COUNT > 0U)) +#define HAL_UART_DMA_HANDLE_SIZE (140U) +#else +#error This SOC does not have DMA or EDMA available! +#endif +#endif /* HAL_UART_DMA_ENABLE */ + +/*! + * @brief Defines the uart handle + * + * This macro is used to define a 4 byte aligned uart handle. + * Then use "(hal_uart_handle_t)name" to get the uart handle. + * + * The macro should be global and could be optional. You could also define uart handle by yourself. + * + * This is an example, + * @code + * UART_HANDLE_DEFINE(uartHandle); + * @endcode + * + * @param name The name string of the uart handle. + */ +#define UART_HANDLE_DEFINE(name) uint32_t name[((HAL_UART_HANDLE_SIZE + sizeof(uint32_t) - 1U) / sizeof(uint32_t))] + +#if (defined(HAL_UART_DMA_ENABLE) && (HAL_UART_DMA_ENABLE > 0U)) +#define UART_DMA_HANDLE_DEFINE(name) \ + uint32_t name[((HAL_UART_DMA_HANDLE_SIZE + sizeof(uint32_t) - 1U) / sizeof(uint32_t))] +#endif + +/*! @brief Whether enable transactional function of the UART. (0 - disable, 1 - enable) */ +#ifndef HAL_UART_TRANSFER_MODE +#define HAL_UART_TRANSFER_MODE (0U) +#endif + +/*! @brief The handle of uart adapter. */ +typedef void *hal_uart_handle_t; + +/*! @brief The handle of uart dma adapter. */ +typedef void *hal_uart_dma_handle_t; + +/*! @brief UART status */ +typedef enum _hal_uart_status +{ + kStatus_HAL_UartSuccess = kStatus_Success, /*!< Successfully */ + kStatus_HAL_UartTxBusy = MAKE_STATUS(kStatusGroup_HAL_UART, 1), /*!< TX busy */ + kStatus_HAL_UartRxBusy = MAKE_STATUS(kStatusGroup_HAL_UART, 2), /*!< RX busy */ + kStatus_HAL_UartTxIdle = MAKE_STATUS(kStatusGroup_HAL_UART, 3), /*!< HAL UART transmitter is idle. */ + kStatus_HAL_UartRxIdle = MAKE_STATUS(kStatusGroup_HAL_UART, 4), /*!< HAL UART receiver is idle */ + kStatus_HAL_UartBaudrateNotSupport = + MAKE_STATUS(kStatusGroup_HAL_UART, 5), /*!< Baudrate is not support in current clock source */ + kStatus_HAL_UartProtocolError = MAKE_STATUS( + kStatusGroup_HAL_UART, + 6), /*!< Error occurs for Noise, Framing, Parity, etc. + For transactional transfer, The up layer needs to abort the transfer and then starts again */ + kStatus_HAL_UartError = MAKE_STATUS(kStatusGroup_HAL_UART, 7), /*!< Error occurs on HAL UART */ +} hal_uart_status_t; + +/*! @brief UART parity mode. */ +typedef enum _hal_uart_parity_mode +{ + kHAL_UartParityDisabled = 0x0U, /*!< Parity disabled */ + kHAL_UartParityEven = 0x2U, /*!< Parity even enabled */ + kHAL_UartParityOdd = 0x3U, /*!< Parity odd enabled */ +} hal_uart_parity_mode_t; + +#if (defined(UART_ADAPTER_NON_BLOCKING_MODE) && (UART_ADAPTER_NON_BLOCKING_MODE > 0U)) +/*! @brief UART Block Mode. */ +typedef enum _hal_uart_block_mode +{ + kHAL_UartNonBlockMode = 0x0U, /*!< Uart NonBlock Mode */ + kHAL_UartBlockMode = 0x1U, /*!< Uart Block Mode */ +} hal_uart_block_mode_t; +#endif /* UART_ADAPTER_NON_BLOCKING_MODE */ + +/*! @brief UART stop bit count. */ +typedef enum _hal_uart_stop_bit_count +{ + kHAL_UartOneStopBit = 0U, /*!< One stop bit */ + kHAL_UartTwoStopBit = 1U, /*!< Two stop bits */ +} hal_uart_stop_bit_count_t; + +/*! @brief UART configuration structure. */ +typedef struct _hal_uart_config +{ + uint32_t srcClock_Hz; /*!< Source clock */ + uint32_t baudRate_Bps; /*!< Baud rate */ + hal_uart_parity_mode_t parityMode; /*!< Parity mode, disabled (default), even, odd */ + hal_uart_stop_bit_count_t stopBitCount; /*!< Number of stop bits, 1 stop bit (default) or 2 stop bits */ + uint8_t enableRx; /*!< Enable RX */ + uint8_t enableTx; /*!< Enable TX */ + uint8_t enableRxRTS; /*!< Enable RX RTS */ + uint8_t enableTxCTS; /*!< Enable TX CTS */ + uint8_t instance; /*!< Instance (0 - UART0, 1 - UART1, ...), detail information please refer to the + SOC corresponding RM. + Invalid instance value will cause initialization failure. */ +#if (defined(UART_ADAPTER_NON_BLOCKING_MODE) && (UART_ADAPTER_NON_BLOCKING_MODE > 0U)) + hal_uart_block_mode_t mode; /*!< Uart block mode */ +#endif /* UART_ADAPTER_NON_BLOCKING_MODE */ +#if (defined(HAL_UART_ADAPTER_FIFO) && (HAL_UART_ADAPTER_FIFO > 0u)) + uint8_t txFifoWatermark; + uint8_t rxFifoWatermark; +#endif +} hal_uart_config_t; + +#if (defined(HAL_UART_DMA_ENABLE) && (HAL_UART_DMA_ENABLE > 0U)) +/*! @brief UART DMA status */ +typedef enum _hal_uart_dma_status +{ + kStatus_HAL_UartDmaSuccess = 0U, + kStatus_HAL_UartDmaRxIdle = (1U << 1U), + kStatus_HAL_UartDmaRxBusy = (1U << 2U), + kStatus_HAL_UartDmaTxIdle = (1U << 3U), + kStatus_HAL_UartDmaTxBusy = (1U << 4U), + kStatus_HAL_UartDmaIdleline = (1U << 5U), + kStatus_HAL_UartDmaError = (1U << 6U), +} hal_uart_dma_status_t; + +typedef struct _hal_uart_dma_config_t +{ + uint8_t uart_instance; + uint8_t dma_instance; + uint8_t rx_channel; + uint8_t tx_channel; +#if defined(FSL_FEATURE_SOC_DMAMUX_COUNT) && FSL_FEATURE_SOC_DMAMUX_COUNT + uint8_t dma_mux_instance; + dma_request_source_t rx_request; + dma_request_source_t tx_request; +#endif +#if defined(FSL_FEATURE_EDMA_HAS_CHANNEL_MUX) && FSL_FEATURE_EDMA_HAS_CHANNEL_MUX + uint32_t dma_rx_channel_mux; + uint32_t dma_tx_channel_mux; +#endif +} hal_uart_dma_config_t; +#endif /* HAL_UART_DMA_ENABLE */ + +/*! @brief UART transfer callback function. */ +typedef void (*hal_uart_transfer_callback_t)(hal_uart_handle_t handle, hal_uart_status_t status, void *callbackParam); + +#if (defined(HAL_UART_DMA_ENABLE) && (HAL_UART_DMA_ENABLE > 0U)) +typedef struct _dma_callback_msg +{ + hal_uart_dma_status_t status; + uint8_t *data; + uint32_t dataSize; +} hal_dma_callback_msg_t; + +/*! @brief UART transfer callback function. */ +typedef void (*hal_uart_dma_transfer_callback_t)(hal_uart_dma_handle_t handle, + hal_dma_callback_msg_t *msg, + void *callbackParam); +#endif /* HAL_UART_DMA_ENABLE */ + +/*! @brief UART transfer structure. */ +typedef struct _hal_uart_transfer +{ + uint8_t *data; /*!< The buffer of data to be transfer.*/ + size_t dataSize; /*!< The byte count to be transfer. */ +} hal_uart_transfer_t; + +/******************************************************************************* + * API + ******************************************************************************/ + +#if defined(__cplusplus) +extern "C" { +#endif /* _cplusplus */ + +/*! + * @name Initialization and deinitialization + * @{ + */ + +/*! + * @brief Initializes a UART instance with the UART handle and the user configuration structure. + * + * This function configures the UART module with user-defined settings. The user can configure the configuration + * structure. The parameter handle is a pointer to point to a memory space of size #HAL_UART_HANDLE_SIZE allocated by + * the caller. Example below shows how to use this API to configure the UART. + * @code + * UART_HANDLE_DEFINE(g_UartHandle); + * hal_uart_config_t config; + * config.srcClock_Hz = 48000000; + * config.baudRate_Bps = 115200U; + * config.parityMode = kHAL_UartParityDisabled; + * config.stopBitCount = kHAL_UartOneStopBit; + * config.enableRx = 1; + * config.enableTx = 1; + * config.enableRxRTS = 0; + * config.enableTxCTS = 0; + * config.instance = 0; + * HAL_UartInit((hal_uart_handle_t)g_UartHandle, &config); + * @endcode + * + * @param handle Pointer to point to a memory space of size #HAL_UART_HANDLE_SIZE allocated by the caller. + * The handle should be 4 byte aligned, because unaligned access doesn't be supported on some devices. + * You can define the handle in the following two ways: + * #UART_HANDLE_DEFINE(handle); + * or + * uint32_t handle[((HAL_UART_HANDLE_SIZE + sizeof(uint32_t) - 1U) / sizeof(uint32_t))]; + * @param config Pointer to user-defined configuration structure. + * @retval kStatus_HAL_UartBaudrateNotSupport Baudrate is not support in current clock source. + * @retval kStatus_HAL_UartSuccess UART initialization succeed + */ +hal_uart_status_t HAL_UartInit(hal_uart_handle_t handle, const hal_uart_config_t *config); + +/*! + * @brief Deinitializes a UART instance. + * + * This function waits for TX complete, disables TX and RX, and disables the UART clock. + * + * @param handle UART handle pointer. + * @retval kStatus_HAL_UartSuccess UART de-initialization succeed + */ +hal_uart_status_t HAL_UartDeinit(hal_uart_handle_t handle); + +/*! @}*/ + +/*! + * @name Blocking bus Operations + * @{ + */ + +/*! + * @brief Reads RX data register using a blocking method. + * + * This function polls the RX register, waits for the RX register to be full or for RX FIFO to + * have data, and reads data from the RX register. + * + * @note The function #HAL_UartReceiveBlocking and the function HAL_UartTransferReceiveNonBlocking + * cannot be used at the same time. + * And, the function HAL_UartTransferAbortReceive cannot be used to abort the transmission of this function. + * + * @param handle UART handle pointer. + * @param data Start address of the buffer to store the received data. + * @param length Size of the buffer. + * @retval kStatus_HAL_UartError An error occurred while receiving data. + * @retval kStatus_HAL_UartParityError A parity error occurred while receiving data. + * @retval kStatus_HAL_UartSuccess Successfully received all data. + */ +hal_uart_status_t HAL_UartReceiveBlocking(hal_uart_handle_t handle, uint8_t *data, size_t length); + +/*! + * @brief Writes to the TX register using a blocking method. + * + * This function polls the TX register, waits for the TX register to be empty or for the TX FIFO + * to have room and writes data to the TX buffer. + * + * @note The function #HAL_UartSendBlocking and the function HAL_UartTransferSendNonBlocking + * cannot be used at the same time. + * And, the function HAL_UartTransferAbortSend cannot be used to abort the transmission of this function. + * + * @param handle UART handle pointer. + * @param data Start address of the data to write. + * @param length Size of the data to write. + * @retval kStatus_HAL_UartSuccess Successfully sent all data. + */ +hal_uart_status_t HAL_UartSendBlocking(hal_uart_handle_t handle, const uint8_t *data, size_t length); + +/*! @}*/ + +#if (defined(UART_ADAPTER_NON_BLOCKING_MODE) && (UART_ADAPTER_NON_BLOCKING_MODE > 0U)) +#if (defined(HAL_UART_TRANSFER_MODE) && (HAL_UART_TRANSFER_MODE > 0U)) + +/*! + * @name Transactional + * @note The transactional API and the functional API cannot be used at the same time. The macro + * #HAL_UART_TRANSFER_MODE is used to set which one will be used. If #HAL_UART_TRANSFER_MODE is zero, the + * functional API with non-blocking mode will be used. Otherwise, transactional API will be used. + * @{ + */ + +/*! + * @brief Installs a callback and callback parameter. + * + * This function is used to install the callback and callback parameter for UART module. + * When any status of the UART changed, the driver will notify the upper layer by the installed callback + * function. And the status is also passed as status parameter when the callback is called. + * + * @param handle UART handle pointer. + * @param callback The callback function. + * @param callbackParam The parameter of the callback function. + * @retval kStatus_HAL_UartSuccess Successfully install the callback. + */ +hal_uart_status_t HAL_UartTransferInstallCallback(hal_uart_handle_t handle, + hal_uart_transfer_callback_t callback, + void *callbackParam); + +/*! + * @brief Receives a buffer of data using an interrupt method. + * + * This function receives data using an interrupt method. This is a non-blocking function, which + * returns directly without waiting for all data to be received. + * The receive request is saved by the UART driver. + * When the new data arrives, the receive request is serviced first. + * When all data is received, the UART driver notifies the upper layer + * through a callback function and passes the status parameter @ref kStatus_UART_RxIdle. + * + * @note The function #HAL_UartReceiveBlocking and the function #HAL_UartTransferReceiveNonBlocking + * cannot be used at the same time. + * + * @param handle UART handle pointer. + * @param transfer UART transfer structure, see #hal_uart_transfer_t. + * @retval kStatus_HAL_UartSuccess Successfully queue the transfer into transmit queue. + * @retval kStatus_HAL_UartRxBusy Previous receive request is not finished. + * @retval kStatus_HAL_UartError An error occurred. + */ +hal_uart_status_t HAL_UartTransferReceiveNonBlocking(hal_uart_handle_t handle, hal_uart_transfer_t *transfer); + +/*! + * @brief Transmits a buffer of data using the interrupt method. + * + * This function sends data using an interrupt method. This is a non-blocking function, which + * returns directly without waiting for all data to be written to the TX register. When + * all data is written to the TX register in the ISR, the UART driver calls the callback + * function and passes the @ref kStatus_UART_TxIdle as status parameter. + * + * @note The function #HAL_UartSendBlocking and the function #HAL_UartTransferSendNonBlocking + * cannot be used at the same time. + * + * @param handle UART handle pointer. + * @param transfer UART transfer structure. See #hal_uart_transfer_t. + * @retval kStatus_HAL_UartSuccess Successfully start the data transmission. + * @retval kStatus_HAL_UartTxBusy Previous transmission still not finished; data not all written to TX register yet. + * @retval kStatus_HAL_UartError An error occurred. + */ +hal_uart_status_t HAL_UartTransferSendNonBlocking(hal_uart_handle_t handle, hal_uart_transfer_t *transfer); + +/*! + * @brief Gets the number of bytes that have been received. + * + * This function gets the number of bytes that have been received. + * + * @param handle UART handle pointer. + * @param count Receive bytes count. + * @retval kStatus_HAL_UartError An error occurred. + * @retval kStatus_Success Get successfully through the parameter \p count. + */ +hal_uart_status_t HAL_UartTransferGetReceiveCount(hal_uart_handle_t handle, uint32_t *count); + +/*! + * @brief Gets the number of bytes written to the UART TX register. + * + * This function gets the number of bytes written to the UART TX + * register by using the interrupt method. + * + * @param handle UART handle pointer. + * @param count Send bytes count. + * @retval kStatus_HAL_UartError An error occurred. + * @retval kStatus_Success Get successfully through the parameter \p count. + */ +hal_uart_status_t HAL_UartTransferGetSendCount(hal_uart_handle_t handle, uint32_t *count); + +/*! + * @brief Aborts the interrupt-driven data receiving. + * + * This function aborts the interrupt-driven data receiving. The user can get the remainBytes to know + * how many bytes are not received yet. + * + * @note The function #HAL_UartTransferAbortReceive cannot be used to abort the transmission of + * the function #HAL_UartReceiveBlocking. + * + * @param handle UART handle pointer. + * @retval kStatus_Success Get successfully abort the receiving. + */ +hal_uart_status_t HAL_UartTransferAbortReceive(hal_uart_handle_t handle); + +/*! + * @brief Aborts the interrupt-driven data sending. + * + * This function aborts the interrupt-driven data sending. The user can get the remainBytes to find out + * how many bytes are not sent out. + * + * @note The function #HAL_UartTransferAbortSend cannot be used to abort the transmission of + * the function #HAL_UartSendBlocking. + * + * @param handle UART handle pointer. + * @retval kStatus_Success Get successfully abort the sending. + */ +hal_uart_status_t HAL_UartTransferAbortSend(hal_uart_handle_t handle); + +/*! @}*/ + +#else + +/*! + * @name Functional API with non-blocking mode. + * @note The functional API and the transactional API cannot be used at the same time. The macro + * #HAL_UART_TRANSFER_MODE is used to set which one will be used. If #HAL_UART_TRANSFER_MODE is zero, the + * functional API with non-blocking mode will be used. Otherwise, transactional API will be used. + * @{ + */ + +/*! + * @brief Installs a callback and callback parameter. + * + * This function is used to install the callback and callback parameter for UART module. + * When non-blocking sending or receiving finished, the adapter will notify the upper layer by the installed callback + * function. And the status is also passed as status parameter when the callback is called. + * + * @param handle UART handle pointer. + * @param callback The callback function. + * @param callbackParam The parameter of the callback function. + * @retval kStatus_HAL_UartSuccess Successfully install the callback. + */ +hal_uart_status_t HAL_UartInstallCallback(hal_uart_handle_t handle, + hal_uart_transfer_callback_t callback, + void *callbackParam); + +/*! + * @brief Receives a buffer of data using an interrupt method. + * + * This function receives data using an interrupt method. This is a non-blocking function, which + * returns directly without waiting for all data to be received. + * The receive request is saved by the UART adapter. + * When the new data arrives, the receive request is serviced first. + * When all data is received, the UART adapter notifies the upper layer + * through a callback function and passes the status parameter @ref kStatus_UART_RxIdle. + * + * @note The function #HAL_UartReceiveBlocking and the function #HAL_UartReceiveNonBlocking + * cannot be used at the same time. + * + * @param handle UART handle pointer. + * @param data Start address of the data to write. + * @param length Size of the data to write. + * @retval kStatus_HAL_UartSuccess Successfully queue the transfer into transmit queue. + * @retval kStatus_HAL_UartRxBusy Previous receive request is not finished. + * @retval kStatus_HAL_UartError An error occurred. + */ +hal_uart_status_t HAL_UartReceiveNonBlocking(hal_uart_handle_t handle, uint8_t *data, size_t length); + +/*! + * @brief Transmits a buffer of data using the interrupt method. + * + * This function sends data using an interrupt method. This is a non-blocking function, which + * returns directly without waiting for all data to be written to the TX register. When + * all data is written to the TX register in the ISR, the UART driver calls the callback + * function and passes the @ref kStatus_UART_TxIdle as status parameter. + * + * @note The function #HAL_UartSendBlocking and the function #HAL_UartSendNonBlocking + * cannot be used at the same time. + * + * @param handle UART handle pointer. + * @param data Start address of the data to write. + * @param length Size of the data to write. + * @retval kStatus_HAL_UartSuccess Successfully start the data transmission. + * @retval kStatus_HAL_UartTxBusy Previous transmission still not finished; data not all written to TX register yet. + * @retval kStatus_HAL_UartError An error occurred. + */ +hal_uart_status_t HAL_UartSendNonBlocking(hal_uart_handle_t handle, uint8_t *data, size_t length); + +/*! + * @brief Gets the number of bytes that have been received. + * + * This function gets the number of bytes that have been received. + * + * @param handle UART handle pointer. + * @param count Receive bytes count. + * @retval kStatus_HAL_UartError An error occurred. + * @retval kStatus_Success Get successfully through the parameter \p count. + */ +hal_uart_status_t HAL_UartGetReceiveCount(hal_uart_handle_t handle, uint32_t *reCount); + +/*! + * @brief Gets the number of bytes written to the UART TX register. + * + * This function gets the number of bytes written to the UART TX + * register by using the interrupt method. + * + * @param handle UART handle pointer. + * @param count Send bytes count. + * @retval kStatus_HAL_UartError An error occurred. + * @retval kStatus_Success Get successfully through the parameter \p count. + */ +hal_uart_status_t HAL_UartGetSendCount(hal_uart_handle_t handle, uint32_t *seCount); + +/*! + * @brief Aborts the interrupt-driven data receiving. + * + * This function aborts the interrupt-driven data receiving. The user can get the remainBytes to know + * how many bytes are not received yet. + * + * @note The function #HAL_UartAbortReceive cannot be used to abort the transmission of + * the function #HAL_UartReceiveBlocking. + * + * @param handle UART handle pointer. + * @retval kStatus_Success Get successfully abort the receiving. + */ +hal_uart_status_t HAL_UartAbortReceive(hal_uart_handle_t handle); + +/*! + * @brief Aborts the interrupt-driven data sending. + * + * This function aborts the interrupt-driven data sending. The user can get the remainBytes to find out + * how many bytes are not sent out. + * + * @note The function #HAL_UartAbortSend cannot be used to abort the transmission of + * the function #HAL_UartSendBlocking. + * + * @param handle UART handle pointer. + * @retval kStatus_Success Get successfully abort the sending. + */ +hal_uart_status_t HAL_UartAbortSend(hal_uart_handle_t handle); + +/*! @}*/ + +#endif +#endif + +#if (defined(HAL_UART_DMA_ENABLE) && (HAL_UART_DMA_ENABLE > 0U)) + +/*! + * @brief Initializes a UART dma instance with the UART dma handle and the user configuration structure. + * + * This function configures the UART dma module with user-defined settings. The user can configure the configuration + * structure. The parameter handle is a pointer to point to a memory space of size #HAL_UART_DMA_HANDLE_SIZE allocated + * by the caller. Example below shows how to use this API to configure the UART. + * @code + * + * Init TimerManager, only used in UART without Idleline interrupt + * timer_config_t timerConfig; + * timerConfig.srcClock_Hz = 16000000; + * timerConfig.instance = 0; + * TM_Init(&timerConfig); + * + * Init the DMA module + * DMA_Init(DMA0); + * + * Define a uart dma handle + * UART_HANDLE_DEFINE(g_uartHandle); + * UART_DMA_HANDLE_DEFINE(g_UartDmaHandle); + * + * Configure uart settings + * hal_uart_config_t uartConfig; + * uartConfig.srcClock_Hz = 48000000; + * uartConfig.baudRate_Bps = 115200; + * uartConfig.parityMode = kHAL_UartParityDisabled; + * uartConfig.stopBitCount = kHAL_UartOneStopBit; + * uartConfig.enableRx = 1; + * uartConfig.enableTx = 1; + * uartConfig.enableRxRTS = 0; + * uartConfig.enableTxCTS = 0; + * uartConfig.instance = 0; + * + * Init uart + * HAL_UartInit((hal_uart_handle_t *)g_uartHandle, &uartConfig); + * + * Configure uart dma settings + * hal_uart_dma_config_t dmaConfig; + * dmaConfig.uart_instance = 0; + * dmaConfig.dma_instance = 0; + * dmaConfig.rx_channel = 0; + * dmaConfig.tx_channel = 1; + * + * Init uart dma + * HAL_UartDMAInit((hal_uart_handle_t *)g_uartHandle, (hal_uart_dma_handle_t *)g_uartDmaHandle, &dmaConfig); + * @endcode + * + * @param handle UART handle pointer. + * @param dmaHandle Pointer to point to a memory space of size #HAL_UART_DMA_HANDLE_SIZE allocated by the caller. + * The handle should be 4 byte aligned, because unaligned access doesn't be supported on some devices. + * You can define the handle in the following two ways: + * #UART_DMA_HANDLE_DEFINE(handle); + * or + * uint32_t handle[((HAL_UART_DMA_HANDLE_SIZE + sizeof(uint32_t) - 1U) / sizeof(uint32_t))]; + * @param dmaConfig Pointer to user-defined configuration structure. + * @retval kStatus_HAL_UartDmaError UART dma initialization failed. + * @retval kStatus_HAL_UartDmaSuccess UART dma initialization succeed. + */ +hal_uart_dma_status_t HAL_UartDMAInit(hal_uart_handle_t handle, + hal_uart_dma_handle_t dmaHandle, + hal_uart_dma_config_t *dmaConfig); + +/*! + * @brief Deinitializes a UART DMA instance. + * + * This function will abort uart dma receive/send transfer and deinitialize UART. + * + * @param handle UART handle pointer. + * @retval kStatus_HAL_UartDmaSuccess UART DMA de-initialization succeed + */ +hal_uart_dma_status_t HAL_UartDMADeinit(hal_uart_handle_t handle); + +/*! + * @brief Installs a callback and callback parameter. + * + * This function is used to install the callback and callback parameter for UART DMA module. + * When any status of the UART DMA changed, the driver will notify the upper layer by the installed callback + * function. And the status is also passed as status parameter when the callback is called. + * + * @param handle UART handle pointer. + * @param callback The callback function. + * @param callbackParam The parameter of the callback function. + * @retval kStatus_HAL_UartDmaSuccess Successfully install the callback. + */ +hal_uart_dma_status_t HAL_UartDMATransferInstallCallback(hal_uart_handle_t handle, + hal_uart_dma_transfer_callback_t callback, + void *callbackParam); + +/*! + * @brief Receives a buffer of data using an dma method. + * + * This function receives data using an dma method. This is a non-blocking function, which + * returns directly without waiting for all data to be received. + * The receive request is saved by the UART DMA driver. + * When all data is received, the UART DMA adapter notifies the upper layer + * through a callback function and passes the status parameter @ref kStatus_HAL_UartDmaRxIdle. + * + * When an idleline is detected, the UART DMA adapter notifies the upper layer through a callback function, + * and passes the status parameter @ref kStatus_HAL_UartDmaIdleline. For the UARTs without hardware idleline + * interrupt(like usart), it will use a software idleline detection method with the help of TimerManager. + * + * When the soc support cache, uplayer should do cache maintain operations for transfer buffer before call this API. + * + * @param handle UART handle pointer. + * @param data data Start address of the buffer to store the received data. + * @param length Size of the buffer. + * @param receiveAll Idleline interrupt will not end transfer process if set true. + * @retval kStatus_HAL_UartDmaSuccess Successfully start the data receive. + * @retval kStatus_HAL_UartDmaRxBusy Previous receive request is not finished. + */ +hal_uart_dma_status_t HAL_UartDMATransferReceive(hal_uart_handle_t handle, + uint8_t *data, + size_t length, + bool receiveAll); + +/*! + * @brief Transmits a buffer of data using an dma method. + * + * This function sends data using an dma method. This is a non-blocking function, which + * returns directly without waiting for all data to be written to the TX register. When + * all data is written to the TX register by DMA, the UART DMA driver calls the callback + * function and passes the @ref kStatus_HAL_UartDmaTxIdle as status parameter. + * + * When the soc support cache, uplayer should do cache maintain operations for transfer buffer before call this API. + * + * @param handle UART handle pointer. + * @param data data Start address of the data to write. + * @param length Size of the data to write. + * @retval kStatus_HAL_UartDmaSuccess Successfully start the data transmission. + * @retval kStatus_HAL_UartDmaTxBusy Previous send request is not finished. + */ +hal_uart_dma_status_t HAL_UartDMATransferSend(hal_uart_handle_t handle, uint8_t *data, size_t length); + +/*! + * @brief Gets the number of bytes that have been received. + * + * This function gets the number of bytes that have been received. + * + * @param handle UART handle pointer. + * @param reCount Receive bytes count. + * @retval kStatus_HAL_UartDmaError An error occurred. + * @retval kStatus_HAL_UartDmaSuccess Get successfully through the parameter \p reCount. + */ +hal_uart_dma_status_t HAL_UartDMAGetReceiveCount(hal_uart_handle_t handle, uint32_t *reCount); + +/*! + * @brief Gets the number of bytes written to the UART TX register. + * + * This function gets the number of bytes written to the UART TX + * register by using the DMA method. + * + * @param handle UART handle pointer. + * @param count Send bytes count. + * @retval kStatus_HAL_UartDmaError An error occurred. + * @retval kStatus_HAL_UartDmaSuccess Get successfully through the parameter \p seCount. + */ +hal_uart_dma_status_t HAL_UartDMAGetSendCount(hal_uart_handle_t handle, uint32_t *seCount); + +/*! + * @brief Aborts the DMA-driven data receiving. + * + * This function aborts the DMA-driven data receiving. + * + * @param handle UART handle pointer. + * @retval kStatus_HAL_UartDmaSuccess Get successfully abort the receiving. + */ +hal_uart_dma_status_t HAL_UartDMAAbortReceive(hal_uart_handle_t handle); + +/*! + * @brief Aborts the DMA-driven data sending. + * + * This function aborts the DMA-driven data sending. + * + * @param handle UART handle pointer. + * @retval kStatus_Success Get successfully abort the sending. + */ +hal_uart_dma_status_t HAL_UartDMAAbortSend(hal_uart_handle_t handle); +#endif /* HAL_UART_DMA_ENABLE */ + +/*! + * @brief Prepares to enter low power consumption. + * + * This function is used to prepare to enter low power consumption. + * + * @param handle UART handle pointer. + * @retval kStatus_HAL_UartSuccess Successful operation. + * @retval kStatus_HAL_UartError An error occurred. + */ +hal_uart_status_t HAL_UartEnterLowpower(hal_uart_handle_t handle); + +/*! + * @brief Restores from low power consumption. + * + * This function is used to restore from low power consumption. + * + * @param handle UART handle pointer. + * @retval kStatus_HAL_UartSuccess Successful operation. + * @retval kStatus_HAL_UartError An error occurred. + */ +hal_uart_status_t HAL_UartExitLowpower(hal_uart_handle_t handle); + +#if (defined(UART_ADAPTER_NON_BLOCKING_MODE) && (UART_ADAPTER_NON_BLOCKING_MODE > 0U)) +/*! + * @brief UART IRQ handle function. + * + * This function handles the UART transmit and receive IRQ request. + * + * @param handle UART handle pointer. + */ +void HAL_UartIsrFunction(hal_uart_handle_t handle); +#endif + +#if defined(__cplusplus) +} +#endif +/*! @}*/ +#endif /* __HAL_UART_ADAPTER_H__ */ |