383 lines
15 KiB
C
383 lines
15 KiB
C
/* Copyright Statement:
|
||
*
|
||
* This software/firmware and related documentation ("AutoChips Software") are
|
||
* protected under relevant copyright laws. The information contained herein is
|
||
* confidential and proprietary to AutoChips Inc. and/or its licensors. Without
|
||
* the prior written permission of AutoChips inc. and/or its licensors, any
|
||
* reproduction, modification, use or disclosure of AutoChips Software, and
|
||
* information contained herein, in whole or in part, shall be strictly
|
||
* prohibited.
|
||
*
|
||
* AutoChips Inc. (C) 2021. All rights reserved.
|
||
*
|
||
* BY OPENING THIS FILE, RECEIVER HEREBY UNEQUIVOCALLY ACKNOWLEDGES AND AGREES
|
||
* THAT THE SOFTWARE/FIRMWARE AND ITS DOCUMENTATIONS ("AUTOCHIPS SOFTWARE")
|
||
* RECEIVED FROM AUTOCHIPS AND/OR ITS REPRESENTATIVES ARE PROVIDED TO RECEIVER
|
||
* ON AN "AS-IS" BASIS ONLY. AUTOCHIPS EXPRESSLY DISCLAIMS ANY AND ALL
|
||
* WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED
|
||
* WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR
|
||
* NONINFRINGEMENT. NEITHER DOES AUTOCHIPS PROVIDE ANY WARRANTY WHATSOEVER WITH
|
||
* RESPECT TO THE SOFTWARE OF ANY THIRD PARTY WHICH MAY BE USED BY,
|
||
* INCORPORATED IN, OR SUPPLIED WITH THE AUTOCHIPS SOFTWARE, AND RECEIVER AGREES
|
||
* TO LOOK ONLY TO SUCH THIRD PARTY FOR ANY WARRANTY CLAIM RELATING THERETO.
|
||
* RECEIVER EXPRESSLY ACKNOWLEDGES THAT IT IS RECEIVER'S SOLE RESPONSIBILITY TO
|
||
* OBTAIN FROM ANY THIRD PARTY ALL PROPER LICENSES CONTAINED IN AUTOCHIPS
|
||
* SOFTWARE. AUTOCHIPS SHALL ALSO NOT BE RESPONSIBLE FOR ANY AUTOCHIPS SOFTWARE
|
||
* RELEASES MADE TO RECEIVER'S SPECIFICATION OR TO CONFORM TO A PARTICULAR
|
||
* STANDARD OR OPEN FORUM. RECEIVER'S SOLE AND EXCLUSIVE REMEDY AND AUTOCHIPS'S
|
||
* ENTIRE AND CUMULATIVE LIABILITY WITH RESPECT TO THE AUTOCHIPS SOFTWARE
|
||
* RELEASED HEREUNDER WILL BE, AT AUTOCHIPS'S OPTION, TO REVISE OR REPLACE THE
|
||
* AUTOCHIPS SOFTWARE AT ISSUE, OR REFUND ANY SOFTWARE LICENSE FEES OR SERVICE
|
||
* CHARGE PAID BY RECEIVER TO AUTOCHIPS FOR SUCH AUTOCHIPS SOFTWARE AT ISSUE.
|
||
*/
|
||
|
||
/*!
|
||
* @file uart_drv.h
|
||
*
|
||
* @brief This file provides uart integration functions interface.
|
||
*
|
||
*/
|
||
|
||
#ifndef UART_DRV_H
|
||
#define UART_DRV_H
|
||
|
||
#ifdef __cplusplus
|
||
extern "C" {
|
||
#endif /* __cplusplus */
|
||
|
||
/* =========================================== Includes =========================================== */
|
||
#include "device_register.h"
|
||
#include "osif.h"
|
||
|
||
/*=====================================SOURCE FILE VERSION INFORMATION==============================*/
|
||
#define UART_HAL_MODULE_ID (661U)
|
||
#define UART_HAL_SW_MAJOR_VERSION (1U)
|
||
#define UART_HAL_SW_MINOR_VERSION (1U)
|
||
#define UART_HAL_SW_PATCH_VERSION (1U)
|
||
|
||
/* ============================================ Define ============================================ */
|
||
|
||
/* =========================================== Typedef ============================================ */
|
||
/*!< Callback for UART module */
|
||
typedef void (*uart_callback_t)(void *driverState, uint32_t event, void *userData);
|
||
|
||
/*!
|
||
* @brief Define the enum of the events which can trigger UART callback.
|
||
*/
|
||
typedef enum
|
||
{
|
||
UART_EVENT_RX_FULL = 0x00U, /*!< Rx buffer is full */
|
||
UART_EVENT_TX_EMPTY = 0x01U, /*!< Tx buffer is empty */
|
||
UART_EVENT_END_TRANSFER = 0x02U, /*!< The current transfer is ending */
|
||
UART_EVENT_ERROR = 0x03U, /*!< An error occured during transfer */
|
||
UART_EVENT_DATA_MATCH = 0x04U, /*!< Rx data match */
|
||
UART_EVENT_IDLE_LINE = 0x05U, /*!< Idle line */
|
||
} uart_event_t;
|
||
|
||
/*!
|
||
* @brief no-blocking transfer type.
|
||
*/
|
||
typedef enum
|
||
{
|
||
UART_USING_DMA = 0U, /*!< Use DMA to perform UART transfer */
|
||
UART_USING_INTERRUPTS /*!< Use interrupts to perform UART transfer */
|
||
} uart_transfer_type_t;
|
||
|
||
/*!
|
||
* @brief UART number of bits in a character.
|
||
*/
|
||
typedef enum
|
||
{
|
||
UART_7_BITS_PER_CHAR = 0x0U, /*!< 7-bit data characters */
|
||
UART_8_BITS_PER_CHAR = 0x1U, /*!< 8-bit data characters */
|
||
UART_9_BITS_PER_CHAR = 0x2U /*!< 9-bit data characters */
|
||
} uart_bit_count_per_char_t;
|
||
|
||
/*!
|
||
* @brief UART parity mode.
|
||
*/
|
||
typedef enum
|
||
{
|
||
UART_PARITY_DISABLED = 0x0U, /*!< parity disabled */
|
||
UART_PARITY_EVEN = 0x1U, /*!< parity enabled, type even */
|
||
UART_PARITY_ODD = 0x2U /*!< parity enabled, type odd */
|
||
} uart_parity_mode_t;
|
||
|
||
/*!
|
||
* @brief UART number of stop bits.
|
||
*/
|
||
typedef enum
|
||
{
|
||
UART_ONE_STOP_BIT = 0x0U, /*!< one stop bit */
|
||
UART_TWO_STOP_BIT = 0x1U /*!< two stop bits */
|
||
} uart_stop_bit_count_t;
|
||
|
||
/*!
|
||
* @brief UART runtime state.
|
||
*/
|
||
typedef struct
|
||
{
|
||
const uint8_t *txBuff; /*!< The buffer of transmit data */
|
||
uint8_t *rxBuff; /*!< The buffer of received data */
|
||
volatile uint32_t txSize; /*!< The remaining number of bytes to be transmitted */
|
||
volatile uint32_t rxSize; /*!< The remaining number of bytes to be received */
|
||
volatile bool isTxBusy; /*!< True if transmit is active */
|
||
volatile bool isRxBusy; /*!< True if receive is active */
|
||
volatile bool isTxBlocking; /*!< True if transmit is blocking */
|
||
volatile bool isRxBlocking; /*!< True if receive is blocking */
|
||
uart_bit_count_per_char_t bitCountPerChar; /*!< number of bits(7/8/9 bits) in a char */
|
||
uart_callback_t rxCallback; /*!< Callback for data receive */
|
||
void *rxCallbackParam; /*!< Receive callback parameter pointer.*/
|
||
uart_callback_t txCallback; /*!< Callback for data send */
|
||
void *txCallbackParam; /*!< Transmit callback parameter pointer.*/
|
||
uart_transfer_type_t transferType; /*!< Type of UART transfer (interrupt or dma) */
|
||
uint8_t rxDMAChannel; /*!< DMA channel for UART receive. */
|
||
uint8_t txDMAChannel; /*!< DMA channel for UART transmit. */
|
||
semaphore_t rxComplete; /*!< Synchronization object for blocking Rx timeout condition */
|
||
semaphore_t txComplete; /*!< Synchronization object for blocking Tx timeout condition */
|
||
volatile status_t transmitStatus; /*!< Status of last transmit */
|
||
volatile status_t receiveStatus; /*!< Status of last receive */
|
||
uint8_t clockConfigType; /*!< Clock config type, use for DMA RX */
|
||
} uart_state_t;
|
||
|
||
/*!
|
||
* @brief UART configuration structure.
|
||
*/
|
||
typedef struct
|
||
{
|
||
uint32_t baudRate; /*!< UART baud rate */
|
||
uart_parity_mode_t parityMode; /*!< parity mode, disabled, even, odd */
|
||
uart_stop_bit_count_t stopBitCount; /*!< number of stop bits, 1 or 2 stop bits */
|
||
uart_bit_count_per_char_t bitCountPerChar; /*!< number of bits in a character (7, 8 or 9) */
|
||
uart_transfer_type_t transferType; /*!< Type of UART transfer (interrupt or dma) */
|
||
uint8_t rxDMAChannel; /*!< DMA rx channel for DMA transfer */
|
||
uint8_t txDMAChannel; /*!< DMA tx channel for DMA transfer */
|
||
uart_callback_t rxCallback; /*!< Callback for data receive */
|
||
void *rxCallbackParam; /*!< Receive callback parameter pointer.*/
|
||
uart_callback_t txCallback; /*!< Callback for data send */
|
||
void *txCallbackParam; /*!< Transmit callback parameter pointer.*/
|
||
} uart_user_config_t;
|
||
|
||
/* ========================================== Variables =========================================== */
|
||
|
||
/* ==================================== Functions declaration ===================================== */
|
||
/*!
|
||
* @brief Get UART module base address.
|
||
*
|
||
* @param[in] instance: UART module instance
|
||
* @return UART module base address
|
||
*/
|
||
UART_Type * UART_DRV_GetBase(uint32_t instance);
|
||
|
||
/*!
|
||
* @brief Initializes the UART configuration structure with default values.
|
||
*
|
||
* @param[out] uartUserConfig: Initializes a configuration structure received from the application
|
||
* with default values
|
||
* @return none
|
||
*/
|
||
void UART_DRV_GetDefaultConfig(uart_user_config_t *uartUserConfig);
|
||
|
||
/*!
|
||
* @brief Initializes an UART operation instance.
|
||
*
|
||
* @param[in] instance: UART instance number
|
||
* @param[in] uartUserConfig: user configuration structure of type uart_user_config_t
|
||
* @param[in] uartStatePtr: pointer to the UART driver state structure
|
||
* @return STATUS_SUCCESS if successful;
|
||
* STATUS_ERROR if an error occurred
|
||
*/
|
||
status_t UART_DRV_Init(uint32_t instance, uart_state_t *uartStatePtr, const uart_user_config_t *uartUserConfig);
|
||
|
||
/*!
|
||
* @brief Shuts down the UART by disabling interrupts and transmitter/receiver.
|
||
*
|
||
* @param[in] instance: UART instance number
|
||
* @return STATUS_SUCCESS if successful;
|
||
* STATUS_ERROR if an error occurred
|
||
*/
|
||
status_t UART_DRV_Deinit(uint32_t instance);
|
||
|
||
/*!
|
||
* @brief Installs callback function for the UART receive.
|
||
* After a callback is installed, it bypasses part of the UART IRQHandler logic.
|
||
* Therefore, the callback needs to handle the indexes of txBuff and txSize.
|
||
*
|
||
* @param[in] instance: The UART instance number.
|
||
* @param[in] function: The UART receive callback function.
|
||
* @param[in] rxBuff: The receive buffer used inside IRQHandler.
|
||
* This buffer must be kept as long as the callback is alive.
|
||
* @param[in] callbackParam: The UART receive callback parameter pointer.
|
||
* @return Former UART receive callback function pointer.
|
||
*/
|
||
uart_callback_t UART_DRV_InstallRxCallback(uint32_t instance, uart_callback_t function, void *callbackParam);
|
||
|
||
/*!
|
||
* @brief Installs callback function for the UART transmit.
|
||
* After a callback is installed, it bypasses part of the UART IRQHandler logic.
|
||
* Therefore, the callback needs to handle the indexes of txBuff and txSize.
|
||
*
|
||
* @param[in] instance: The UART instance number
|
||
* @param[in] function: The UART transmit callback function
|
||
* @param[in] txBuff: The transmit buffer used inside IRQHandler.
|
||
* This buffer must be kept as long as the callback is alive
|
||
* @param[in] callbackParam: The UART transmit callback parameter pointer
|
||
* @return Former UART transmit callback function pointer.
|
||
*/
|
||
uart_callback_t UART_DRV_InstallTxCallback(uint32_t instance, uart_callback_t function, void *callbackParam);
|
||
|
||
/*!
|
||
* @brief Sends data out through the UART module using a blocking method.
|
||
* Blocking means that the function does not return until the transmission is complete.
|
||
*
|
||
* @param[in] instance: UART instance number
|
||
* @param[in] txBuff: source buffer containing 8-bit data chars to send
|
||
* @param[in] txSize: the number of bytes to send
|
||
* @param[in] timeout: timeout value in milliseconds
|
||
* @return STATUS_SUCCESS if successful;
|
||
* STATUS_TIMEOUT if the timeout was reached;
|
||
* STATUS_BUSY if the resource is busy;
|
||
* STATUS_ERROR if an error occurred
|
||
*/
|
||
status_t UART_DRV_SendDataBlocking(uint32_t instance, const uint8_t *txBuff, uint32_t txSize, uint32_t timeout);
|
||
|
||
/*!
|
||
* @brief UART send data using polling mode
|
||
*
|
||
* @param[in] instance: UART instance
|
||
* @param[in] txBuff: The tx data buffer pointer
|
||
* @param[in] txSize: The tx data buffer bytes size
|
||
* @return STATUS_BUSY or STATUS_SUCCESS
|
||
*/
|
||
status_t UART_DRV_SendDataPolling(uint32_t instance, const uint8_t *txBuff, uint32_t txSize);
|
||
|
||
/*!
|
||
* @brief UART send data using non-blocking method (interrupt or DMA)
|
||
*
|
||
* @param[in] instance: UART instance
|
||
* @param[in] txBuff: The tx data buffer pointer
|
||
* @param[in] txSize: The tx data buffer bytes size
|
||
* @return STATUS_BUSY or STATUS_SUCCESS
|
||
*/
|
||
status_t UART_DRV_SendData(uint32_t instance, const uint8_t *txBuff, uint32_t txSize);
|
||
|
||
/*!
|
||
* @brief Get transmit status
|
||
*
|
||
* @param[in] instance: UART instance
|
||
* @param[out] bytesRemaining: Remaining bytes to be sent
|
||
* @return Transmit status
|
||
*/
|
||
status_t UART_DRV_GetTransmitStatus(uint32_t instance, uint32_t *bytesRemaining);
|
||
|
||
/*!
|
||
* @brief Terminates an non-blocking UART transmission early.
|
||
*
|
||
* @param[in] instance: UART instance
|
||
* @return STATUS_SUCCESS
|
||
*/
|
||
status_t UART_DRV_AbortSendingData(uint32_t instance);
|
||
|
||
/*!
|
||
* @brief UART receive data using blocking method, which will not return until
|
||
* the receive is complete.
|
||
*
|
||
* @param[in] instance: UART instance
|
||
* @param[out] rxBuff: The rx data buffer pointer
|
||
* @param[in] rxSize: The rx data buffer bytes size
|
||
* @param[in] timeout：Configurate timeout
|
||
* @return The receive status
|
||
*/
|
||
status_t UART_DRV_ReceiveDataBlocking(uint32_t instance, uint8_t *rxBuff, uint32_t rxSize, uint32_t timeout);
|
||
|
||
/*!
|
||
* @brief UART receive data using polling mode.
|
||
*
|
||
* @param[in] instance: UART instance
|
||
* @param[out] rxBuff: The rx data buffer pointer
|
||
* @param[in] rxSize: The rx data buffer bytes size
|
||
* @return Receive status
|
||
*/
|
||
status_t UART_DRV_ReceiveDataPolling(uint32_t instance, uint8_t *rxBuff, uint32_t rxSize);
|
||
|
||
/*!
|
||
* @brief UART receive data using non-blocking method(interrupt or DMA).
|
||
*
|
||
* @param[in] instance: UART instance
|
||
* @param[out] rxBuff: The rx data buffer pointer
|
||
* @param[in] rxSize: The rx data buffer bytes size
|
||
* @return STATUS_BUSY or STATUS_SUCCESS
|
||
*/
|
||
status_t UART_DRV_ReceiveData(uint32_t instance, uint8_t *rxBuff, uint32_t rxSize);
|
||
|
||
/*!
|
||
* @brief Get receive status.
|
||
*
|
||
* @param[in] instance: UART instance
|
||
* @param[out] bytesRemaining: Remaining bytes to receive
|
||
* @return Receive status
|
||
*/
|
||
status_t UART_DRV_GetReceiveStatus(uint32_t instance, uint32_t *bytesRemaining);
|
||
|
||
/*!
|
||
* @brief Terminates a non-blocking receive early.
|
||
*
|
||
* @param[in] instance: UART instance
|
||
* @return STATUS_SUCCESS
|
||
*/
|
||
status_t UART_DRV_AbortReceivingData(uint32_t instance);
|
||
|
||
/*!
|
||
* @brief Set UART baud rate.
|
||
*
|
||
* @param[in] instance: UART instance
|
||
* @param[in] desiredBaudRate: UART state pointer
|
||
* @return STATUS_BUSY, STATUS_ERROR or STATUS_SUCCESS
|
||
*/
|
||
status_t UART_DRV_SetBaudRate(uint32_t instance, uint32_t desiredBaudRate);
|
||
|
||
/*!
|
||
* @brief Get UART baud rate.
|
||
*
|
||
* @param[in] instance: UART instance
|
||
* @param[out] configuredBaudRate: Return the UART configured baud rate
|
||
* @return none
|
||
*/
|
||
void UART_DRV_GetBaudRate(uint32_t instance, uint32_t *configuredBaudRate);
|
||
|
||
/*!
|
||
* @brief Set the driver internal tx buffer.
|
||
*
|
||
* @param[in] instance: UART instance
|
||
* @param[in] txBuff: The tx data buffer pointer
|
||
* @param[in] txSize: The tx data buffer bytes size
|
||
* @return STATUS_SUCCESS
|
||
*/
|
||
status_t UART_DRV_SetTxBuffer(uint32_t instance, const uint8_t *txBuff, uint32_t txSize);
|
||
|
||
/*!
|
||
* @brief Set the driver internal rx buffer.
|
||
*
|
||
* @param[in] instance: UART instance
|
||
* @param[in] txBuff: The rx data buffer pointer
|
||
* @param[in] txSize: The rx data buffer bytes size
|
||
* @return STATUS_SUCCESS
|
||
*/
|
||
status_t UART_DRV_SetRxBuffer(uint32_t instance, uint8_t *rxBuff, uint32_t rxSize);
|
||
|
||
/*!
|
||
* @brief Get module version information.
|
||
*
|
||
* @param[out] versionInfo: Module version information address.
|
||
* @return void
|
||
*/
|
||
void UART_DRV_GetVersionInfo(Drv_VersionInfo_Type *versionInfo);
|
||
|
||
#if defined(__cplusplus)
|
||
}
|
||
#endif /* __cplusplus */
|
||
|
||
#endif /* UART_DRV_H */
|
||
|
||
/* ============================================= EOF ============================================== */
|