drv_usart.h 18 KB

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