1 /* 2 * Copyright (C) 2017-2019 Alibaba Group Holding Limited 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 * 6 * Change Logs: 7 * Date Author Notes 8 * 2020-08-20 zx.chen header file for usart driver 9 */ 10 11 #ifndef _CSI_USART_H_ 12 #define _CSI_USART_H_ 13 14 15 #include <drv_common.h> 16 17 #ifdef __cplusplus 18 extern "C" { 19 #endif 20 /// definition for usart handle. 21 typedef void *usart_handle_t; 22 23 /****** USART specific error codes *****/ 24 typedef enum 25 { 26 USART_ERROR_MODE = (DRV_ERROR_SPECIFIC + 1), ///< Specified Mode not supported 27 USART_ERROR_BAUDRATE, ///< Specified baudrate not supported 28 USART_ERROR_DATA_BITS, ///< Specified number of Data bits not supported 29 USART_ERROR_PARITY, ///< Specified Parity not supported 30 USART_ERROR_STOP_BITS, ///< Specified number of Stop bits not supported 31 USART_ERROR_FLOW_CONTROL, ///< Specified Flow Control not supported 32 USART_ERROR_CPOL, ///< Specified Clock Polarity not supported 33 USART_ERROR_CPHA ///< Specified Clock Phase not supported 34 } usart_error_e; 35 36 /*----- USART Control Codes: Mode -----*/ 37 typedef enum 38 { 39 USART_MODE_ASYNCHRONOUS = 0, ///< USART (Asynchronous) 40 USART_MODE_SYNCHRONOUS_MASTER, ///< Synchronous Master 41 USART_MODE_SYNCHRONOUS_SLAVE, ///< Synchronous Slave (external clock signal) 42 USART_MODE_SINGLE_WIRE, ///< USART Single-wire (half-duplex) 43 USART_MODE_SINGLE_IRDA, ///< UART IrDA 44 USART_MODE_SINGLE_SMART_CARD, ///< UART Smart Card 45 } usart_mode_e; 46 47 /*----- USART Control Codes: Mode Parameters: Data Bits -----*/ 48 typedef enum 49 { 50 USART_DATA_BITS_5 = 0, ///< 5 Data bits 51 USART_DATA_BITS_6, ///< 6 Data bit 52 USART_DATA_BITS_7, ///< 7 Data bits 53 USART_DATA_BITS_8, ///< 8 Data bits (default) 54 USART_DATA_BITS_9 ///< 9 Data bits 55 } usart_data_bits_e; 56 57 /*----- USART Control Codes: Mode Parameters: Parity -----*/ 58 typedef enum 59 { 60 USART_PARITY_NONE = 0, ///< No Parity (default) 61 USART_PARITY_EVEN, ///< Even Parity 62 USART_PARITY_ODD, ///< Odd Parity 63 USART_PARITY_1, ///< Parity forced to 1 64 USART_PARITY_0 ///< Parity forced to 0 65 } usart_parity_e; 66 67 /*----- USART Control Codes: Mode Parameters: Stop Bits -----*/ 68 typedef enum 69 { 70 USART_STOP_BITS_1 = 0, ///< 1 Stop bit (default) 71 USART_STOP_BITS_2, ///< 2 Stop bits 72 USART_STOP_BITS_1_5, ///< 1.5 Stop bits 73 USART_STOP_BITS_0_5 ///< 0.5 Stop bits 74 } usart_stop_bits_e; 75 76 /*----- USART Control Codes: Mode Parameters: Clock Polarity (Synchronous mode) -----*/ 77 typedef enum 78 { 79 USART_CPOL0 = 0, ///< CPOL = 0 (default). data are captured on rising edge (low->high transition) 80 USART_CPOL1 ///< CPOL = 1. data are captured on falling edge (high->lowh transition) 81 } usart_cpol_e; 82 83 /*----- USART Control Codes: Mode Parameters: Clock Phase (Synchronous mode) -----*/ 84 typedef enum 85 { 86 USART_CPHA0 = 0, ///< CPHA = 0 (default). sample on first (leading) edge 87 USART_CPHA1 ///< CPHA = 1. sample on second (trailing) edge 88 } usart_cpha_e; 89 90 /*----- USART Control Codes: flush data type-----*/ 91 typedef enum 92 { 93 USART_FLUSH_WRITE, 94 USART_FLUSH_READ 95 } usart_flush_type_e; 96 97 /*----- USART Control Codes: flow control type-----*/ 98 typedef enum 99 { 100 USART_FLOWCTRL_NONE, 101 USART_FLOWCTRL_CTS, 102 USART_FLOWCTRL_RTS, 103 USART_FLOWCTRL_CTS_RTS 104 } usart_flowctrl_type_e; 105 106 /*----- USART Modem Control -----*/ 107 typedef enum 108 { 109 USART_RTS_CLEAR, ///< Deactivate RTS 110 USART_RTS_SET, ///< Activate RTS 111 USART_DTR_CLEAR, ///< Deactivate DTR 112 USART_DTR_SET ///< Activate DTR 113 } usart_modem_ctrl_e; 114 115 /*----- USART Modem Status -----*/ 116 typedef struct 117 { 118 uint32_t cts : 1; ///< CTS state: 1=Active, 0=Inactive 119 uint32_t dsr : 1; ///< DSR state: 1=Active, 0=Inactive 120 uint32_t dcd : 1; ///< DCD state: 1=Active, 0=Inactive 121 uint32_t ri : 1; ///< RI state: 1=Active, 0=Inactive 122 } usart_modem_stat_t; 123 124 /*----- USART Control Codes: on-off intrrupte type-----*/ 125 typedef enum 126 { 127 USART_INTR_WRITE, 128 USART_INTR_READ 129 } usart_intr_type_e; 130 131 /** 132 \brief USART Status 133 */ 134 typedef struct { 135 uint32_t tx_busy : 1; ///< Transmitter busy flag 136 uint32_t rx_busy : 1; ///< Receiver busy flag 137 uint32_t tx_underflow : 1; ///< Transmit data underflow detected (cleared on start of next send operation)(Synchronous Slave) 138 uint32_t rx_overflow : 1; ///< Receive data overflow detected (cleared on start of next receive operation) 139 uint32_t rx_break : 1; ///< Break detected on receive (cleared on start of next receive operation) 140 uint32_t rx_framing_error : 1; ///< Framing error detected on receive (cleared on start of next receive operation) 141 uint32_t rx_parity_error : 1; ///< Parity error detected on receive (cleared on start of next receive operation) 142 uint32_t tx_enable : 1; ///< Transmitter enable flag 143 uint32_t rx_enable : 1; ///< Receiver enbale flag 144 } usart_status_t; 145 146 /****** USART Event *****/ 147 typedef enum 148 { 149 USART_EVENT_SEND_COMPLETE = 0, ///< Send completed; however USART may still transmit data 150 USART_EVENT_RECEIVE_COMPLETE = 1, ///< Receive completed 151 USART_EVENT_TRANSFER_COMPLETE = 2, ///< Transfer completed 152 USART_EVENT_TX_COMPLETE = 3, ///< Transmit completed (optional) 153 USART_EVENT_TX_UNDERFLOW = 4, ///< Transmit data not available (Synchronous Slave) 154 USART_EVENT_RX_OVERFLOW = 5, ///< Receive data overflow 155 USART_EVENT_RX_TIMEOUT = 6, ///< Receive character timeout (optional) 156 USART_EVENT_RX_BREAK = 7, ///< Break detected on receive 157 USART_EVENT_RX_FRAMING_ERROR = 8, ///< Framing error detected on receive 158 USART_EVENT_RX_PARITY_ERROR = 9, ///< Parity error detected on receive 159 USART_EVENT_CTS = 10, ///< CTS state changed (optional) 160 USART_EVENT_DSR = 11, ///< DSR state changed (optional) 161 USART_EVENT_DCD = 12, ///< DCD state changed (optional) 162 USART_EVENT_RI = 13, ///< RI state changed (optional) 163 USART_EVENT_RECEIVED = 14, ///< Data Received, only in usart fifo, call receive()/transfer() get the data 164 } usart_event_e; 165 166 typedef void (*usart_event_cb_t)(int32_t idx, usart_event_e event); ///< Pointer to \ref usart_event_cb_t : USART Event call back. 167 168 /** 169 \brief USART Driver Capabilities. 170 */ 171 typedef struct { 172 uint32_t asynchronous : 1; ///< supports UART (Asynchronous) mode 173 uint32_t synchronous_master : 1; ///< supports Synchronous Master mode 174 uint32_t synchronous_slave : 1; ///< supports Synchronous Slave mode 175 uint32_t single_wire : 1; ///< supports UART Single-wire mode 176 uint32_t irda : 1; ///< supports UART IrDA mode 177 uint32_t smart_card : 1; ///< supports UART Smart Card mode 178 uint32_t smart_card_clock : 1; ///< Smart Card Clock generator available 179 uint32_t flow_control_rts : 1; ///< RTS Flow Control available 180 uint32_t flow_control_cts : 1; ///< CTS Flow Control available 181 uint32_t event_tx_complete : 1; ///< Transmit completed event: \ref USART_EVENT_TX_COMPLETE 182 uint32_t event_rx_timeout : 1; ///< Signal receive character timeout event: \ref USART_EVENT_RX_TIMEOUT 183 uint32_t rts : 1; ///< RTS Line: 0=not available, 1=available 184 uint32_t cts : 1; ///< CTS Line: 0=not available, 1=available 185 uint32_t dtr : 1; ///< DTR Line: 0=not available, 1=available 186 uint32_t dsr : 1; ///< DSR Line: 0=not available, 1=available 187 uint32_t dcd : 1; ///< DCD Line: 0=not available, 1=available 188 uint32_t ri : 1; ///< RI Line: 0=not available, 1=available 189 uint32_t event_cts : 1; ///< Signal CTS change event: \ref USART_EVENT_CTS 190 uint32_t event_dsr : 1; ///< Signal DSR change event: \ref USART_EVENT_DSR 191 uint32_t event_dcd : 1; ///< Signal DCD change event: \ref USART_EVENT_DCD 192 uint32_t event_ri : 1; ///< Signal RI change event: \ref USART_EVENT_RI 193 } usart_capabilities_t; 194 195 /** 196 \brief Initialize USART Interface. 1. Initializes the resources needed for the USART interface 2.registers event callback function 197 \param[in] idx usart index 198 \param[in] cb_event event call back function \ref usart_event_cb_t 199 \return return usart handle if success 200 */ 201 usart_handle_t csi_usart_initialize(int32_t idx, usart_event_cb_t cb_event); 202 203 /** 204 \brief De-initialize USART Interface. stops operation and releases the software resources used by the interface 205 \param[in] handle usart handle to operate. 206 \return error code 207 */ 208 int32_t csi_usart_uninitialize(usart_handle_t handle); 209 /** 210 \brief Get driver capabilities. 211 \param[in] idx usart index 212 \return \ref usart_capabilities_t 213 */ 214 usart_capabilities_t csi_usart_get_capabilities(int32_t idx); 215 216 /** 217 \brief config usart mode. 218 \param[in] handle usart handle to operate. 219 \param[in] baud baud rate. 220 \param[in] mode \ref usart_mode_e . 221 \param[in] parity \ref usart_parity_e . 222 \param[in] stopbits \ref usart_stop_bits_e . 223 \param[in] bits \ref usart_data_bits_e . 224 \return error code 225 */ 226 int32_t csi_usart_config(usart_handle_t handle, 227 uint32_t baud, 228 usart_mode_e mode, 229 usart_parity_e parity, 230 usart_stop_bits_e stopbits, 231 usart_data_bits_e bits); 232 233 234 /** 235 \brief Start sending data to USART transmitter,(received data is ignored). 236 This function is non-blocking,\ref usart_event_e is signaled when operation completes or error happens. 237 \ref csi_usart_get_status can get operation status. 238 \param[in] handle usart handle to operate. 239 \param[in] data Pointer to buffer with data to send to USART transmitter. data_type is : uint8_t for 5..8 data bits, uint16_t for 9 data bits 240 \param[in] num Number of data items to send 241 \return error code 242 */ 243 int32_t csi_usart_send(usart_handle_t handle, const void *data, uint32_t num); 244 245 /** 246 \brief Abort Send data to USART transmitter 247 \param[in] handle usart handle to operate. 248 \return error code 249 */ 250 int32_t csi_usart_abort_send(usart_handle_t handle); 251 252 /** 253 \brief Start receiving data from USART receiver. \n 254 This function is non-blocking,\ref usart_event_e is signaled when operation completes or error happens. 255 \ref csi_usart_get_status can get operation status. 256 \param[in] handle usart handle to operate. 257 \param[out] data Pointer to buffer for data to receive from USART receiver.data_type is : uint8_t for 5..8 data bits, uint16_t for 9 data bits 258 \param[in] num Number of data items to receive 259 \return error code 260 */ 261 int32_t csi_usart_receive(usart_handle_t handle, void *data, uint32_t num); 262 263 /** 264 \brief query data from UART receiver FIFO. 265 \param[in] handle usart handle to operate. 266 \param[out] data Pointer to buffer for data to receive from UART receiver 267 \param[in] num Number of data items to receive 268 \return fifo data num to receive 269 */ 270 int32_t csi_usart_receive_query(usart_handle_t handle, void *data, uint32_t num); 271 272 /** 273 \brief Abort Receive data from USART receiver 274 \param[in] handle usart handle to operate. 275 \return error code 276 */ 277 int32_t csi_usart_abort_receive(usart_handle_t handle); 278 279 /** 280 \brief Start synchronously sends data to the USART transmitter and receives data from the USART receiver. used in synchronous mode 281 This function is non-blocking,\ref usart_event_e is signaled when operation completes or error happens. 282 \ref csi_usart_get_status can get operation status. 283 \param[in] handle usart handle to operate. 284 \param[in] data_out Pointer to buffer with data to send to USART transmitter.data_type is : uint8_t for 5..8 data bits, uint16_t for 9 data bits 285 \param[out] data_in Pointer to buffer for data to receive from USART receiver.data_type is : uint8_t for 5..8 data bits, uint16_t for 9 data bits 286 \param[in] num Number of data items to transfer 287 \return error code 288 */ 289 int32_t csi_usart_transfer(usart_handle_t handle, const void *data_out, void *data_in, uint32_t num); 290 291 /** 292 \brief abort sending/receiving data to/from USART transmitter/receiver. 293 \param[in] handle usart handle to operate. 294 \return error code 295 */ 296 int32_t csi_usart_abort_transfer(usart_handle_t handle); 297 298 /** 299 \brief Get USART status. 300 \param[in] handle usart handle to operate. 301 \return USART status \ref usart_status_t 302 */ 303 usart_status_t csi_usart_get_status(usart_handle_t handle); 304 305 /** 306 \brief flush receive/send data. 307 \param[in] handle usart handle to operate. 308 \param[in] type \ref usart_flush_type_e . 309 \return error code 310 */ 311 int32_t csi_usart_flush(usart_handle_t handle, usart_flush_type_e type); 312 313 /** 314 \brief set interrupt mode. 315 \param[in] handle usart handle to operate. 316 \param[in] type \ref usart_intr_type_e. 317 \param[in] flag 0-OFF, 1-ON. 318 \return error code 319 */ 320 int32_t csi_usart_set_interrupt(usart_handle_t handle, usart_intr_type_e type, int32_t flag); 321 322 /** 323 \brief set the baud rate of usart. 324 \param[in] baud usart base to operate. 325 \param[in] baudrate baud rate 326 \return error code 327 */ 328 int32_t csi_usart_config_baudrate(usart_handle_t handle, uint32_t baud); 329 330 /** 331 \brief config usart mode. 332 \param[in] handle usart handle to operate. 333 \param[in] mode \ref usart_mode_e 334 \return error code 335 */ 336 int32_t csi_usart_config_mode(usart_handle_t handle, usart_mode_e mode); 337 338 /** 339 \brief config usart parity. 340 \param[in] handle usart handle to operate. 341 \param[in] parity \ref usart_parity_e 342 \return error code 343 */ 344 int32_t csi_usart_config_parity(usart_handle_t handle, usart_parity_e parity); 345 346 /** 347 \brief config usart stop bit number. 348 \param[in] handle usart handle to operate. 349 \param[in] stopbits \ref usart_stop_bits_e 350 \return error code 351 */ 352 int32_t csi_usart_config_stopbits(usart_handle_t handle, usart_stop_bits_e stopbit); 353 354 /** 355 \brief config usart data length. 356 \param[in] handle usart handle to operate. 357 \param[in] databits \ref usart_data_bits_e 358 \return error code 359 */ 360 int32_t csi_usart_config_databits(usart_handle_t handle, usart_data_bits_e databits); 361 362 /** 363 \brief get character in query mode. 364 \param[in] handle usart handle to operate. 365 \param[out] ch the pointer to the received character. 366 \return error code 367 */ 368 int32_t csi_usart_getchar(usart_handle_t handle, uint8_t *ch); 369 370 /** 371 \brief transmit character in query mode. 372 \param[in] handle usart handle to operate. 373 \param[in] ch the input character 374 \return error code 375 */ 376 int32_t csi_usart_putchar(usart_handle_t handle, uint8_t ch); 377 378 /** 379 \brief Get usart send data count. 380 \param[in] handle usart handle to operate. 381 \return number of currently transmitted data bytes 382 */ 383 uint32_t csi_usart_get_tx_count(usart_handle_t handle); 384 385 /** 386 \brief Get usart received data count. 387 \param[in] handle usart handle to operate. 388 \return number of currently received data bytes 389 */ 390 uint32_t csi_usart_get_rx_count(usart_handle_t handle); 391 392 /** 393 \brief control usart power. 394 \param[in] handle usart handle to operate. 395 \param[in] state power state.\ref csi_power_stat_e. 396 \return error code 397 */ 398 int32_t csi_usart_power_control(usart_handle_t handle, csi_power_stat_e state); 399 400 /** 401 \brief config usart flow control type. 402 \param[in] handle usart handle to operate. 403 \param[in] flowctrl_type flow control type.\ref usart_flowctrl_type_e. 404 \return error code 405 */ 406 int32_t csi_usart_config_flowctrl(usart_handle_t handle, 407 usart_flowctrl_type_e flowctrl_type); 408 409 /** 410 \brief config usart clock Polarity and Phase. 411 \param[in] handle usart handle to operate. 412 \param[in] cpol Clock Polarity.\ref usart_cpol_e. 413 \param[in] cpha Clock Phase.\ref usart_cpha_e. 414 \return error code 415 */ 416 int32_t csi_usart_config_clock(usart_handle_t handle, usart_cpol_e cpol, usart_cpha_e cpha); 417 418 /** 419 \brief control the transmitter. 420 \param[in] handle usart handle to operate. 421 \param[in] enable 1 - enable the transmitter. 0 - disable the transmitter 422 \return error code 423 */ 424 int32_t csi_usart_control_tx(usart_handle_t handle, uint32_t enable); 425 426 /** 427 \brief control the receiver. 428 \param[in] handle usart handle to operate. 429 \param[in] enable 1 - enable the receiver. 0 - disable the receiver 430 \return error code 431 */ 432 int32_t csi_usart_control_rx(usart_handle_t handle, uint32_t enable); 433 434 /** 435 \brief control the break. 436 \param[in] handle usart handle to operate. 437 \param[in] enable 1- Enable continuous Break transmission,0 - disable continuous Break transmission 438 \return error code 439 */ 440 int32_t csi_usart_control_break(usart_handle_t handle, uint32_t enable); 441 442 #ifdef __cplusplus 443 } 444 #endif 445 446 #endif /* _CSI_USART_H_ */ 447