[freertos] / FreeRTOS / Demo / CORTEX_MPU_M33F_NXP_LPC55S69_MCUXpresso / NXP_Code / component / uart / uart.h

/*\r
 * Copyright 2018 NXP\r
 * All rights reserved.\r
 *\r
 *\r
 * SPDX-License-Identifier: BSD-3-Clause\r
 */\r
\r
#ifndef __HAL_UART_ADAPTER_H__\r
#define __HAL_UART_ADAPTER_H__\r
\r
/*******************************************************************************\r
 * Definitions\r
 ******************************************************************************/\r
\r
#ifdef DEBUG_CONSOLE_TRANSFER_NON_BLOCKING\r
#define UART_ADAPTER_NON_BLOCKING_MODE \\r
    (1U) /* Enable or disable Uart adapter non-blocking mode (1 - enable, 0 - disable) */\r
#else\r
#ifndef SERIAL_MANAGER_NON_BLOCKING_MODE\r
#define UART_ADAPTER_NON_BLOCKING_MODE \\r
    (0U) /* Enable or disable Uart adapter non-blocking mode (1 - enable, 0 - disable) */\r
#else\r
#define UART_ADAPTER_NON_BLOCKING_MODE SERIAL_MANAGER_NON_BLOCKING_MODE\r
#endif\r
#endif\r
\r
#if (defined(UART_ADAPTER_NON_BLOCKING_MODE) && (UART_ADAPTER_NON_BLOCKING_MODE > 0U))\r
#define HAL_UART_HANDLE_SIZE (90U)\r
#else\r
#define HAL_UART_HANDLE_SIZE (4U)\r
#endif\r
\r
#define HAL_UART_TRANSFER_MODE                                                               \\r
    (0U) /*!< Whether enable transactional function of the uart. (0 - disable, 1 - enable) \ \\r
            */\r
\r
typedef void *hal_uart_handle_t;\r
\r
/*! @brief uart status */\r
typedef enum _hal_uart_status\r
{\r
    kStatus_HAL_UartSuccess = kStatus_Success,                      /*!< Successfully */\r
    kStatus_HAL_UartTxBusy = MAKE_STATUS(kStatusGroup_HAL_UART, 1), /*!< TX busy */\r
    kStatus_HAL_UartRxBusy = MAKE_STATUS(kStatusGroup_HAL_UART, 2), /*!< RX busy */\r
    kStatus_HAL_UartTxIdle = MAKE_STATUS(kStatusGroup_HAL_UART, 3), /*!< HAL uart transmitter is idle. */\r
    kStatus_HAL_UartRxIdle = MAKE_STATUS(kStatusGroup_HAL_UART, 4), /*!< HAL uart receiver is idle */\r
    kStatus_HAL_UartBaudrateNotSupport =\r
        MAKE_STATUS(kStatusGroup_HAL_UART, 5), /*!< Baudrate is not support in current clock source */\r
    kStatus_HAL_UartProtocolError = MAKE_STATUS(\r
        kStatusGroup_HAL_UART,\r
        6),                                                        /*!< Error occurs for Noise, Framing, Parity, etc.\r
                                                                        For transcational transfer, The up layer needs to abort the transfer and then starts again */\r
    kStatus_HAL_UartError = MAKE_STATUS(kStatusGroup_HAL_UART, 7), /*!< Error occurs on HAL uart */\r
} hal_uart_status_t;\r
\r
/*! @brief uart parity mode. */\r
typedef enum _hal_uart_parity_mode\r
{\r
    kHAL_UartParityDisabled = 0x0U, /*!< Parity disabled */\r
    kHAL_UartParityEven = 0x1U,     /*!< Parity even enabled */\r
    kHAL_UartParityOdd = 0x2U,      /*!< Parity odd enabled */\r
} hal_uart_parity_mode_t;\r
\r
/*! @brief uart stop bit count. */\r
typedef enum _hal_uart_stop_bit_count\r
{\r
    kHAL_UartOneStopBit = 0U, /*!< One stop bit */\r
    kHAL_UartTwoStopBit = 1U, /*!< Two stop bits */\r
} hal_uart_stop_bit_count_t;\r
\r
/*! @brief uart configuration structure. */\r
typedef struct _hal_uart_config\r
{\r
    uint32_t srcClock_Hz;                   /*!< Source clock */\r
    uint32_t baudRate_Bps;                  /*!< Baud rate  */\r
    hal_uart_parity_mode_t parityMode;      /*!< Parity mode, disabled (default), even, odd */\r
    hal_uart_stop_bit_count_t stopBitCount; /*!< Number of stop bits, 1 stop bit (default) or 2 stop bits  */\r
    uint8_t enableRx;                       /*!< Enable RX */\r
    uint8_t enableTx;                       /*!< Enable TX */\r
    uint8_t instance; /*!< Instance (0 - UART0, 1 - UART1, ...), detail information please refer to the\r
                           SOC corresponding RM.\r
                           Invalid instance value will cause initialization failure. */\r
} hal_uart_config_t;\r
\r
/*! @brief uart transfer callback function. */\r
typedef void (*hal_uart_transfer_callback_t)(hal_uart_handle_t handle, hal_uart_status_t status, void *callbackParam);\r
\r
/*! @brief uart transfer structure. */\r
typedef struct _hal_uart_transfer\r
{\r
    uint8_t *data;   /*!< The buffer of data to be transfer.*/\r
    size_t dataSize; /*!< The byte count to be transfer. */\r
} hal_uart_transfer_t;\r
\r
/*******************************************************************************\r
 * API\r
 ******************************************************************************/\r
