dev_uart.h 20 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475
  1. /* ------------------------------------------
  2. * Copyright (c) 2016, Synopsys, Inc. All rights reserved.
  3. * Redistribution and use in source and binary forms, with or without modification,
  4. * are permitted provided that the following conditions are met:
  5. * 1) Redistributions of source code must retain the above copyright notice, this
  6. * list of conditions and the following disclaimer.
  7. * 2) Redistributions in binary form must reproduce the above copyright notice,
  8. * this list of conditions and the following disclaimer in the documentation and/or
  9. * other materials provided with the distribution.
  10. * 3) Neither the name of the Synopsys, Inc., nor the names of its contributors may
  11. * be used to endorse or promote products derived from this software without
  12. * specific prior written permission.
  13. * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
  14. * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  15. * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  16. * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
  17. * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  18. * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  19. * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
  20. * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  21. * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  22. * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  23. *
  24. * \version 2016.05
  25. * \date 2014-06-16
  26. * \author Huaqi Fang(Huaqi.Fang@synopsys.com)
  27. --------------------------------------------- */
  28. /**
  29. * \defgroup DEVICE_HAL_UART UART Device HAL Interface
  30. * \ingroup DEVICE_HAL_DEF
  31. * \brief Definitions for uart device hardware layer (\ref dev_uart.h)
  32. * \details Provide unified APIs for uart driver to implement.
  33. * Here is a diagram for the uart interface.
  34. *
  35. * \htmlonly
  36. * <div class="imagebox">
  37. * <div style="width: 600px">
  38. * <img src="pic/dev_uart_hal.jpg" alt="UART Device HAL Interface Diagram"/>
  39. * <p>UART Device HAL Interface Diagram</p>
  40. * </div>
  41. * </div>
  42. * \endhtmlonly
  43. *
  44. * ### Reference Links
  45. * * [Serial Port](https://en.wikipedia.org/wiki/Serial_port)
  46. *
  47. * @{6
  48. *
  49. * \file
  50. * \brief uart device hardware layer definitions
  51. * \details Provide common definitions for uart device,
  52. * then software developer can develop uart driver
  53. * following this definitions, and the applications
  54. * can directly call this definition to realize functions
  55. *
  56. */
  57. #ifndef _DEVICE_HAL_UART_H_
  58. #define _DEVICE_HAL_UART_H_
  59. #include "device/device_hal/inc/dev_common.h"
  60. /**
  61. * \defgroup DEVICE_HAL_UART_BAUD UART Device Baudrate Definitions
  62. * \ingroup DEVICE_HAL_UART
  63. * \brief Macros for uart baudrate.
  64. * \details Definitions for baudrate from 4800 to 115200bps.
  65. * @{
  66. */
  67. /*
  68. * defines for uart baudrates
  69. */
  70. #define UART_BAUDRATE_110 (110) /*!< uart baudrate 110bps */
  71. #define UART_BAUDRATE_300 (300) /*!< uart baudrate 300bps */
  72. #define UART_BAUDRATE_600 (600) /*!< uart baudrate 600bps */
  73. #define UART_BAUDRATE_1200 (1200) /*!< uart baudrate 1200bps */
  74. #define UART_BAUDRATE_2400 (2400) /*!< uart baudrate 2400bps */
  75. #define UART_BAUDRATE_4800 (4800) /*!< uart baudrate 4800bps */
  76. #define UART_BAUDRATE_9600 (9600) /*!< uart baudrate 9600bps */
  77. #define UART_BAUDRATE_14400 (14400) /*!< uart baudrate 14400bps */
  78. #define UART_BAUDRATE_19200 (19200) /*!< uart baudrate 19200bps */
  79. #define UART_BAUDRATE_38400 (38400) /*!< uart baudrate 38400bps */
  80. #define UART_BAUDRATE_57600 (57600) /*!< uart baudrate 57600bps */
  81. #define UART_BAUDRATE_115200 (115200) /*!< uart baudrate 115200bps */
  82. #define UART_BAUDRATE_230400 (230400) /*!< uart baudrate 230400bps */
  83. #define UART_BAUDRATE_460800 (460800) /*!< uart baudrate 460800bps */
  84. #define UART_BAUDRATE_921600 (921600) /*!< uart baudrate 921600bps */
  85. /** @} */
  86. /**
  87. * \defgroup DEVICE_HAL_UART_FORMAT UART Device Format Definitions
  88. * \ingroup DEVICE_HAL_UART
  89. * \brief Macros for uart format.
  90. * \details Definitions for uart format like databits, parity, stopbits.
  91. * @{
  92. */
  93. /**
  94. * UART Device Parity Types Enum
  95. */
  96. typedef enum {
  97. UART_PARITY_NONE = 0, /*!< no parity bit */
  98. UART_PARITY_ODD = 1, /*!< odd parity bit */
  99. UART_PARITY_EVEN = 2, /*!< even parity bit */
  100. UART_PARITY_MARK = 3, /*!< mark parity bit, always logical 1 */
  101. UART_PARITY_SPACE = 4 /*!< space parity bit, always logical 0 */
  102. } UART_PARITY;
  103. /**
  104. * UART Device Stop Bits Enum
  105. */
  106. typedef enum {
  107. UART_STPBITS_ONE = 0, /*!< 1 stop bit */
  108. UART_STPBITS_ONEHALF = 1, /*!< 1.5 stop bits */
  109. UART_STPBITS_TWO = 2 /*!< 2 stop bits */
  110. } UART_STOPBITS;
  111. /**
  112. * UART DPS Format: databits/parity/stopbits
  113. */
  114. typedef struct uart_dps_format {
  115. uint32_t databits; /*!< data bits */
  116. UART_PARITY parity; /*!< parity bit type */
  117. UART_STOPBITS stopbits; /*!< stop bits */
  118. } UART_DPS_FORMAT;
  119. #define UART_DATABITS_DEFAULT 8 /*!< default data bits */
  120. /** Default UART DPS format */
  121. static const UART_DPS_FORMAT dps_format_default = {UART_DATABITS_DEFAULT, UART_PARITY_NONE, UART_STPBITS_ONE};
  122. /** @} */
  123. /**
  124. * UART Device Hardware Flow Control Types Enum
  125. */
  126. typedef enum {
  127. UART_FC_NONE = 0, /*!< Non hardware flow control */
  128. UART_FC_RTS = 1, /*!< Request To Send */
  129. UART_FC_CTS = 2, /*!< Clear To Send */
  130. UART_FC_BOTH = 3 /*!< Both hardware flow control methods */
  131. } UART_HW_FLOW_CONTROL;
  132. /** Default hardware flow control method */
  133. static const UART_HW_FLOW_CONTROL hwfc_default = UART_FC_NONE;
  134. /**
  135. * \defgroup DEVICE_HAL_UART_CTRLCMD UART Device Control Commands
  136. * \ingroup DEVICE_HAL_UART
  137. * \brief Definitions for uart control command, used in \ref dev_uart::uart_control "UART IO Control"
  138. * \details These commands defined here can be used in user code directly.
  139. * - Parameters Usage
  140. * - For passing parameters like integer, just use uint32_t/int32_t to directly pass values
  141. * - For passing parameters for a structure, please use pointer to pass values
  142. * - For getting some data, please use pointer to store the return data
  143. * - Common Return Values
  144. * - \ref E_OK, Control device successfully
  145. * - \ref E_CLSED, Device is not opened
  146. * - \ref E_OBJ, Device object is not valid or not exists
  147. * - \ref E_PAR, Parameter is not valid for current control command
  148. * - \ref E_SYS, Control device failed, due to hardware issues such as device is disabled
  149. * - \ref E_CTX, Control device failed, due to different reasons like in transfer state
  150. * - \ref E_NOSPT, Control command is not supported or not valid
  151. * @{
  152. */
  153. /**
  154. * Set \ref dev_uart_info::baudrate "uart baudrate".
  155. * - Param type : uint32_t
  156. * - Param usage : uart baudrate, must above zero. Here is a list of \ref DEVICE_HAL_UART_BAUD "possible baudrates"
  157. * - Return value explanation :
  158. */
  159. #define UART_CMD_SET_BAUD DEV_SET_SYSCMD(0)
  160. /**
  161. * Get \ref dev_uart_info::status "current device status"
  162. * - Param type : uint32_t *
  163. * - Param usage : store result of current status
  164. * - Return value explanation :
  165. */
  166. #define UART_CMD_GET_STATUS DEV_SET_SYSCMD(1)
  167. /**
  168. * Enable uart device
  169. * - Param type : NULL
  170. * - Param usage : param is not required
  171. * - Return value explanation :
  172. */
  173. #define UART_CMD_ENA_DEV DEV_SET_SYSCMD(2)
  174. /**
  175. * Disable uart device, when device is disabled,
  176. * only \ref UART_CMD_ENA_DEV, \ref UART_CMD_DIS_DEV and
  177. * \ref UART_CMD_GET_STATUS commands can be executed,
  178. * other commands will return \ref E_SYS
  179. * - Param type : NULL
  180. * - Param usage : param is not required
  181. * - Return value explanation :
  182. */
  183. #define UART_CMD_DIS_DEV DEV_SET_SYSCMD(3)
  184. /**
  185. * Flush uart device output
  186. * - Param type : NULL
  187. * - Param usage : param is not required
  188. * - Return value explanation :
  189. */
  190. #define UART_CMD_FLUSH_OUTPUT DEV_SET_SYSCMD(4)
  191. /**
  192. * Get how many bytes space in uart are available to transmit,
  193. * this can be used in interrupt callback functions,
  194. * cooperate with \ref dev_uart::uart_write "uart_write" API to realize non-blocked write
  195. * - Param type : int32_t *
  196. * - Param usage : store the write available bytes, > 0 for available bytes, 0 for not available
  197. * - Return value explanation :
  198. */
  199. #define UART_CMD_GET_TXAVAIL DEV_SET_SYSCMD(5)
  200. /**
  201. * Get how many bytes in uart are available to receive,
  202. * this can be used in interrupt callback functions,
  203. * cooperate with \ref dev_uart::uart_read "uart_read" API to realize non-blocked read
  204. * - Param type : int32_t *
  205. * - Param usage : store the read available bytes, > 0 for available bytes, 0 for not available
  206. * - Return value explanation :
  207. */
  208. #define UART_CMD_GET_RXAVAIL DEV_SET_SYSCMD(6)
  209. /**
  210. * Cause a break condition to be transmitted to the receiving device
  211. * - Param type : NULL
  212. * - Param usage : param is not required
  213. * - Return value explanation :
  214. */
  215. #define UART_CMD_BREAK_SET DEV_SET_SYSCMD(7)
  216. /**
  217. * Clear break condition and return to normal
  218. * - Param type : NULL
  219. * - Param usage : param is not required
  220. * - Return value explanation :
  221. */
  222. #define UART_CMD_BREAK_CLR DEV_SET_SYSCMD(8)
  223. /**
  224. * Change uart \ref dev_uart_info::dps_format "D/P/S(Data/Parity/Stop) format"
  225. * - Param type : \ref UART_DPS_FORMAT *
  226. * - Param usage : uart dps format including databits, parity and stopbits
  227. * - Return value explanation :
  228. */
  229. #define UART_CMD_SET_DPS_FORMAT DEV_SET_SYSCMD(9)
  230. /**
  231. * Set uart device \ref dev_uart_info::hwfc "hardware flow control"
  232. * - Param type : \ref UART_HW_FLOW_CONTROL
  233. * - Param usage : uart dps format including databits, parity and stopbits
  234. * - Return value explanation :
  235. */
  236. #define UART_CMD_SET_HWFC DEV_SET_SYSCMD(10)
  237. /**
  238. * Set \ref dev_uart_cbs::tx_cb "uart transmit success callback" function
  239. * when all required bytes are transmitted for interrupt method
  240. * - Param type : \ref DEV_CALLBACK * or NULL
  241. * - Param usage : transmit success callback function for uart
  242. * - Return value explanation :
  243. */
  244. #define UART_CMD_SET_TXCB DEV_SET_SYSCMD(11)
  245. /**
  246. * Set \ref dev_uart_cbs::rx_cb "uart receive success callback" function
  247. * when all required bytes are received for interrupt method
  248. * - Param type : \ref DEV_CALLBACK * or NULL
  249. * - Param usage : receive success callback function for uart
  250. * - Return value explanation :
  251. */
  252. #define UART_CMD_SET_RXCB DEV_SET_SYSCMD(12)
  253. /**
  254. * Set \ref dev_uart_cbs::err_cb "uart transfer error callback" function
  255. * when something error happened for interrupt method
  256. * - Param type : \ref DEV_CALLBACK * or NULL
  257. * - Param usage : transfer error callback function for uart
  258. * - Return value explanation :
  259. */
  260. #define UART_CMD_SET_ERRCB DEV_SET_SYSCMD(13)
  261. /**
  262. * Set transmit buffer via interrupt, and it will set \ref dev_uart_info::tx_buf "tx_buf"
  263. * - Param type : DEV_BUFFER * or NULL
  264. * - Param usage : buffer structure pointer, if param is NULL, then it will set tx_buf to NULL
  265. * - Return value explanation :
  266. */
  267. #define UART_CMD_SET_TXINT_BUF DEV_SET_SYSCMD(14)
  268. /**
  269. * Set receive buffer via interrupt, and it will set \ref dev_uart_info::rx_buf "rx_buf"
  270. * - Param type : DEV_BUFFER * or NULL
  271. * - Param usage : buffer structure pointer, if param is NULL, then it will set rx_buf to NULL
  272. * - Return value explanation :
  273. */
  274. #define UART_CMD_SET_RXINT_BUF DEV_SET_SYSCMD(15)
  275. /**
  276. * Enable or disable transmit interrupt
  277. * - Param type : uint32_t
  278. * - Param usage : enable(none-zero) or disable(zero) flag
  279. * - Return value explanation :
  280. */
  281. #define UART_CMD_SET_TXINT DEV_SET_SYSCMD(16)
  282. /**
  283. * Enable or disable receive interrupt
  284. * - Param type : uint32_t
  285. * - Param usage : enable(none-zero) or disable(zero) flag
  286. * - Return value explanation :
  287. */
  288. #define UART_CMD_SET_RXINT DEV_SET_SYSCMD(17)
  289. /**
  290. * Abort current interrupt transmit operation if tx interrupt enabled,
  291. * it will disable transmit interrupt, and set \ref DEV_IN_TX_ABRT
  292. * in \ref dev_uart_info::status "status" variable,
  293. * and call the transmit callback function, when tx callback is finished,
  294. * it will clear \ref DEV_IN_TX_ABRT and return
  295. * - Param type : NULL
  296. * - Param usage :
  297. * - Return value explanation :
  298. */
  299. #define UART_CMD_ABORT_TX DEV_SET_SYSCMD(18)
  300. /**
  301. * Abort current interrupt receive operation if rx interrupt enabled,
  302. * it will disable receive interrupt, and set \ref DEV_IN_TX_ABRT
  303. * in \ref dev_uart_info::status "status" variable,
  304. * and call the receive callback function, when rx callback is finished,
  305. * it will clear \ref DEV_IN_TX_ABRT and return
  306. * - Param type : NULL
  307. * - Param usage :
  308. * - Return value explanation :
  309. */
  310. #define UART_CMD_ABORT_RX DEV_SET_SYSCMD(19)
  311. /** @} */
  312. /**
  313. * \defgroup DEVICE_HAL_UART_CALLBACK UART Interrupt callback functions
  314. * \ingroup DEVICE_HAL_UART
  315. * \brief callback function structure for UART device
  316. * @{
  317. */
  318. typedef struct dev_uart_cbs {
  319. DEV_CALLBACK tx_cb; /*!< uart data transmit success required bytes callback */
  320. DEV_CALLBACK rx_cb; /*!< uart data receive success required bytes callback */
  321. DEV_CALLBACK err_cb; /*!< uart error callback */
  322. } DEV_UART_CBS, *DEV_UART_CBS_PTR;
  323. /** @} */
  324. /**
  325. * \defgroup DEVICE_HAL_UART_DEVSTRUCT UART Device Interface Definition
  326. * \ingroup DEVICE_HAL_UART
  327. * \brief Contains definitions of uart device interface structure.
  328. * \details This structure will be used in user implemented code, which was called
  329. * \ref DEVICE_IMPL "Device Driver Implement Layer" for uart to use in implementation code.
  330. * Application developer should use the UART API provided here to access to UART devices.
  331. * BSP developer should follow the API definition to implement UART device drivers.
  332. * @{
  333. */
  334. /**
  335. * \brief UART information struct definition
  336. * \details informations about uart open count, working status,
  337. * baudrate, uart registers and ctrl structure, uart dps format
  338. */
  339. typedef struct dev_uart_info {
  340. void *uart_ctrl; /*!< uart control related pointer, implemented by bsp developer, and this should be set during uart object implementation */
  341. uint32_t opn_cnt; /*!< uart open count, open it will increase 1, close it will decrease 1, 0 for close, >0 for open */
  342. uint32_t status; /*!< current working status, refer to \ref DEVICE_HAL_COMMON_DEVSTATUS, this should be \ref DEV_ENABLED for first open */
  343. uint32_t baudrate; /*!< uart baud rate, this should be the value of baud passing by uart_open if first successfully opened */
  344. UART_DPS_FORMAT dps_format; /*!< D/P/S format settings for uart device, here is \ref dps_format_default "default settings for first open" */
  345. UART_HW_FLOW_CONTROL hwfc; /*!< UART hardware flow control, here is \ref hwfc_default "default hardware flow control settings for first open" */
  346. DEV_BUFFER tx_buf; /*!< transmit buffer via interrupt, this should be all zero for first open */
  347. DEV_BUFFER rx_buf; /*!< receive buffer via interrupt, this should be all zero for first open */
  348. DEV_UART_CBS uart_cbs; /*!< uart callbacks, callback arguments should be \ref DEV_UART * or NULL, this should be all NULL for first open */
  349. void *extra; /*!< a extra pointer to get hook to applications which should not used by bsp developer,
  350. this should be NULL for first open and you can \ref DEV_UART_INFO_SET_EXTRA_OBJECT "set"
  351. or \ref DEV_UART_INFO_GET_EXTRA_OBJECT "get" the extra information pointer */
  352. } DEV_UART_INFO, * DEV_UART_INFO_PTR;
  353. /** Set extra information pointer of uart info */
  354. #define DEV_UART_INFO_SET_EXTRA_OBJECT(uart_info_ptr, extra_info) (uart_info_ptr)->extra = (void *)(extra_info)
  355. /** Get extra information pointer of uart info */
  356. #define DEV_UART_INFO_GET_EXTRA_OBJECT(uart_info_ptr) ((uart_info_ptr)->extra)
  357. /**
  358. * \brief UART device interface definition
  359. * \details Define uart device interface, like uart information structure,
  360. * provide functions to open/close/control uart, send/receive data by uart
  361. * \note All this details are implemented by user in user porting code
  362. */
  363. typedef struct dev_uart {
  364. DEV_UART_INFO uart_info; /*!< UART device information */
  365. int32_t (*uart_open) (uint32_t baud); /*!< Open uart device */
  366. int32_t (*uart_close) (void); /*!< Close uart device */
  367. int32_t (*uart_control) (uint32_t ctrl_cmd, void *param); /*!< Control uart device */
  368. int32_t (*uart_write) (const void *data, uint32_t len); /*!< Send data by uart device(blocked) */
  369. int32_t (*uart_read) (void *data, uint32_t len); /*!< Read data from uart device(blocked) */
  370. } DEV_UART, * DEV_UART_PTR;
  371. /**
  372. * \fn int32_t (* dev_uart::uart_open) (uint32_t baud)
  373. * \details open an uart device with defined baudrate
  374. * \param[in] baud \ref DEVICE_HAL_UART_BAUD "initial baudrate of uart", must > 0
  375. * \retval E_OK Open successfully without any issues
  376. * \retval E_OPNED If device was opened before with different parameters,
  377. * then just increase the \ref dev_uart_info::opn_cnt "opn_cnt" and return \ref E_OPNED
  378. * \retval E_OBJ Device object is not valid
  379. * \retval E_PAR Parameter is not valid
  380. * \retval E_NOSPT Open settings are not supported
  381. */
  382. /**
  383. * \fn int32_t (* dev_uart::uart_close) (void)
  384. * \details close an uart device, just decrease the \ref dev_uart_info::opn_cnt "opn_cnt",
  385. * if \ref dev_uart_info::opn_cnt "opn_cnt" equals 0, then close the device
  386. * \retval E_OK Close successfully without any issues(including scenario that device is already closed)
  387. * \retval E_OPNED Device is still opened, the device \ref dev_uart_info::opn_cnt "opn_cnt" decreased by 1
  388. * \retval E_OBJ Device object is not valid
  389. */
  390. /**
  391. * \fn int32_t (* dev_uart::uart_control) (uint32_t ctrl_cmd, void *param)
  392. * \details control an uart device by \ref ctrl_cmd, with passed \ref param.
  393. * you can control uart device using predefined uart control commands defined using \ref DEV_SET_SYSCMD
  394. * (which must be implemented by bsp developer), such as \ref UART_CMD_SET_BAUD "change baudrate",
  395. * \ref UART_CMD_FLUSH_OUTPUT "flush output" and \ref DEVICE_HAL_UART_CTRLCMD "more".
  396. * And you can also control uart device using your own specified commands defined using \ref DEV_SET_USRCMD,
  397. * but these specified commands should be defined in your own uart device driver implementation.
  398. * \param[in] ctrl_cmd \ref DEVICE_HAL_UART_CTRLCMD "control command", to change or get some thing related to uart
  399. * \param[in,out] param parameters that maybe argument of the command, or return values of the command
  400. * \retval E_OK Control device successfully
  401. * \retval E_CLSED Device is not opened
  402. * \retval E_OBJ Device object is not valid or not exists
  403. * \retval E_PAR Parameter is not valid for current control command
  404. * \retval E_SYS Control device failed, due to hardware issues, such as device is disabled
  405. * \retval E_CTX Control device failed, due to different reasons like in transfer state
  406. * \retval E_NOSPT Control command is not supported or not valid
  407. */
  408. /**
  409. * \fn int32_t (* dev_uart::uart_write) (const void *data, uint32_t len)
  410. * \details send \ref data through uart with defined \ref len(blocked).
  411. * \param[in] data pointer to data need to send by uart, must not be NULL
  412. * \param[in] len length of data to be sent, must > 0
  413. * \retval >0 Byte count that was successfully sent for poll method
  414. * \retval E_OBJ Device object is not valid or not exists
  415. * \retval E_PAR Parameter is not valid
  416. * \retval E_SYS Can't write data to hardware due to hardware issues, such as device is disabled
  417. */
  418. /**
  419. * \fn int32_t (* dev_uart::uart_read) (void *data, uint32_t len)
  420. * \details receive \ref data of defined \ref len through uart(blocked).
  421. * \param[out] data pointer to data need to received by uart, must not be NULL
  422. * \param[in] len length of data to be received, must > 0
  423. * \retval >0 Byte count that was successfully received for poll method
  424. * \retval E_OBJ Device object is not valid or not exists
  425. * \retval E_PAR Parameter is not valid
  426. * \retval E_SYS Can't receive data from hardware due to hardware issues, such as device is disabled
  427. */
  428. /** @} */
  429. #ifdef __cplusplus
  430. extern "C" {
  431. #endif
  432. /**
  433. * \brief get an \ref dev_uart "uart device" by uart device id.
  434. * For how to use uart device hal refer to \ref DEVICE_HAL_UART_DEVSTRUCT "Functions in uart device structure"
  435. * \param[in] uart_id id of uart, defined by user
  436. * \retval !NULL pointer to an \ref dev_uart "uart device structure"
  437. * \retval NULL failed to find the uart device by \ref uart_id
  438. * \note need to implemented by user in user code
  439. */
  440. extern DEV_UART_PTR uart_get_dev(int32_t uart_id);
  441. #ifdef __cplusplus
  442. }
  443. #endif
  444. /** @} */
  445. #endif /* _DEVICE_HAL_UART_H_ */