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