git.sur5r.net Git - freertos/blob - FreeRTOS/Demo/T-HEAD_CB2201_CDK/csi/csi_driver/include/drv_usart.h

   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     EDRV_USART_MODE  = (EDRV_SPECIFIC + 1),      ///< Specified Mode not supported
  38     EDRV_USART_BAUDRATE,                         ///< Specified baudrate not supported
  39     EDRV_USART_DATA_BITS,                        ///< Specified number of Data bits not supported
  40     EDRV_USART_PARITY,                           ///< Specified Parity not supported
  41     EDRV_USART_STOP_BITS,                        ///< Specified number of Stop bits not supported
  42     EDRV_USART_FLOW_CONTROL,                     ///< Specified Flow Control not supported
  43     EDRV_USART_CPOL,                             ///< Specified Clock Polarity not supported
  44     EDRV_USART_CPHA                              ///< Specified Clock Phase not supported
  45 } drv_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->lowh 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 intrrupte 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 } usart_status_t;
 143
 144 /****** USART Event *****/
 145 typedef enum {
 146     USART_EVENT_SEND_COMPLETE       = 0,  ///< Send completed; however USART may still transmit data
 147     USART_EVENT_RECEIVE_COMPLETE    = 1,  ///< Receive completed
 148     USART_EVENT_TRANSFER_COMPLETE   = 2,  ///< Transfer completed
 149     USART_EVENT_TX_COMPLETE         = 3,  ///< Transmit completed (optional)
 150     USART_EVENT_TX_UNDERFLOW        = 4,  ///< Transmit data not available (Synchronous Slave)
 151     USART_EVENT_RX_OVERFLOW         = 5,  ///< Receive data overflow
 152     USART_EVENT_RX_TIMEOUT          = 6,  ///< Receive character timeout (optional)
 153     USART_EVENT_RX_BREAK            = 7,  ///< Break detected on receive
 154     USART_EVENT_RX_FRAMING_ERROR    = 8,  ///< Framing error detected on receive
 155     USART_EVENT_RX_PARITY_ERROR     = 9,  ///< Parity error detected on receive
 156     USART_EVENT_CTS                 = 10, ///< CTS state changed (optional)
 157     USART_EVENT_DSR                 = 11, ///< DSR state changed (optional)
 158     USART_EVENT_DCD                 = 12, ///< DCD state changed (optional)
 159     USART_EVENT_RI                  = 13, ///< RI  state changed (optional)
 160     USART_EVENT_RECEIVED            = 14,  ///< Received data, but no send()/receive()/transfer() called
 161 } usart_event_e;
 162
 163 typedef void (*usart_event_cb_t)(usart_event_e event, void *cb_arg);   ///< Pointer to \ref usart_event_cb_t : USART Event call back.
 164
 165 /**
 166 \brief USART Driver Capabilities.
 167 */
 168 typedef struct  {
 169     uint32_t asynchronous       : 1;      ///< supports UART (Asynchronous) mode
 170     uint32_t synchronous_master : 1;      ///< supports Synchronous Master mode
 171     uint32_t synchronous_slave  : 1;      ///< supports Synchronous Slave mode
 172     uint32_t single_wire        : 1;      ///< supports UART Single-wire mode
 173     uint32_t irda               : 1;      ///< supports UART IrDA mode
 174     uint32_t smart_card         : 1;      ///< supports UART Smart Card mode
 175     uint32_t smart_card_clock   : 1;      ///< Smart Card Clock generator available
 176     uint32_t flow_control_rts   : 1;      ///< RTS Flow Control available
 177     uint32_t flow_control_cts   : 1;      ///< CTS Flow Control available
 178     uint32_t event_tx_complete  : 1;      ///< Transmit completed event: \ref ARM_USART_EVENT_TX_COMPLETE
 179     uint32_t event_rx_timeout   : 1;      ///< Signal receive character timeout event: \ref ARM_USART_EVENT_RX_TIMEOUT
 180     uint32_t rts                : 1;      ///< RTS Line: 0=not available, 1=available
 181     uint32_t cts                : 1;      ///< CTS Line: 0=not available, 1=available
 182     uint32_t dtr                : 1;      ///< DTR Line: 0=not available, 1=available
 183     uint32_t dsr                : 1;      ///< DSR Line: 0=not available, 1=available
 184     uint32_t dcd                : 1;      ///< DCD Line: 0=not available, 1=available
 185     uint32_t ri                 : 1;      ///< RI Line: 0=not available, 1=available
 186     uint32_t event_cts          : 1;      ///< Signal CTS change event: \ref ARM_USART_EVENT_CTS
 187     uint32_t event_dsr          : 1;      ///< Signal DSR change event: \ref ARM_USART_EVENT_DSR
 188     uint32_t event_dcd          : 1;      ///< Signal DCD change event: \ref ARM_USART_EVENT_DCD
 189     uint32_t event_ri           : 1;      ///< Signal RI change event: \ref ARM_USART_EVENT_RI
 190 } usart_capabilities_t;
 191
 192 /**
 193   \brief       Initialize USART Interface. 1. Initializes the resources needed for the USART interface 2.registers event callback function
 194   \param[in]   tx usart pin of tx
 195   \param[in]   rx usart pin of rx
 196   \param[in]   cb_event  Pointer to \ref usart_event_cb_t
 197   \param[in]   cb_arg    argument for cb_event
 198   \return      return usart handle if success
 199 */
 200 usart_handle_t csi_usart_initialize(pin_t tx, pin_t rx, usart_event_cb_t cb_event, void *cb_arg);
 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]   handle  usart handle to operate.
 211   \return      \ref usart_capabilities_t
 212 */
 213 usart_capabilities_t csi_usart_get_capabilities(usart_handle_t handle);
 214
 215 /**
 216   \brief       config usart mode.
 217   \param[in]   handle  usart handle to operate.
 218   \param[in]   sysclk    system clock.
 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 sysclk,
 228                          uint32_t baud,
 229                          usart_mode_e mode,
 230                          usart_parity_e parity,
 231                          usart_stop_bits_e stopbits,
 232                          usart_data_bits_e bits);
 233
 234 /**
 235   \brief       config usart default tx value. used in synchronous mode
 236   \param[in]   handle  usart handle to operate.
 237   \param[in]   value  default tx value
 238   \return      error code
 239 */
 240 int32_t csi_usart_set_default_tx_value(usart_handle_t handle, uint32_t value);
 241
 242 /**
 243   \brief       Start sending data to USART transmitter,(received data is ignored).
 244                This function is non-blocking,\ref usart_event_e is signaled when operation completes or error happens.
 245                \ref csi_usart_get_status can indicates operation status.
 246   \param[in]   handle  usart handle to operate.
 247   \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
 248   \param[in]   num   Number of data items to send
 249   \return      error code
 250 */
 251 int32_t csi_usart_send(usart_handle_t handle, const void *data, uint32_t num/*,bool asynch*/);
 252
 253 /**
 254   \brief       Abort Send data to USART transmitter
 255   \param[in]   handle  usart handle to operate.
 256   \return      error code
 257 */
 258 int32_t csi_usart_abort_send(usart_handle_t handle);
 259
 260 /**
 261   \brief       Start receiving data from USART receiver.transmits the default value as specified by csi_usart_set_default_tx_value. \n
 262                This function is non-blocking,\ref usart_event_e is signaled when operation completes or error happens.
 263                \ref csi_usart_get_status can indicates operation status.
 264   \param[in]   handle  usart handle to operate.
 265   \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
 266   \param[in]   num   Number of data items to receive
 267   \return      error code
 268 */
 269 int32_t csi_usart_receive(usart_handle_t handle, void *data, uint32_t num/*,bool asynch*/);
 270
 271 /**
 272   \brief       query data from UART receiver FIFO.
 273   \param[in]   handle  usart handle to operate.
 274   \param[out]  data  Pointer to buffer for data to receive from UART receiver
 275   \param[in]   num   Number of data items to receive
 276   \return      receive fifo data num
 277 */
 278 int32_t csi_usart_receive_query(usart_handle_t handle, void *data, uint32_t num/*,bool asynch*/);
 279
 280 /**
 281   \brief       Abort Receive data from USART receiver
 282   \param[in]   handle  usart handle to operate.
 283   \return      error code
 284 */
 285 int32_t csi_usart_abort_receive(usart_handle_t handle);
 286
 287 /**
 288   \brief       Start synchronously sends data to the USART transmitter and receives data from the USART receiver. used in synchronous mode
 289                This function is non-blocking,\ref usart_event_e is signaled when operation completes or error happens.
 290                \ref csi_usart_get_status can indicates operation status.
 291   \param[in]   handle  usart handle to operate.
 292   \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
 293   \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
 294   \param[in]   num       Number of data items to transfer
 295   \return      error code
 296 */
 297 int32_t csi_usart_transfer(usart_handle_t handle, const void *data_out, void *data_in, uint32_t num/*,bool asynch*/);
 298
 299 /**
 300   \brief       abort sending/receiving data to/from USART transmitter/receiver.
 301   \param[in]   handle  usart handle to operate.
 302   \return      error code
 303 */
 304 int32_t csi_usart_abort_transfer(usart_handle_t handle);
 305
 306 /**
 307   \brief       Get USART status.
 308   \param[in]   handle  usart handle to operate.
 309   \return      USART status \ref usart_status_t
 310 */
 311 usart_status_t csi_usart_get_status(usart_handle_t handle);
 312
 313 /**
 314   \brief       flush receive/send data.
 315   \param[in]   handle usart handle to operate.
 316   \param[in]   type \ref usart_flush_type_e .
 317   \return      \ref execution_status
 318 */
 319 int32_t csi_usart_flush(usart_handle_t handle, usart_flush_type_e type);
 320
 321 /**
 322   \brief       control interrupt on/off.
 323   \param[in]   handle usart handle to operate.
 324   \param[in]   type \ref usart_intr_type_e.
 325   \param[in]   flag 0-OFF, 1-ON.
 326   \return      error code
 327 */
 328 int32_t csi_usart_interrupt_on_off(usart_handle_t handle, usart_intr_type_e type, int flag);
 329
 330 /**
 331   \brief       set the baut drate of usart.
 332   \param[in]   addr  usart base to operate.
 333   \param[in]   baudrate baud rate
 334   \param[in]   apbfreq the frequency of the apb.
 335   \return      error code
 336 */
 337 int32_t csi_usart_config_baudrate(usart_handle_t handle, uint32_t baudrate, uint32_t apbfreq);
 338
 339 /**
 340   \brief       config usart mode.
 341   \param[in]   handle  usart handle to operate.
 342   \param[in]   mode    \ref usart_mode_e
 343   \return      error code
 344 */
 345 int32_t csi_usart_config_mode(usart_handle_t handle, usart_mode_e mode);
 346
 347 /**
 348   \brief       config usart parity.
 349   \param[in]   handle  usart handle to operate.
 350   \param[in]   parity    \ref usart_parity_e
 351   \return      error code
 352 */
 353 int32_t csi_usart_config_parity(usart_handle_t handle, usart_parity_e parity);
 354
 355 /**
 356   \brief       config usart stop bit number.
 357   \param[in]   handle  usart handle to operate.
 358   \param[in]   stopbits  \ref usart_stop_bits_e
 359   \return      error code
 360 */
 361 int32_t dw_usart_config_stopbits(usart_handle_t handle, usart_stop_bits_e stopbit);
 362
 363 /**
 364   \brief       config usart data length.
 365   \param[in]   handle  usart handle to operate.
 366   \param[in]   databits      \ref usart_data_bits_e
 367   \return      error code
 368 */
 369 int32_t csi_usart_config_databits(usart_handle_t handle, usart_data_bits_e databits);
 370
 371 /**
 372   \brief       get character in query mode.
 373   \param[in]   handle  usart handle to operate.
 374   \param[in]   the pointer to the received character if return 0.
 375   \return      error code
 376 */
 377 int32_t csi_usart_getchar(usart_handle_t handle, uint8_t *ch);
 378
 379 /**
 380   \brief       transmit character in query mode.
 381   \param[in]   handle  usart handle to operate.
 382   \param[in]   ch  the input character
 383   \return      error code
 384 */
 385 int32_t csi_usart_putchar(usart_handle_t handle, uint8_t ch);
 386
 387 /**
 388   \brief       Get usart send data count.
 389   \param[in]   handle  usart handle to operate.
 390   \return      number of data bytes transferred
 391 */
 392 uint32_t csi_usart_get_tx_count(usart_handle_t handle);
 393
 394 /**
 395   \brief       Get usart receive data count.
 396   \param[in]   handle  usart handle to operate.
 397   \return      number of data bytes transferred
 398 */
 399 uint32_t csi_usart_get_rx_count(usart_handle_t handle);
 400
 401 /**
 402   \brief       control usart power.
 403   \param[in]   handle  usart handle to operate.
 404   \param[in]   state   power state.\ref csi_power_stat_e.
 405   \return      error code
 406 */
 407 int32_t csi_usart_power_control(usart_handle_t handle, csi_power_stat_e state);
 408
 409 /**
 410   \brief       config usart flow control type.
 411   \param[in]   handle  usart handle to operate.
 412   \param[in]   flowctrl_type   flow control type.\ref usart_flowctrl_type_e.
 413   \param[in]   tx_flow  The TX flow pin name
 414   \param[in]   rx_flow  The RX flow pin name
 415   \return      error code
 416 */
 417 int32_t csi_usart_config_flowctrl(usart_handle_t handle,
 418                                   usart_flowctrl_type_e flowctrl_type,
 419                                   pin_t tx_flow, pin_t rx_flow);
 420 /**
 421   \brief       usart modem control.
 422   \param[in]   handle  usart handle to operate.
 423   \param[in]   modem_ctrl   modem control action.\ref usart_modem_ctrl_e.
 424   \return      error code
 425 */
 426 int32_t csi_usart_modem_ctrl(usart_handle_t handle, usart_modem_ctrl_e modem_ctrl);
 427
 428 /**
 429   \brief       get usart modem status.
 430   \param[in]   handle  usart handle to operate.
 431   \param[in]   modem_ctrl   modem control action.\ref usart_modem_ctrl_e.
 432   \return      modem status.\ref usart_modem_stat_t.
 433 */
 434 usart_modem_stat_t csi_usart_get_modem_stat(usart_handle_t handle);
 435
 436 /**
 437   \brief       config usart clock Polarity and Phase.
 438   \param[in]   handle  usart handle to operate.
 439   \param[in]   cpol    Clock Polarity.\ref usart_cpol_e.
 440   \param[in]   cpha    Clock Phase.\ref usart_cpha_e.
 441   \return      error code
 442 */
 443 int32_t csi_usart_config_clock(usart_handle_t handle, usart_cpol_e cpol, usart_cpha_e cpha);
 444
 445 /**
 446   \brief       config usart guard time.
 447   \param[in]   handle  usart handle to operate.
 448   \param[in]   num_of_bits   guard time in number of bit periods.
 449   \return      error code
 450 */
 451 int32_t csi_usart_config_guard_time(usart_handle_t handle, uint32_t num_of_bits);
 452
 453 /**
 454   \brief       check if usart is readable(data received).
 455   \param[in]   handle  usart handle to operate.
 456   \return      1 - a character can be read, 0 if nothing to read ,negative for error code
 457 */
 458 int32_t csi_usart_readable(usart_handle_t handle);
 459
 460 /**
 461   \brief       check if usart is writable(free for data sending).
 462   \param[in]   handle  usart handle to operate.
 463   \return      1 - a character can be written, 0 -  cannot be written ,negative for error code
 464 */
 465 int32_t csi_usart_writable(usart_handle_t handle);
 466
 467 /**
 468   \brief       control the transmit.
 469   \param[in]   handle  usart handle to operate.
 470   \param[in]   1 - enable the transmitter. 0 - disable the transmitter
 471   \return      error code
 472 */
 473 int32_t csi_usart_control_tx(usart_handle_t handle, uint32_t enable);
 474
 475 /**
 476   \brief       control the receive.
 477   \param[in]   handle  usart handle to operate.
 478   \param[in]   1 - enable the receiver. 0 - disable the receiver
 479   \return      error code
 480 */
 481 int32_t csi_usart_control_rx(usart_handle_t handle, uint32_t enable);
 482
 483 /**
 484   \brief       control the break.
 485   \param[in]   handle  usart handle to operate.
 486   \param[in]   1- Enable continuous Break transmission,0 - disable continuous Break transmission
 487   \return      error code
 488 */
 489 int32_t csi_usart_control_break(usart_handle_t handle, uint32_t enable);
 490
 491 #ifdef __cplusplus
 492 }
 493 #endif
 494
 495 #endif /* _CSI_USART_H_ */