hal_uart.h 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444
  1. /*
  2. * ===========================================================================================
  3. *
  4. * Filename: hal_uart.h
  5. *
  6. * Description: UART HAL definition.
  7. *
  8. * Version: Melis3.0
  9. * Create: 2019-11-14 11:11:56
  10. * Revision: none
  11. * Compiler: GCC:version 9.2.1 20170904 (release),SUNXI_HAL/embedded-7-branch revision 255204
  12. *
  13. * Author: bantao@allwinnertech.com
  14. * Organization: SWC-BPD
  15. * Last Modified: 2020-04-02 19:39:41
  16. *
  17. * ===========================================================================================
  18. */
  19. #ifndef SUNXI_HAL_UART_H
  20. #define SUNXI_HAL_UART_H
  21. #ifdef __cplusplus
  22. extern "C"
  23. {
  24. #endif
  25. #include "sunxi_hal_common.h"
  26. /*
  27. * include the platform uart header file.
  28. */
  29. #include <platform-uart.h>
  30. /*
  31. * This enum defines return status of the UART HAL public API.
  32. * User should check return value after calling these APIs.
  33. */
  34. typedef enum
  35. {
  36. HAL_UART_STATUS_ERROR_PARAMETER = -4, /**< Invalid user input parameter. */
  37. HAL_UART_STATUS_ERROR_BUSY = -3, /**< UART port is currently in use. */
  38. HAL_UART_STATUS_ERROR_UNINITIALIZED = -2, /**< UART port has not been initialized. */
  39. HAL_UART_STATUS_ERROR = -1, /**< UART driver detected a common error. */
  40. HAL_UART_STATUS_OK = 0 /**< UART function executed successfully. */
  41. } hal_uart_status_t;
  42. typedef enum
  43. {
  44. UART_0 = 0,
  45. UART_1,
  46. UART_2,
  47. UART_3,
  48. UART_MAX,
  49. } uart_port_t;
  50. #define CLI_UART_PORT (UART_0)
  51. /* This enum defines baud rate of the UART frame. */
  52. typedef enum
  53. {
  54. UART_BAUDRATE_300 = 0,
  55. UART_BAUDRATE_600,
  56. UART_BAUDRATE_1200,
  57. UART_BAUDRATE_2400,
  58. UART_BAUDRATE_4800,
  59. UART_BAUDRATE_9600,
  60. UART_BAUDRATE_19200,
  61. UART_BAUDRATE_38400,
  62. UART_BAUDRATE_57600,
  63. UART_BAUDRATE_115200,
  64. UART_BAUDRATE_230400,
  65. UART_BAUDRATE_576000,
  66. UART_BAUDRATE_921600,
  67. UART_BAUDRATE_500000,
  68. UART_BAUDRATE_1000000,
  69. UART_BAUDRATE_1500000,
  70. UART_BAUDRATE_3000000,
  71. UART_BAUDRATE_4000000,
  72. UART_BAUDRATE_MAX,
  73. } uart_baudrate_t;
  74. /* This enum defines word length of the UART frame. */
  75. typedef enum
  76. {
  77. UART_WORD_LENGTH_5 = 0,
  78. UART_WORD_LENGTH_6,
  79. UART_WORD_LENGTH_7,
  80. UART_WORD_LENGTH_8,
  81. } uart_word_length_t;
  82. /* This enum defines stop bit of the UART frame. */
  83. typedef enum
  84. {
  85. UART_STOP_BIT_1 = 0,
  86. UART_STOP_BIT_2,
  87. } uart_stop_bit_t;
  88. /* This enum defines parity of the UART frame. */
  89. typedef enum
  90. {
  91. UART_PARITY_NONE = 0,
  92. UART_PARITY_ODD,
  93. UART_PARITY_EVEN
  94. } uart_parity_t;
  95. /* This struct defines UART configure parameters. */
  96. typedef struct
  97. {
  98. uart_baudrate_t baudrate;
  99. uart_word_length_t word_length;
  100. uart_stop_bit_t stop_bit;
  101. uart_parity_t parity;
  102. } _uart_config_t;
  103. /* UART HAL Layer API Version */
  104. #define SUNXI_HAL_UART_API_VERSION SUNXI_HAL_VERSION_MAJOR_MINOR(1, 0)
  105. /* Driver version */
  106. #define SUNXI_HAL_UART_DRV_VERSION SUNXI_HAL_VERSION_MAJOR_MINOR(1, 0)
  107. //======================================reg==========================================================//
  108. #define UART_INVAL_DATA_IND (0xffffffff)
  109. #undef BIT
  110. #define BIT(nr) (1UL << (nr))
  111. //=================================reg===================================================//
  112. /*
  113. * brief UART Status
  114. */
  115. typedef struct sunxi_hal_uart_status
  116. {
  117. uint32_t tx_busy : 1; ///< Transmitter busy flag
  118. uint32_t rx_busy : 1; ///< Receiver busy flag
  119. uint32_t tx_underflow : 1; ///< Transmit data underflow detected (cleared on start of next send operation)
  120. uint32_t rx_overflow : 1; ///< Receive data overflow detected (cleared on start of next receive operation)
  121. uint32_t rx_break : 1; ///< Break detected on receive (cleared on start of next receive operation)
  122. uint32_t rx_framing_error : 1; ///< Framing error detected on receive (cleared on start of next receive operation)
  123. uint32_t rx_parity_error : 1; ///< Parity error detected on receive (cleared on start of next receive operation)
  124. uint32_t reserved : 25;
  125. } sunxi_hal_uart_status_t;
  126. /*
  127. *brief UART Modem Control
  128. */
  129. typedef enum sunxi_hal_uart_modem_control
  130. {
  131. SUNXI_HAL_UART_RTS_CLEAR, ///< Deactivate RTS
  132. SUNXI_HAL_UART_RTS_SET, ///< Activate RTS
  133. SUNXI_HAL_UART_DTR_CLEAR, ///< Deactivate DTR
  134. SUNXI_HAL_UART_DTR_SET ///< Activate DTR
  135. } sunxi_hal_uart_modem_control_e;
  136. /*
  137. *brief UART Modem Status
  138. */
  139. typedef struct sunxi_hal_uart_modem_status
  140. {
  141. uint32_t cts : 1; ///< CTS state: 1=Active, 0=Inactive
  142. uint32_t dsr : 1; ///< DSR state: 1=Active, 0=Inactive
  143. uint32_t dcd : 1; ///< DCD state: 1=Active, 0=Inactive
  144. uint32_t ri : 1; ///< RI state: 1=Active, 0=Inactive
  145. uint32_t reserved : 28;
  146. } sunxi_hal_uart_modem_status_t;
  147. /****** UART Event *****/
  148. #define SUNXI_HAL_UART_EVENT_SEND_COMPLETE (1UL << 0) ///< Send completed; however UART may still transmit data
  149. #define SUNXI_HAL_UART_EVENT_RECEIVE_COMPLETE (1UL << 1) ///< Receive completed
  150. #define SUNXI_HAL_UART_EVENT_TRANSFER_COMPLETE (1UL << 2) ///< Transfer completed
  151. #define SUNXI_HAL_UART_EVENT_TX_COMPLETE (1UL << 3) ///< Transmit completed (optional)
  152. #define SUNXI_HAL_UART_EVENT_TX_UNDERFLOW (1UL << 4) ///< Transmit data not available (Synchronous Slave)
  153. #define SUNXI_HAL_UART_EVENT_RX_OVERFLOW (1UL << 5) ///< Receive data overflow
  154. #define SUNXI_HAL_UART_EVENT_RX_TIMEOUT (1UL << 6) ///< Receive character timeout (optional)
  155. #define SUNXI_HAL_UART_EVENT_RX_BREAK (1UL << 7) ///< Break detected on receive
  156. #define SUNXI_HAL_UART_EVENT_RX_FRAMING_ERROR (1UL << 8) ///< Framing error detected on receive
  157. #define SUNXI_HAL_UART_EVENT_RX_PARITY_ERROR (1UL << 9) ///< Parity error detected on receive
  158. #define SUNXI_HAL_UART_EVENT_CTS (1UL << 10) ///< CTS state changed (optional)
  159. #define SUNXI_HAL_UART_EVENT_DSR (1UL << 11) ///< DSR state changed (optional)
  160. #define SUNXI_HAL_UART_EVENT_DCD (1UL << 12) ///< DCD state changed (optional)
  161. #define SUNXI_HAL_UART_EVENT_RI (1UL << 13) ///< RI state changed (optional)
  162. /* This enum defines the UART event when an interrupt occurs. */
  163. typedef enum
  164. {
  165. UART_EVENT_TRANSACTION_ERROR = -1,
  166. UART_EVENT_RX_BUFFER_ERROR = -2,
  167. UART_EVENT_TX_COMPLETE = 1,
  168. UART_EVENT_RX_COMPLETE = 2,
  169. } uart_callback_event_t;
  170. /** @brief This typedef defines user's callback function prototype.
  171. * This callback function will be called in UART interrupt handler when UART interrupt is raised.
  172. * User should call uart_register_callback() to register callbacks to UART driver explicitly.
  173. * Note, that the callback function is not appropriate for time-consuming operations. \n
  174. * parameter "event" : for more information, please refer to description of #uart_callback_event_t.
  175. * parameter "user_data" : a user defined data used in the callback function.
  176. */
  177. typedef void (*uart_callback_t)(uart_callback_event_t event, void *user_data);
  178. typedef struct
  179. {
  180. uint8_t *buf;
  181. uint32_t len;
  182. uint32_t head;
  183. uint32_t tail;
  184. int32_t cnt;
  185. } uart_ring_buf_t;
  186. /* This struct defines UART private data */
  187. typedef struct
  188. {
  189. /* basic info */
  190. uart_port_t uart_port;
  191. uint32_t irqn;
  192. /* uart register value */
  193. unsigned char ier;
  194. unsigned char lcr;
  195. unsigned char mcr;
  196. unsigned char fcr;
  197. unsigned char dll;
  198. unsigned char dlh;
  199. /* tx & rx buf */
  200. const char *tx_buf;
  201. uint32_t tx_buf_size;
  202. /* rx ring buf */
  203. uart_ring_buf_t ring_buf;
  204. /* user callback */
  205. uart_callback_t func;
  206. void *arg;
  207. } uart_priv_t;
  208. /**
  209. \fn sunxi_hal_version_t SUNXI_HAL_UART_GetVersion (void)
  210. \brief Get driver version.
  211. \return \ref sunxi_hal_version_t
  212. \fn SUNXI_HAL_UART_CAPABILITIES SUNXI_HAL_UART_GetCapabilities (void)
  213. \brief Get driver capabilities
  214. \return \ref SUNXI_HAL_UART_CAPABILITIES
  215. \fn int32_t SUNXI_HAL_UART_Initialize (SUNXI_HAL_UART_SignalEvent_t cb_event)
  216. \brief Initialize UART Interface.
  217. \param[in] cb_event Pointer to \ref SUNXI_HAL_UART_SignalEvent
  218. \return \ref execution_status
  219. \fn int32_t SUNXI_HAL_UART_Uninitialize (void)
  220. \brief De-initialize UART Interface.
  221. \return \ref execution_status
  222. \fn int32_t SUNXI_HAL_UART_PowerControl (SUNXI_HAL_POWER_STATE state)
  223. \brief Control UART Interface Power.
  224. \param[in] state Power state
  225. \return \ref execution_status
  226. \fn int32_t SUNXI_HAL_UART_Send (const void *data, uint32_t num)
  227. \brief Start sending data to UART transmitter.
  228. \param[in] data Pointer to buffer with data to send to UART transmitter
  229. \param[in] num Number of data items to send
  230. \return \ref execution_status
  231. \fn int32_t SUNXI_HAL_UART_Receive (void *data, uint32_t num)
  232. \brief Start receiving data from UART receiver.
  233. \param[out] data Pointer to buffer for data to receive from UART receiver
  234. \param[in] num Number of data items to receive
  235. \return \ref execution_status
  236. \fn int32_t SUNXI_HAL_UART_Transfer (const void *data_out,
  237. void *data_in,
  238. uint32_t num)
  239. \brief Start sending/receiving data to/from UART transmitter/receiver.
  240. \param[in] data_out Pointer to buffer with data to send to UART transmitter
  241. \param[out] data_in Pointer to buffer for data to receive from UART receiver
  242. \param[in] num Number of data items to transfer
  243. \return \ref execution_status
  244. \fn uint32_t SUNXI_HAL_UART_GetTxCount (void)
  245. \brief Get transmitted data count.
  246. \return number of data items transmitted
  247. \fn uint32_t SUNXI_HAL_UART_GetRxCount (void)
  248. \brief Get received data count.
  249. \return number of data items received
  250. \fn int32_t SUNXI_HAL_UART_Control (uint32_t control, uint32_t arg)
  251. \brief Control UART Interface.
  252. \param[in] control Operation
  253. \param[in] arg Argument of operation (optional)
  254. \return common \ref execution_status and driver specific \ref uart_execution_status
  255. \fn SUNXI_HAL_UART_STATUS SUNXI_HAL_UART_GetStatus (void)
  256. \brief Get UART status.
  257. \return UART status \ref SUNXI_HAL_UART_STATUS
  258. \fn int32_t SUNXI_HAL_UART_SetModemControl (SUNXI_HAL_UART_MODEM_CONTROL control)
  259. \brief Set UART Modem Control line state.
  260. \param[in] control \ref SUNXI_HAL_UART_MODEM_CONTROL
  261. \return \ref execution_status
  262. \fn SUNXI_HAL_UART_MODEM_STATUS SUNXI_HAL_UART_GetModemStatus (void)
  263. \brief Get UART Modem Status lines state.
  264. \return modem status \ref SUNXI_HAL_UART_MODEM_STATUS
  265. \fn void SUNXI_HAL_UART_SignalEvent (uint32_t event)
  266. \brief Signal UART Events.
  267. \param[in] event \ref UART_events notification mask
  268. \return none
  269. */
  270. typedef void (*sunxi_hal_uart_signal_event_t)(uint32_t event); ///< Pointer to \ref SUNXI_HAL_UART_SignalEvent : Signal UART Event.
  271. /**
  272. \brief UART Device Driver Capabilities.
  273. */
  274. typedef struct sunxi_hal_uart_capabilities
  275. {
  276. uint32_t asynchronous : 1; ///< supports UART (Asynchronous) mode
  277. uint32_t synchronous_master : 1; ///< supports Synchronous Master mode
  278. uint32_t synchronous_slave : 1; ///< supports Synchronous Slave mode
  279. uint32_t single_wire : 1; ///< supports UART Single-wire mode
  280. uint32_t irda : 1; ///< supports UART IrDA mode
  281. uint32_t smart_card : 1; ///< supports UART Smart Card mode
  282. uint32_t smart_card_clock : 1; ///< Smart Card Clock generator available
  283. uint32_t flow_control_rts : 1; ///< RTS Flow Control available
  284. uint32_t flow_control_cts : 1; ///< CTS Flow Control available
  285. uint32_t event_tx_complete : 1; ///< Transmit completed event: \ref SUNXI_HAL_UART_EVENT_TX_COMPLETE
  286. uint32_t event_rx_timeout : 1; ///< Signal receive character timeout event: \ref SUNXI_HAL_UART_EVENT_RX_TIMEOUT
  287. uint32_t rts : 1; ///< RTS Line: 0=not available, 1=available
  288. uint32_t cts : 1; ///< CTS Line: 0=not available, 1=available
  289. uint32_t dtr : 1; ///< DTR Line: 0=not available, 1=available
  290. uint32_t dsr : 1; ///< DSR Line: 0=not available, 1=available
  291. uint32_t dcd : 1; ///< DCD Line: 0=not available, 1=available
  292. uint32_t ri : 1; ///< RI Line: 0=not available, 1=available
  293. uint32_t event_cts : 1; ///< Signal CTS change event: \ref SUNXI_HAL_UART_EVENT_CTS
  294. uint32_t event_dsr : 1; ///< Signal DSR change event: \ref SUNXI_HAL_UART_EVENT_DSR
  295. uint32_t event_dcd : 1; ///< Signal DCD change event: \ref SUNXI_HAL_UART_EVENT_DCD
  296. uint32_t event_ri : 1; ///< Signal RI change event: \ref SUNXI_HAL_UART_EVENT_RI
  297. uint32_t reserved : 11; ///< Reserved (must be zero)
  298. } sunxi_hal_uart_capabilities_t;
  299. typedef struct sunxi_hal_driver_usart
  300. {
  301. ///< Pointer to \ref SUNXI_HAL_USART_GetVersion : Get driver version.
  302. sunxi_hal_version_t (*get_version)(int32_t dev);
  303. ///< Pointer to \ref SUNXI_HAL_USART_GetCapabilities : Get driver capabilities.
  304. sunxi_hal_uart_capabilities_t (*get_capabilities)(int32_t dev);
  305. ///< Pointer to \ref SUNXI_HAL_USART_Initialize : Initialize USART Interface.
  306. int32_t (*initialize)(int32_t uart_port);
  307. ///< Pointer to \ref SUNXI_HAL_USART_Uninitialize : De-initialize USART Interface.
  308. int32_t (*uninitialize)(int32_t uart_port);
  309. ///< Pointer to \ref SUNXI_HAL_USART_PowerControl : Control USART Interface Power.
  310. int32_t (*power_control)(int32_t dev, sunxi_hal_power_state_e state);
  311. ///< Pointer to \ref SUNXI_HAL_USART_Send : Start sending data to USART transmitter.
  312. int32_t (*send)(int32_t dev, const uint8_t *data, uint32_t num);
  313. ///< Pointer to \ref SUNXI_HAL_USART_Receive : Start receiving data from USART receiver.
  314. int32_t (*receive)(int32_t dev, int *data, uint32_t num);
  315. ///< Pointer to \ref SUNXI_HAL_USART_Transfer : Start sending/receiving data to/from USART.
  316. int32_t (*transfer)(int32_t dev, const void *data_out, void *data_in, uint32_t num);
  317. ///< Pointer to \ref SUNXI_HAL_USART_GetTxCount : Get transmitted data count.
  318. uint32_t (*get_tx_count)(int32_t dev);
  319. ///< Pointer to \ref SUNXI_HAL_USART_GetRxCount : Get received data count.
  320. uint32_t (*get_rx_count)(int32_t dev);
  321. ///< Pointer to \ref SUNXI_HAL_USART_Control : Control USART Interface.
  322. int32_t (*control)(int32_t uart_port, int cmd, void *args);
  323. ///< Pointer to \ref SUNXI_HAL_USART_GetStatus : Get USART status.
  324. sunxi_hal_uart_status_t (*get_status)(int32_t dev);
  325. ///< Pointer to \ref SUNXI_HAL_USART_SetModemControl : Set USART Modem Control line state.
  326. int32_t (*set_modem_control)(int32_t dev, sunxi_hal_uart_modem_control_e control);
  327. ///< Pointer to \ref SUNXI_HAL_USART_GetModemStatus : Get USART Modem Status lines state.
  328. sunxi_hal_uart_modem_status_t (*get_modem_status)(int32_t dev);
  329. int32_t (*receive_polling)(int32_t dev, uint8_t *data, uint32_t num);
  330. sunxi_hal_poll_ops *poll_ops;
  331. } const sunxi_hal_driver_usart_t;
  332. #if 0
  333. #define POLLIN (0x01)
  334. #define POLLRDNORM (0x01)
  335. #define POLLRDBAND (0x01)
  336. #define POLLPRI (0x01)
  337. #define POLLOUT (0x02)
  338. #define POLLWRNORM (0x02)
  339. #define POLLWRBAND (0x02)
  340. #define POLLERR (0x04)
  341. #define POLLHUP (0x08)
  342. #define POLLNVAL (0x10)
  343. #endif
  344. sunxi_hal_version_t hal_uart_get_version(int32_t dev);
  345. sunxi_hal_uart_capabilities_t hal_uart_get_capabilities(int32_t dev);
  346. int32_t hal_uart_init(int32_t uart_port);
  347. int32_t hal_uart_deinit(int32_t uart_port);
  348. int32_t hal_uart_power_control(int32_t dev, sunxi_hal_power_state_e state);
  349. int32_t hal_uart_send(int32_t dev, const uint8_t *data, uint32_t num);
  350. int32_t hal_uart_put_char(int32_t dev, char c);
  351. int32_t hal_uart_receive(int32_t dev, uint8_t *data, uint32_t num);
  352. int32_t hal_uart_receive_no_block(int32_t dev, uint8_t *data, uint32_t num, int32_t timeout);
  353. uint8_t hal_uart_get_char(int32_t dev);
  354. uint32_t hal_uart_get_tx_count(int32_t dev);
  355. uint32_t hal_uart_get_rx_count(int32_t dev);
  356. int32_t hal_uart_control(int32_t uart_port, int cmd, void *args);
  357. sunxi_hal_uart_status_t hal_uart_get_status(int32_t dev);
  358. int32_t hal_uart_transfer(int32_t dev, const void *data_out,
  359. void *data_in, uint32_t num);
  360. int32_t hal_uart_set_modem_control(int32_t dev,
  361. sunxi_hal_uart_modem_control_e control);
  362. sunxi_hal_uart_modem_status_t hal_uart_get_modem_status(int32_t dev);
  363. int32_t hal_uart_receive_polling(int32_t dev, uint8_t *data, uint32_t num);
  364. int32_t hal_uart_check_poll_state(int32_t dev_id, short key);
  365. int32_t hal_uart_poll_wakeup(int32_t dev_id, short key);
  366. int32_t hal_uart_register_poll_wakeup(poll_wakeup_func poll_wakeup);
  367. void hal_uart_set_hardware_flowcontrol(uart_port_t uart_port);
  368. void hal_uart_disable_flowcontrol(uart_port_t uart_port);
  369. void hal_uart_set_loopback(uart_port_t uart_port, bool enable);
  370. void sunxi_driver_uart_init(void);
  371. #ifdef __cplusplus
  372. }
  373. #endif
  374. #endif