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