hal_uart.h 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284
  1. /**
  2. * Copyright (c) 2016 - 2020 Nordic Semiconductor ASA and Luxoft Global Operations Gmbh.
  3. *
  4. * All Rights Reserved.
  5. *
  6. * Redistribution and use in source and binary forms, with or without modification,
  7. * are permitted provided that the following conditions are met:
  8. *
  9. *
  10. * 1. Redistributions of source code must retain the above copyright notice, this
  11. * list of conditions and the following disclaimer.
  12. *
  13. * 2. Redistributions in binary form, except as embedded into a Nordic
  14. * Semiconductor ASA integrated circuit in a product or a software update for
  15. * such product, must reproduce the above copyright notice, this list of
  16. * conditions and the following disclaimer in the documentation and/or other
  17. * materials provided with the distribution.
  18. *
  19. * 3. Neither the name of Nordic Semiconductor ASA nor the names of its
  20. * contributors may be used to endorse or promote products derived from this
  21. * software without specific prior written permission.
  22. *
  23. * 4. This software, with or without modification, must only be used with a
  24. * Nordic Semiconductor ASA integrated circuit.
  25. *
  26. * 5. Any software provided in binary form under this license must not be reverse
  27. * engineered, decompiled, modified and/or disassembled.
  28. *
  29. *
  30. * THIS SOFTWARE IS PROVIDED BY NORDIC SEMICONDUCTOR ASA "AS IS" AND ANY EXPRESS
  31. * OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  32. * OF MERCHANTABILITY, NONINFRINGEMENT, AND FITNESS FOR A PARTICULAR PURPOSE ARE
  33. * DISCLAIMED. IN NO EVENT SHALL NORDIC SEMICONDUCTOR ASA OR CONTRIBUTORS BE
  34. * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  35. * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
  36. * GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  37. * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  38. * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  39. * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  40. *
  41. */
  42. #ifndef HAL_UART_H_INCLUDED
  43. #define HAL_UART_H_INCLUDED
  44. #include <stdint.h>
  45. #include <stdlib.h>
  46. #include <limits.h>
  47. /** @file
  48. * This file contains declarations of the routines, types and macros to implement the UART protocol.
  49. *
  50. * @defgroup hal_uart HAL UART protocol
  51. * @ingroup hal_15_4
  52. * @{
  53. * @brief Module to declare HAL UART protocol
  54. * @details The UART module implements the standard UART driver API. This includes open/close via hal_uart_open(),
  55. * hal_uart_close(), read/write via hal_uart_read(), hal_uart_write() routines, and hal_uart_puts() for
  56. * sending a null-terminated string in a non-blocking way. The user also can get some info about the available
  57. * bytes for read/write via hal_uart_read_buffer_size_get() and hal_uart_write_buffer_size_get(). This implies
  58. * that the user may register read/write buffers to use for buffered input/output and handler routines that
  59. * will be called upon read/written characters. Also the most popular settings of the UART driver are supported:
  60. * different baudrates, parity checks, flow control, character size, and stop bits.
  61. */
  62. /** @brief Maximum size in bytes of input and output buffers. */
  63. #define MAX_QUEUE_LENGTH 0xffffu
  64. /** @brief Maximum size in bytes of data can be stored in hardware unit output buffer. */
  65. #define MAX_TX_CHUNK_SIZE UCHAR_MAX
  66. /** @brief UART baudrate. */
  67. typedef enum
  68. {
  69. HAL_UART_BAUDRATE_38400, /**< 38400 bits per second.*/
  70. HAL_UART_BAUDRATE_115200, /**< 115200 bits per second.*/
  71. HAL_UART_BAUDRATE_230400 /**< 230400 bits per second.*/
  72. } hal_uart_baudrate_t;
  73. /** @brief UART parity check. */
  74. typedef enum
  75. {
  76. HAL_UART_PARITY_NONE, /**< Do not check parity.*/
  77. HAL_UART_PARITY_EVEN /**< Check even parity.*/
  78. } hal_uart_parity_t;
  79. /** @brief UART flow control. */
  80. typedef enum
  81. {
  82. HAL_UART_FLOW_CONTROL_DISABLED, /**< Flow control is disabled.*/
  83. HAL_UART_FLOW_CONTROL_ENABLED, /**< Flow control is enabled.*/
  84. } hal_uart_flow_control_t;
  85. /** @brief UART character size settings. */
  86. typedef enum
  87. {
  88. HAL_UART_FIVE_BITS_CHAR = 5, /**< 5 bits character.*/
  89. HAL_UART_SIX_BITS_CHAR, /**< 6 bits character.*/
  90. HAL_UART_SEVEN_BITS_CHAR, /**< 7 bits character.*/
  91. HAL_UART_EIGHT_BITS_CHAR, /**< 8 bits character.*/
  92. } hal_uart_char_size_t;
  93. /** @brief UART stop bits settings. */
  94. typedef enum
  95. {
  96. HAL_UART_ONE_STOP_BIT, /**< 1 stop bit.*/
  97. HAL_UART_ONEHALF_STOP_BITS, /**< 1.5 stop bits.*/
  98. HAL_UART_TWO_STOP_BITS, /**< 2 stop bits.*/
  99. } hal_uart_stop_bits_t;
  100. /** @brief Represents error source for the UART driver. There might be other values,
  101. * representing clearer elaborating of error statuses, if this module is used
  102. * with Windows or Linux.
  103. */
  104. typedef enum
  105. {
  106. HAL_UART_ERROR_NONE = 0, /**< Success.*/
  107. HAL_UART_ERROR_TX_OVERFLOW = 252, /**< This error happens when amount of elements in
  108. the transmitter ring buffer exceeds its size.
  109. All the data above limit is not placed into
  110. buffer.*/
  111. HAL_UART_ERROR_RX_OVERFLOW = 253, /**< This error happens when amount of elements in
  112. the receiver ring buffer exceeds its size.
  113. All the unread data is overwritten with new
  114. received data.*/
  115. HAL_UART_ERROR_RX_UNDERFLOW = 254, /**< This error happens when the user-side software
  116. tries to read more elements than it is available
  117. in the receive buffer.
  118. The user-side buffer will be filled with all available
  119. characters and then the error handler is started.*/
  120. HAL_UART_ERROR_HW_ERROR = 255, /**< There is some unrecoverable error in hardware.*/
  121. } hal_uart_error_t;
  122. /**
  123. * @brief User-side handler of UART read and write events.
  124. *
  125. * @param[in] channel event channel number.
  126. * @param[in] char_count number of characters successfully sent before entering
  127. * the callback function.
  128. */
  129. typedef void (*hal_uart_handler_t)(uint32_t channel, size_t char_count);
  130. /**
  131. * @brief User-side handler for UART error events.
  132. *
  133. * @param[in] channel event channel number.
  134. * @param[in] error_id call reason.
  135. */
  136. typedef void (*hal_uart_error_handler_t)(uint32_t channel, hal_uart_error_t error_id);
  137. /** @brief HAL UART configuration structure.
  138. */
  139. typedef struct
  140. {
  141. uint32_t module; /**< UART module number. By now zero
  142. is the only option.*/
  143. uint32_t tx_pin; /**< Number of pin used as TX.*/
  144. uint32_t rx_pin; /**< Number of pin used as RX.*/
  145. uint32_t cts_pin; /**< Number of pin used as CTS.*/
  146. uint32_t rts_pin; /**< Number of pin used as RTS.*/
  147. hal_uart_baudrate_t baudrate; /**< Baudrate selector.*/
  148. hal_uart_parity_t parity; /**< Parity selector.*/
  149. hal_uart_flow_control_t flow_control; /**< Flow control selector.*/
  150. hal_uart_char_size_t char_size; /**< Size of char in bits.*/
  151. hal_uart_stop_bits_t stop_bits; /**< Stop bits number.*/
  152. } hal_uart_config_t;
  153. /**
  154. * @brief This structure defines the UART module operation.
  155. *
  156. * If \a write_buffer_ptr is defined as NULL, then sending data will work
  157. * in blocking way, that is call for \a hal_uart_write will be completed
  158. * only after sending of the last byte passed as input parameter.
  159. *
  160. * If \a read_buffer_ptr is defined as NULL, then driver will drop every
  161. * received byte.
  162. */
  163. typedef struct
  164. {
  165. hal_uart_config_t uart_config; /**< UART settings struct.*/
  166. hal_uart_handler_t write_handler; /**< Callback function for write operation.*/
  167. void * write_buffer_ptr; /**< User-side buffer for write operation.*/
  168. size_t write_buffer_size; /**< Size of write operation buffer.*/
  169. hal_uart_handler_t read_handler; /**< Callback function for read operation.*/
  170. void * read_buffer_ptr; /**< User-side buffer for read operation.*/
  171. size_t read_buffer_size; /**< Size of read operation buffer.*/
  172. hal_uart_error_handler_t error_handler; /**< Callback function in case of something
  173. goes wrong.*/
  174. } hal_uart_descriptor_t;
  175. /**
  176. * @brief Configures UART interface using input parameter.
  177. *
  178. * @param[in] config pointer to a config struct.
  179. * @param[in] descriptor pointer to a descriptor struct.
  180. *
  181. * @return Return status of operation.
  182. */
  183. hal_uart_error_t hal_uart_open(const hal_uart_config_t * config,
  184. const hal_uart_descriptor_t * descriptor);
  185. /**
  186. * @brief Sends data in a non-blocking way.
  187. *
  188. * @param[in] descriptor pointer to the UART module operation structure.
  189. * @param[in] data pointer to the user-side buffer of output data.
  190. * @param[in] length number of bytes to transmit.
  191. *
  192. * If descriptor has a non-null \a write_buffer_ptr then this function will use it
  193. * as a temporary buffer and will copy input \a data to it before starting
  194. * transmit. If descriptor has the NULL \a write_buffer_ptr, then the user-side code
  195. * is responsible to retain \a data until \a write_handler is called.
  196. */
  197. void hal_uart_write(const hal_uart_descriptor_t * descriptor,
  198. const uint8_t * data,
  199. const size_t length);
  200. /**
  201. * @brief Sends a null-terminated C-string in a non-blocking way.
  202. *
  203. * @param[in] descriptor pointer to the UART module operation structure.
  204. * @param[in] s null-terminated string to send.
  205. */
  206. void hal_uart_puts(const hal_uart_descriptor_t * descriptor, const char * s);
  207. /**
  208. * @brief Receives data in a non-blocking way.
  209. *
  210. * @param[in] descriptor pointer to the UART module operation structure.
  211. * @param[out] data pointer to the user-side buffer used to receive data.
  212. * @param[in] length number of bytes to receive.
  213. *
  214. * If descriptor has a non-null \a read_buffer_ptr, then this function is used to
  215. * copy input characters from it to \a data.
  216. * If \a read_buffer_ptr is NULL, then this function ignores all inputs.
  217. */
  218. void hal_uart_read(const hal_uart_descriptor_t * descriptor,
  219. uint8_t * data,
  220. const size_t length);
  221. /**
  222. * @brief Returns number of bytes available to read from the income buffer of the
  223. * driver.
  224. *
  225. * @param[in] descriptor pointer to driver structure.
  226. *
  227. * @return Number of bytes available to read.
  228. */
  229. size_t hal_uart_read_buffer_size_get(const hal_uart_descriptor_t * descriptor);
  230. /**
  231. * @brief Returns number of bytes available to write to the outgoing buffer of the
  232. * driver.
  233. *
  234. * @param[in] descriptor pointer to driver structure.
  235. *
  236. * @return Number of bytes available to write.
  237. */
  238. size_t hal_uart_write_buffer_size_get(const hal_uart_descriptor_t * descriptor);
  239. /**
  240. * @brief This function deallocates resources previously allocated by hal_uart_open.
  241. *
  242. * @param[in] descriptor pointer to driver structure.
  243. *
  244. * @return Return status of operation.
  245. */
  246. hal_uart_error_t hal_uart_close(const hal_uart_descriptor_t * descriptor);
  247. #if defined(CONFIG_TRACE) && defined(CONFIG_DEBUG)
  248. /**
  249. * @brief Finalizes remaining trace data output to UART.
  250. *
  251. * @details This debugging feature is needed to finalize buffered trace output
  252. * to UART before commencing non-buffered assertion output.
  253. */
  254. void hal_uart_trace_finalize(void);
  255. #endif
  256. /** @} */
  257. #endif /* HAL_UART_H_INCLUDED */