1 /* 2 * Copyright (C) 2017-2020 Alibaba Group Holding Limited 3 */ 4 5 /****************************************************************************** 6 * @file drv/uart.h 7 * @brief Header File for UART Driver 8 * @version V1.0 9 * @date 08. Apr 2020 10 * @model uart 11 ******************************************************************************/ 12 13 #ifndef _DRV_UART_H_ 14 #define _DRV_UART_H_ 15 16 #include <drv/common.h> 17 #include <drv/dma.h> 18 19 #ifdef __cplusplus 20 extern "C" { 21 #endif 22 23 /*----- UART Control Codes: Mode Parameters: Data Bits -----*/ 24 typedef enum { 25 UART_DATA_BITS_5 = 0, ///< 5 Data bits 26 UART_DATA_BITS_6, ///< 6 Data bit 27 UART_DATA_BITS_7, ///< 7 Data bits 28 UART_DATA_BITS_8, ///< 8 Data bits (default) 29 UART_DATA_BITS_9 ///< 9 Data bits 30 } csi_uart_data_bits_t; 31 32 /*----- UART Control Codes: Mode Parameters: Parity -----*/ 33 typedef enum { 34 UART_PARITY_NONE = 0, ///< No Parity (default) 35 UART_PARITY_EVEN, ///< Even Parity 36 UART_PARITY_ODD, ///< Odd Parity 37 } csi_uart_parity_t; 38 39 /*----- UART Control Codes: Mode Parameters: Stop Bits -----*/ 40 typedef enum { 41 UART_STOP_BITS_1 = 0, ///< 1 Stop bit (default) 42 UART_STOP_BITS_2, ///< 2 Stop bits 43 UART_STOP_BITS_1_5, ///< 1.5 Stop bits 44 } csi_uart_stop_bits_t; 45 46 /*----- UART Control Codes: Mode Parameters: Flow Control -----*/ 47 typedef enum { 48 UART_FLOWCTRL_NONE = 0, ///< none flowctrl 49 UART_FLOWCTRL_RTS, ///< RTS 50 UART_FLOWCTRL_CTS, ///< CTS 51 UART_FLOWCTRL_RTS_CTS ///< RTS & CTS 52 } csi_uart_flowctrl_t; 53 54 /****** UART Event *****/ 55 typedef enum { 56 UART_EVENT_SEND_COMPLETE = 0, ///< Send data completed. 57 UART_EVENT_RECEIVE_COMPLETE, ///< Receive data completed. 58 UART_EVENT_RECEIVE_FIFO_READABLE, ///< Data in uart fifo, call csi_uart_receive() get the data. 59 UART_ENENT_BREAK_INTR, ///< the serial input,sin, is held in a logic '0' state for longer than the sum of start time+data bits+parity+stop bits. 60 UART_EVENT_ERROR_OVERFLOW, ///< A new data character was received before the previous data was read. 61 UART_EVENT_ERROR_PARITY, ///< Occur parity error in the receiver. 62 UART_EVENT_ERROR_FRAMING ///< the receiver does not detect a valid STOP bit in the received data. 63 } csi_uart_event_t; 64 65 ///< definition for uart. 66 typedef struct csi_uart csi_uart_t; 67 68 struct csi_uart { 69 csi_dev_t dev; 70 void (*callback)(csi_uart_t *uart, csi_uart_event_t event, void *arg); 71 void *arg; 72 uint8_t *tx_data; 73 uint32_t tx_size; 74 uint8_t *rx_data; 75 uint32_t rx_size; 76 csi_dma_ch_t *tx_dma; 77 csi_dma_ch_t *rx_dma; 78 csi_error_t (*send)(csi_uart_t *uart, const void *data, uint32_t size); 79 csi_error_t (*receive)(csi_uart_t *uart, void *data, uint32_t size); 80 csi_state_t state; 81 void *priv; 82 }; 83 84 /** 85 \brief Initializes the resources needed for the UART interface. 86 \param[in] uart Operate handle. 87 \param[in] idx The device idx. 88 \return Error code. 89 */ 90 csi_error_t csi_uart_init(csi_uart_t *uart, uint32_t idx); 91 92 /** 93 \brief De-initialize UART Interface. stops operation and releases the software resources used by the interface. 94 \param[in] uart Operate handle. 95 \return Error code. 96 */ 97 void csi_uart_uninit(csi_uart_t *uart); 98 99 /** 100 \brief Attach the callback handler to UART. 101 \param[in] uart Operate handle. 102 \param[in] callback Callback function. 103 \param[in] arg User can define it by himself as callback's param. 104 \return Error code. 105 */ 106 csi_error_t csi_uart_attach_callback(csi_uart_t *uart, void *callback, void *arg); 107 108 /** 109 \brief Detach the callback handler. 110 \param[in] uart Operate handle. 111 */ 112 void csi_uart_detach_callback(csi_uart_t *uart); 113 114 /** 115 \brief Config the baudrate. 116 \param[in] uart UART handle to operate. 117 \param[in] baud UART baudrate. 118 \return Error code. 119 */ 120 csi_error_t csi_uart_baud(csi_uart_t *uart, uint32_t baud); 121 122 /** 123 \brief Config the uart format. 124 \param[in] uart UART handle to operate. 125 \param[in] data_bit UART data bits. 126 \param[in] parity UART data parity. 127 \param[in] stop_bit UART stop bits. 128 \return Error code. 129 */ 130 csi_error_t csi_uart_format(csi_uart_t *uart, csi_uart_data_bits_t data_bits, 131 csi_uart_parity_t parity, csi_uart_stop_bits_t stop_bits); 132 133 /** 134 \brief Config the uart flow control. 135 \param[in] uart UART handle to operate. 136 \param[in] flowctrl UART flow control. 137 \return Error code. 138 */ 139 csi_error_t csi_uart_flowctrl(csi_uart_t *uart, csi_uart_flowctrl_t flowctrl); 140 141 /** 142 \brief Start send data to UART transmitter, this function is blocking. 143 \param[in] uart UART handle to operate. 144 \param[in] data Pointer to buffer with data to send to UART transmitter. 145 \param[in] size Number of data to send (byte). 146 \param[in] timeout The timeout between bytes(ms). 147 \return the num of data which is sent successfully or CSI_ERROR. 148 */ 149 int32_t csi_uart_send(csi_uart_t *uart, const void *data, uint32_t size, uint32_t timeout); 150 151 /** 152 \brief Start send data to UART transmitter, this function is non-blocking. 153 \param[in] uart UART handle to operate. 154 \param[in] data Pointer to buffer with data to send to UART transmitter. 155 \param[in] size Number of data to send (byte). 156 \return Error code. 157 */ 158 csi_error_t csi_uart_send_async(csi_uart_t *uart, const void *data, uint32_t size); 159 160 /** 161 \brief Query data from UART receiver FIFO, this function is blocking. 162 \param[in] uart UART handle to operate. 163 \param[out] data Pointer to buffer for data to receive from UART receiver. 164 \param[in] size Number of data to receive. 165 \param[in] timeout The timeout between bytes(ms). 166 \return the num of data witch is received successfully or CSI_ERROR. 167 */ 168 int32_t csi_uart_receive(csi_uart_t *uart, void *data, uint32_t size, uint32_t timeout); 169 170 /** 171 \brief Start receiving data from UART receiver, this function is non-blocking. 172 \param[in] uart UART handle to operate. 173 \param[out] data Pointer to buffer for data to receive from UART receiver. 174 \param[in] size Number of data to receive (byte). 175 \return Error code. 176 */ 177 csi_error_t csi_uart_receive_async(csi_uart_t *uart, void *data, uint32_t size); 178 179 /** 180 \brief Get character in query mode. 181 \param[in] uart UART handle to operate. 182 \return the character to get. 183 */ 184 uint8_t csi_uart_getc(csi_uart_t *uart); 185 186 /** 187 \brief Send character in query mode. 188 \param[in] uart UART handle to operate. 189 \param[in] ch The character to be send. 190 */ 191 void csi_uart_putc(csi_uart_t *uart, uint8_t ch); 192 193 /** 194 \brief Link DMA channel to uart device. 195 \param[in] uart UART handle to operate. 196 \param[in] tx_dma The DMA channel handle for send, when it is NULL means to unlink the channel. 197 \param[in] rx_dma The DMA channel handle for receive, when it is NULL means to unlink the channel. 198 \return Error code. 199 */ 200 csi_error_t csi_uart_link_dma(csi_uart_t *uart, csi_dma_ch_t *tx_dma, csi_dma_ch_t *rx_dma); 201 202 /** 203 \brief Get the state of uart device. 204 \param[in] uart UART handle to operate. 205 \param[out] state The state of uart device. 206 \return Error code. 207 */ 208 csi_error_t csi_uart_get_state(csi_uart_t *uart, csi_state_t *state); 209 210 /** 211 \brief Enable uart power manage. 212 \param[in] uart UART handle to operate. 213 \return Error code. 214 */ 215 csi_error_t csi_uart_enable_pm(csi_uart_t *uart); 216 217 /** 218 \brief Disable uart power manage. 219 \param[in] uart UART handle to operate. 220 */ 221 void csi_uart_disable_pm(csi_uart_t *uart); 222 223 #ifdef __cplusplus 224 } 225 #endif 226 227 #endif /* _DRV_UART_H_ */ 228