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