1 /** 2 * @file uart.h 3 * @copyright Copyright (C) 2015-2018 Alibaba Group Holding Limited 4 */ 5 6 #ifndef HAL_UART_H 7 #define HAL_UART_H 8 9 #ifdef __cplusplus 10 extern "C" { 11 #endif 12 13 /** @addtogroup hal_uart UART 14 * uart hal API. 15 * 16 * @{ 17 */ 18 19 #include <stdint.h> 20 21 /* Define the wait forever timeout macro */ 22 #define HAL_WAIT_FOREVER 0xFFFFFFFFU 23 24 #ifndef HAL_UART_STDIO_PORT 25 #define HAL_UART_STDIO_PORT 0 26 #endif 27 28 /* 29 * UART data width 30 */ 31 typedef enum { 32 DATA_WIDTH_5BIT, 33 DATA_WIDTH_6BIT, 34 DATA_WIDTH_7BIT, 35 DATA_WIDTH_8BIT, 36 DATA_WIDTH_9BIT 37 } hal_uart_data_width_t; 38 39 /* 40 * UART stop bits 41 */ 42 typedef enum { 43 STOP_BITS_1, 44 STOP_BITS_2 45 } hal_uart_stop_bits_t; 46 47 /* 48 * UART flow control 49 */ 50 typedef enum { 51 FLOW_CONTROL_DISABLED, /**< Flow control disabled */ 52 FLOW_CONTROL_CTS, /**< Clear to send, yet to send data */ 53 FLOW_CONTROL_RTS, /**< Require to send, yet to receive data */ 54 FLOW_CONTROL_CTS_RTS /**< Both CTS and RTS flow control */ 55 } hal_uart_flow_control_t; 56 57 /* 58 * UART parity 59 */ 60 typedef enum { 61 NO_PARITY, /**< No parity check */ 62 ODD_PARITY, /**< Odd parity check */ 63 EVEN_PARITY /**< Even parity check */ 64 } hal_uart_parity_t; 65 66 /* 67 * UART mode 68 */ 69 typedef enum { 70 MODE_TX, /**< Uart in send mode */ 71 MODE_RX, /**< Uart in receive mode */ 72 MODE_TX_RX /**< Uart in send and receive mode */ 73 } hal_uart_mode_t; 74 75 /* 76 * UART configuration 77 */ 78 typedef struct { 79 uint32_t baud_rate; /**< Uart baud rate */ 80 hal_uart_data_width_t data_width; /**< Uart data width */ 81 hal_uart_parity_t parity; /**< Uart parity check mode */ 82 hal_uart_stop_bits_t stop_bits; /**< Uart stop bit mode */ 83 hal_uart_flow_control_t flow_control; /**< Uart flow control mode */ 84 hal_uart_mode_t mode; /**< Uart send/receive mode */ 85 } uart_config_t; 86 87 /* 88 * UART dev handle 89 */ 90 typedef struct { 91 uint8_t port; /**< uart port */ 92 uart_config_t config; /**< uart config */ 93 void *priv; /**< priv data */ 94 } uart_dev_t; 95 96 typedef int32_t (*uart_rx_cb)(uart_dev_t *uart); 97 98 /** 99 * Initialises a UART interface 100 * 101 * 102 * @param[in] uart the interface which should be initialised 103 * 104 * @return 0 : on success, otherwise is error 105 */ 106 int32_t hal_uart_init(uart_dev_t *uart); 107 108 /** 109 * Transmit data on a UART interface 110 * 111 * @param[in] uart the UART interface 112 * @param[in] data pointer to the start of data 113 * @param[in] size number of bytes to transmit 114 * @param[in] timeout timeout in milisecond, set this value to HAL_WAIT_FOREVER 115 * if you want to wait forever 116 * 117 * @return 0 : on success, otherwise is error 118 */ 119 int32_t hal_uart_send(uart_dev_t *uart, const void *data, uint32_t size, uint32_t timeout); 120 121 /** 122 * Transmit data on a UART interface with polling 123 * 124 * @param[in] uart the UART interface 125 * @param[in] data pointer to the start of data 126 * @param[in] size number of bytes to transmit 127 * 128 * @return 0 : on success, otherwise is error 129 */ 130 int32_t hal_uart_send_poll(uart_dev_t *uart, const void *data, uint32_t size); 131 132 /** 133 * Receive data on a UART interface 134 * 135 * @param[in] uart the UART interface 136 * @param[out] data pointer to the buffer which will store incoming data 137 * @param[in] expect_size number of bytes to receive 138 * @param[in] timeout timeout in milisecond, set this value to HAL_WAIT_FOREVER 139 * if you want to wait forever 140 * 141 * @return 0 : on success, otherwise is error 142 */ 143 int32_t hal_uart_recv(uart_dev_t *uart, void *data, uint32_t expect_size, uint32_t timeout); 144 145 146 /** 147 * Receive data on a UART interface with polling 148 * 149 * @param[in] uart the UART interface 150 * @param[out] data pointer to the buffer which will store incoming data 151 * @param[in] expect_size number of bytes to receive 152 * @param[in] timeout timeout in milisecond, set this value to HAL_WAIT_FOREVER 153 * if you want to wait forever 154 * 155 * @return 0 : on success, otherwise is error 156 */ 157 int32_t hal_uart_recv_poll(uart_dev_t *uart, void *data, uint32_t expect_size); 158 159 160 /** 161 * Receive data on a UART interface 162 * 163 * @param[in] uart the UART interface 164 * @param[out] data pointer to the buffer which will store incoming data 165 * @param[in] expect_size number of bytes to receive 166 * @param[out] recv_size number of bytes trully received 167 * @param[in] timeout timeout in milisecond, set this value to HAL_WAIT_FOREVER 168 * if you want to wait forever 169 * 170 * @return 0 : on success, otherwise is error 171 */ 172 int32_t hal_uart_recv_II(uart_dev_t *uart, void *data, uint32_t expect_size, 173 uint32_t *recv_size, uint32_t timeout); 174 175 /* 176 * 177 * @param [in] uart the UART interface 178 * @param [in] rx_cb Non-zero pointer is the rx callback handler; 179 * NULL pointer for rx_cb unregister operation 180 * uart in rx_cb must be the same pointer with uart pointer passed to hal_uart_recv_cb_reg 181 * driver must notify upper layer by calling rx_cb if data is available in UART's hw or rx buffer 182 * @return 0: on success, negative no.: if an error occured with any step 183 */ 184 int32_t hal_uart_recv_cb_reg(uart_dev_t *uart, uart_rx_cb cb); 185 186 /** 187 * Deinitialises a UART interface 188 * 189 * @param[in] uart the interface which should be deinitialised 190 * 191 * @return 0 : on success, otherwise is error 192 */ 193 int32_t hal_uart_finalize(uart_dev_t *uart); 194 195 /** @} */ 196 197 #ifdef __cplusplus 198 } 199 #endif 200 201 #endif /* HAL_UART_H */ 202 203