\r
#if defined(__cplusplus)\r
extern "C" {\r
#endif /* _cplusplus */\r
\r
/*!\r
 * @name Initialization and deinitialization\r
 * @{\r
 */\r
\r
/*!\r
* @brief Initializes a uart instance with the uart handle and the user configuration structure.\r
*\r
* This function configures the uart module with user-defined settings. The user can configure the configuration\r
* structure. The parameter handle is a pointer to point to a memory space of size #HAL_UART_HANDLE_SIZE allocated by the\r
* caller.\r
* Example below shows how to use this API to configure the uart.\r
*  @code\r
*   uint8_t g_UartHandleBuffer[HAL_UART_HANDLE_SIZE];\r
*   hal_uart_handle_t g_UartHandle = &g_UartHandleBuffer[0];\r
*   hal_uart_config_t config;\r
*   config.srcClock_Hz = 48000000;\r
*   config.baudRate_Bps = 115200U;\r
*   config.parityMode = kHAL_UartParityDisabled;\r
*   config.stopBitCount = kHAL_UartOneStopBit;\r
*   config.enableRx = 1;\r
*   config.enableTx = 1;\r
*   config.instance = 0;\r
*   HAL_UartInit(g_UartHandle, &config);\r
*  @endcode\r
*\r
* @param handle Pointer to point to a memory space of size #HAL_UART_HANDLE_SIZE allocated by the caller.\r
* @param config Pointer to user-defined configuration structure.\r
* @retval kStatus_HAL_UartBaudrateNotSupport Baudrate is not support in current clock source.\r
* @retval kStatus_HAL_UartSuccess uart initialization succeed\r
*/\r
hal_uart_status_t HAL_UartInit(hal_uart_handle_t handle, hal_uart_config_t *config);\r
\r
/*!\r
 * @brief Deinitializes a uart instance.\r
 *\r
 * This function waits for TX complete, disables TX and RX, and disables the uart clock.\r
 *\r
 * @param handle uart handle pointer.\r
 * @retval kStatus_HAL_UartSuccess uart de-initialization succeed\r
 */\r
hal_uart_status_t HAL_UartDeinit(hal_uart_handle_t handle);\r
\r
/* @} */\r
\r
/*!\r
 * @name Blocking bus Operations\r
 * @{\r
 */\r
\r
/*!\r
 * @brief Reads RX data register using a blocking method.\r
 *\r
 * This function polls the RX register, waits for the RX register to be full or for RX FIFO to\r
 * have data, and reads data from the RX register.\r
 *\r
 * @note The function #HAL_UartReceiveBlocking and the function #HAL_UartTransferReceiveNonBlocking\r
 * cannot be used at the same time.\r
 * And, the function #HAL_UartTransferAbortReceive cannot be used to abort the transmission of this function.\r
 *\r
 * @param handle uart handle pointer.\r
 * @param data Start address of the buffer to store the received data.\r
 * @param length Size of the buffer.\r
 * @retval kStatus_HAL_UartError An error occurred while receiving data.\r
 * @retval kStatus_HAL_UartParityError A parity error occurred while receiving data.\r
 * @retval kStatus_HAL_UartSuccess Successfully received all data.\r
 */\r
hal_uart_status_t HAL_UartReceiveBlocking(hal_uart_handle_t handle, uint8_t *data, size_t length);\r
\r
/*!\r
 * @brief Writes to the TX register using a blocking method.\r
 *\r
 * This function polls the TX register, waits for the TX register to be empty or for the TX FIFO\r
 * to have room and writes data to the TX buffer.\r
 *\r
 * @note The function #HAL_UartSendBlocking and the function #HAL_UartTransferSendNonBlocking\r
 * cannot be used at the same time.\r
 * And, the function #HAL_UartTransferAbortSend cannot be used to abort the transmission of this function.\r
 *\r
 * @param handle uart handle pointer.\r
 * @param data Start address of the data to write.\r
 * @param length Size of the data to write.\r
 * @retval kStatus_HAL_UartSuccess Successfully sent all data.\r
 */\r
hal_uart_status_t HAL_UartSendBlocking(hal_uart_handle_t handle, const uint8_t *data, size_t length);\r
\r
/* @} */\r
\r
#if (defined(HAL_UART_TRANSFER_MODE) && (HAL_UART_TRANSFER_MODE > 0U))\r
\r
/*!\r
 * @name Transactional\r
 * @note The transactional API and the functional API cannot be used at the same time. The macro\r
 * #HAL_UART_TRANSFER_MODE is used to set which one will be used. If #HAL_UART_TRANSFER_MODE is zero, the\r
 * functional API with non-blocking mode will be used. Otherwise, transactional API will be used.\r
 * @{\r
 */\r
\r
/*!\r
 * @brief Installs a callback and callback parameter.\r
 *\r
 * This function is used to install the callback and callback parameter for uart module.\r
 * When any status of the uart changed, the driver will notify the upper layer by the installed callback\r
 * function. And the status is also passed as status parameter when the callback is called.\r
 *\r
 * @param handle uart handle pointer.\r
 * @param callback The callback function.\r
 * @param callbackParam The parameter of the callback function.\r
 * @retval kStatus_HAL_UartSuccess Successfully install the callback.\r
 */\r
hal_uart_status_t HAL_UartTransferInstallCallback(hal_uart_handle_t handle,\r
                                                  hal_uart_transfer_callback_t callback,\r
                                                  void *callbackParam);\r
\r
/*!\r
 * @brief Receives a buffer of data using an interrupt method.\r
 *\r
 * This function receives data using an interrupt method. This is a non-blocking function, which\r
 * returns directly without waiting for all data to be received.\r
 * The receive request is saved by the uart driver.\r
 * When the new data arrives, the receive request is serviced first.\r
 * When all data is received, the uart driver notifies the upper layer\r
 * through a callback function and passes the status parameter @ref kStatus_UART_RxIdle.\r
 *\r
 * @note The function #HAL_UartReceiveBlocking and the function #HAL_UartTransferReceiveNonBlocking\r
 * cannot be used at the same time.\r
 *\r
 * @param handle uart handle pointer.\r
 * @param transfer uart transfer structure, see #hal_uart_transfer_t.\r
 * @retval kStatus_HAL_UartSuccess Successfully queue the transfer into transmit queue.\r
 * @retval kStatus_HAL_UartRxBusy Previous receive request is not finished.\r
 * @retval kStatus_HAL_UartError An error occurred.\r
 */\r
hal_uart_status_t HAL_UartTransferReceiveNonBlocking(hal_uart_handle_t handle, hal_uart_transfer_t *transfer);\r
\r
/*!\r
 * @brief Transmits a buffer of data using the interrupt method.\r
 *\r
 * This function sends data using an interrupt method. This is a non-blocking function, which\r
 * returns directly without waiting for all data to be written to the TX register. When\r
 * all data is written to the TX register in the ISR, the uart driver calls the callback\r
 * function and passes the @ref kStatus_UART_TxIdle as status parameter.\r
 *\r
 * @note The function #HAL_UartSendBlocking and the function #HAL_UartTransferSendNonBlocking\r
 * cannot be used at the same time.\r
 *\r
 * @param handle uart handle pointer.\r
 * @param transfer uart transfer structure. See #hal_uart_transfer_t.\r
 * @retval kStatus_HAL_UartSuccess Successfully start the data transmission.\r
 * @retval kStatus_HAL_UartTxBusy Previous transmission still not finished; data not all written to TX register yet.\r
 * @retval kStatus_HAL_UartError An error occurred.\r
 */\r
hal_uart_status_t HAL_UartTransferSendNonBlocking(hal_uart_handle_t handle, hal_uart_transfer_t *transfer);\r
\r
/*!\r
 * @brief Gets the number of bytes that have been received.\r
 *\r
 * This function gets the number of bytes that have been received.\r
 *\r
 * @param handle uart handle pointer.\r
 * @param count Receive bytes count.\r
 * @retval kStatus_HAL_UartError An error occurred.\r
 * @retval kStatus_Success Get successfully through the parameter \p count.\r
 */\r
hal_uart_status_t HAL_UartTransferGetReceiveCount(hal_uart_handle_t handle, uint32_t *count);\r
\r
/*!\r
 * @brief Gets the number of bytes written to the uart TX register.\r
 *\r
 * This function gets the number of bytes written to the uart TX\r
 * register by using the interrupt method.\r
 *\r
 * @param handle uart handle pointer.\r
 * @param count Send bytes count.\r
 * @retval kStatus_HAL_UartError An error occurred.\r
 * @retval kStatus_Success Get successfully through the parameter \p count.\r
 */\r
hal_uart_status_t HAL_UartTransferGetSendCount(hal_uart_handle_t handle, uint32_t *count);\r
\r
/*!\r
 * @brief Aborts the interrupt-driven data receiving.\r
 *\r
 * This function aborts the interrupt-driven data receiving. The user can get the remainBytes to know\r
 * how many bytes are not received yet.\r
 *\r
 * @note The function #HAL_UartTransferAbortReceive cannot be used to abort the transmission of\r
 * the function #HAL_UartReceiveBlocking.\r
 *\r
 * @param handle uart handle pointer.\r
 * @retval kStatus_Success Get successfully abort the receiving.\r
 */\r
hal_uart_status_t HAL_UartTransferAbortReceive(hal_uart_handle_t handle);\r
\r
/*!\r
 * @brief Aborts the interrupt-driven data sending.\r
 *\r
 * This function aborts the interrupt-driven data sending. The user can get the remainBytes to find out\r
 * how many bytes are not sent out.\r
 *\r
 * @note The function #HAL_UartTransferAbortSend cannot be used to abort the transmission of\r
 * the function #HAL_UartSendBlocking.\r
 *\r
 * @param handle uart handle pointer.\r
 * @retval kStatus_Success Get successfully abort the sending.\r
 */\r
hal_uart_status_t HAL_UartTransferAbortSend(hal_uart_handle_t handle);\r
\r
/* @} */\r
\r
#else\r
\r
/*!\r
 * @name Functional API with non-blocking mode.\r
 * @note The functional API and the transactional API cannot be used at the same time. The macro\r
 * #HAL_UART_TRANSFER_MODE is used to set which one will be used. If #HAL_UART_TRANSFER_MODE is zero, the\r
 * functional API with non-blocking mode will be used. Otherwise, transactional API will be used.\r
 * @{\r
 */\r
\r
/*!\r
 * @brief Installs a callback and callback parameter.\r
 *\r
 * This function is used to install the callback and callback parameter for uart module.\r
 * When non-blocking sending or receiving finished, the adapter will notify the upper layer by the installed callback\r
 * function. And the status is also passed as status parameter when the callback is called.\r
 *\r
 * @param handle uart handle pointer.\r
 * @param callback The callback function.\r
 * @param callbackParam The parameter of the callback function.\r
 * @retval kStatus_HAL_UartSuccess Successfully install the callback.\r
 */\r
hal_uart_status_t HAL_UartInstallCallback(hal_uart_handle_t handle,\r
                                          hal_uart_transfer_callback_t callback,\r
                                          void *callbackParam);\r
\r
/*!\r
 * @brief Receives a buffer of data using an interrupt method.\r
 *\r
 * This function receives data using an interrupt method. This is a non-blocking function, which\r
 * returns directly without waiting for all data to be received.\r
 * The receive request is saved by the uart adapter.\r
 * When the new data arrives, the receive request is serviced first.\r
 * When all data is received, the uart adapter notifies the upper layer\r
 * through a callback function and passes the status parameter @ref kStatus_UART_RxIdle.\r
 *\r
 * @note The function #HAL_UartReceiveBlocking and the function #HAL_UartReceiveNonBlocking\r
 * cannot be used at the same time.\r
 *\r
 * @param handle uart handle pointer.\r
 * @param data Start address of the data to write.\r
 * @param length Size of the data to write.\r
 * @retval kStatus_HAL_UartSuccess Successfully queue the transfer into transmit queue.\r
 * @retval kStatus_HAL_UartRxBusy Previous receive request is not finished.\r
 * @retval kStatus_HAL_UartError An error occurred.\r
 */\r
hal_uart_status_t HAL_UartReceiveNonBlocking(hal_uart_handle_t handle, uint8_t *data, size_t length);\r
\r
/*!\r
 * @brief Transmits a buffer of data using the interrupt method.\r
 *\r
 * This function sends data using an interrupt method. This is a non-blocking function, which\r
 * returns directly without waiting for all data to be written to the TX register. When\r
 * all data is written to the TX register in the ISR, the uart driver calls the callback\r
 * function and passes the @ref kStatus_UART_TxIdle as status parameter.\r
 *\r
 * @note The function #HAL_UartSendBlocking and the function #HAL_UartSendNonBlocking\r
 * cannot be used at the same time.\r
 *\r
 * @param handle uart handle pointer.\r
 * @param data Start address of the data to write.\r
 * @param length Size of the data to write.\r
 * @retval kStatus_HAL_UartSuccess Successfully start the data transmission.\r
 * @retval kStatus_HAL_UartTxBusy Previous transmission still not finished; data not all written to TX register yet.\r
 * @retval kStatus_HAL_UartError An error occurred.\r
 */\r
hal_uart_status_t HAL_UartSendNonBlocking(hal_uart_handle_t handle, const uint8_t *data, size_t length);\r
\r
/*!\r
 * @brief Gets the number of bytes that have been received.\r
 *\r
 * This function gets the number of bytes that have been received.\r
 *\r
 * @param handle uart handle pointer.\r
 * @param count Receive bytes count.\r
 * @retval kStatus_HAL_UartError An error occurred.\r
 * @retval kStatus_Success Get successfully through the parameter \p count.\r
 */\r
hal_uart_status_t HAL_UartGetReceiveCount(hal_uart_handle_t handle, uint32_t *count);\r
\r
/*!\r
 * @brief Gets the number of bytes written to the uart TX register.\r
 *\r
 * This function gets the number of bytes written to the uart TX\r
 * register by using the interrupt method.\r
 *\r
 * @param handle uart handle pointer.\r
 * @param count Send bytes count.\r
 * @retval kStatus_HAL_UartError An error occurred.\r
 * @retval kStatus_Success Get successfully through the parameter \p count.\r
 */\r
hal_uart_status_t HAL_UartGetSendCount(hal_uart_handle_t handle, uint32_t *count);\r
\r
/*!\r
 * @brief Aborts the interrupt-driven data receiving.\r
 *\r
 * This function aborts the interrupt-driven data receiving. The user can get the remainBytes to know\r
 * how many bytes are not received yet.\r
 *\r
 * @note The function #HAL_UartAbortReceive cannot be used to abort the transmission of\r
 * the function #HAL_UartReceiveBlocking.\r
 *\r
 * @param handle uart handle pointer.\r
 * @retval kStatus_Success Get successfully abort the receiving.\r
 */\r
hal_uart_status_t HAL_UartAbortReceive(hal_uart_handle_t handle);\r
\r
/*!\r
 * @brief Aborts the interrupt-driven data sending.\r
 *\r
 * This function aborts the interrupt-driven data sending. The user can get the remainBytes to find out\r
 * how many bytes are not sent out.\r
 *\r
 * @note The function #HAL_UartAbortSend cannot be used to abort the transmission of\r
 * the function #HAL_UartSendBlocking.\r
 *\r
 * @param handle uart handle pointer.\r
 * @retval kStatus_Success Get successfully abort the sending.\r
 */\r
hal_uart_status_t HAL_UartAbortSend(hal_uart_handle_t handle);\r
\r
/* @} */\r
\r
#endif\r
\r
/*!\r
 * @brief uart IRQ handle function.\r
 *\r
 * This function handles the uart transmit and receive IRQ request.\r
 *\r
 * @param handle uart handle pointer.\r
 */\r
void HAL_UartIsrFunction(hal_uart_handle_t handle);\r
\r
#if defined(__cplusplus)\r
}\r
#endif\r
\r
#endif /* __HAL_UART_ADAPTER_H__ */\r