1 /* 2 * Copyright (c) 2020-2021 Huawei Device Co., Ltd. 3 * 4 * HDF is dual licensed: you can use it either under the terms of 5 * the GPL, or the BSD license, at your option. 6 * See the LICENSE file in the root of this repository for complete details. 7 */ 8 9 /** 10 * @addtogroup UART 11 * @{ 12 * 13 * @brief Defines standard APIs of universal asynchronous receiver/transmitter (UART) capabilities. 14 * 15 * You can use this module to access the UART and enable the driver to operate a UART-compliant device. 16 * The functions in this module help you to obtain and release the UART device handle, read and write data, 17 * obtain and set the baud rate and device attributes. 18 * 19 * @since 1.0 20 */ 21 22 /** 23 * @file uart_if.h 24 * 25 * @brief Declares standard UART APIs. 26 * 27 * @since 1.0 28 */ 29 30 #ifndef UART_IF_H 31 #define UART_IF_H 32 33 #include "platform_if.h" 34 35 #ifdef __cplusplus 36 extern "C" { 37 #endif /* __cplusplus */ 38 39 /** 40 * @brief Defines basic attributes of the UART port. 41 * 42 * You can configure the attributes via {@link UartSetAttribute}. If the parameters are not set, 43 * default attributes are used. 44 * 45 * @attention The UART controller determines which UART attribute parameters are supported. 46 * 47 * @since 1.0 48 */ 49 struct UartAttribute { 50 /** 51 * Data Bit | Description 52 * ------------| ----------------------- 53 * UART_ATTR_DATABIT_8 | 8 data bits 54 * UART_ATTR_DATABIT_7 | 7 data bits 55 * UART_ATTR_DATABIT_6 | 6 data bits 56 * UART_ATTR_DATABIT_5 | 5 data bits 57 */ 58 unsigned int dataBits : 4; 59 /** 60 * @brief Indicates the UART word length, which is 8 data bits per frame. 61 * 62 * @since 1.0 63 */ 64 #define UART_ATTR_DATABIT_8 0 65 /** 66 * @brief Indicates the UART word length, which is 7 data bits per frame. 67 * 68 * @since 1.0 69 */ 70 #define UART_ATTR_DATABIT_7 1 71 /** 72 * @brief Indicates the UART word length, which is 6 data bits per frame. 73 * 74 * @since 1.0 75 */ 76 #define UART_ATTR_DATABIT_6 2 77 /** 78 * @brief Indicates the UART word length, which is 5 data bits per frame. 79 * 80 * @since 1.0 81 */ 82 #define UART_ATTR_DATABIT_5 3 83 /** 84 * Parity Bit | Description 85 * ------------| ----------------------- 86 * UART_ATTR_PARITY_NONE | No parity bit 87 * UART_ATTR_PARITY_ODD | Odd parity bit 88 * UART_ATTR_PARITY_EVEN | Even parity bit 89 * UART_ATTR_PARITY_MARK | <b>1</b> 90 * UART_ATTR_PARITY_SPACE | <b>0</b> 91 */ 92 unsigned int parity : 4; 93 /** 94 * @brief Indicates that the UART device has no parity bit. 95 * 96 * @since 1.0 97 */ 98 #define UART_ATTR_PARITY_NONE 0 99 /** 100 * @brief Indicates that the UART device has an odd parity bit. 101 * 102 * @since 1.0 103 */ 104 #define UART_ATTR_PARITY_ODD 1 105 /** 106 * @brief Indicates that the UART device has an even parity bit. 107 * 108 * @since 1.0 109 */ 110 #define UART_ATTR_PARITY_EVEN 2 111 /** 112 * @brief Indicates that the parity bit is 1. 113 * 114 * @since 1.0 115 */ 116 #define UART_ATTR_PARITY_MARK 3 117 /** 118 * @brief Indicates that the parity bit is 0. 119 * 120 * @since 1.0 121 */ 122 #define UART_ATTR_PARITY_SPACE 4 123 /** 124 * Stop Bit | Description 125 * ------------| ----------------------- 126 * UART_ATTR_STOPBIT_1 | 1 stop bit 127 * UART_ATTR_STOPBIT_1P5 | 1.5 stop bits 128 * UART_ATTR_STOPBIT_2 | 2 stop bits 129 */ 130 unsigned int stopBits : 4; 131 /** 132 * @brief Indicates that the UART device has 1 stop bit. 133 * 134 * @since 1.0 135 */ 136 #define UART_ATTR_STOPBIT_1 0 137 /** 138 * @brief Indicates that the UART device has 1.5 stop bits. 139 * 140 * @since 1.0 */ 141 #define UART_ATTR_STOPBIT_1P5 1 142 /** 143 * @brief Indicates that the UART device has 2 stop bits. 144 * 145 * @since 1.0 146 */ 147 #define UART_ATTR_STOPBIT_2 2 148 /** 149 * RTS | Description 150 * ------------| ----------------------- 151 * UART_ATTR_RTS_DIS | RTS disabled 152 * UART_ATTR_RTS_EN | RTS enabled 153 */ 154 unsigned int rts : 1; 155 /** 156 * @brief Indicates that Request To Send (RTS) is disabled for the UART device. 157 * 158 * @since 1.0 159 */ 160 #define UART_ATTR_RTS_DIS 0 161 /** 162 * @brief Indicates that RTS is enabled for the UART device. 163 * 164 * @since 1.0 165 */ 166 #define UART_ATTR_RTS_EN 1 167 /** 168 * CTS | Description 169 * ------------| ----------------------- 170 * UART_ATTR_CTS_DIS | CTS disabled 171 * UART_ATTR_CTS_EN | CTS enabled 172 */ 173 unsigned int cts : 1; 174 /** 175 * @brief Indicates that Clear To Send (CTS) is disabled for the UART device. 176 * 177 * @since 1.0 178 */ 179 #define UART_ATTR_CTS_DIS 0 180 /** 181 * @brief Indicates that CTS is enabled for the UART device. 182 * 183 * @since 1.0 184 */ 185 #define UART_ATTR_CTS_EN 1 186 /** 187 * Receiver FIFO | Description 188 * ------------| ----------------------- 189 * UART_ATTR_RX_FIFO_DIS | FIFO disabled 190 * UART_ATTR_RX_FIFO_EN | FIFO enabled 191 */ 192 unsigned int fifoRxEn : 1; 193 /** 194 * @brief Indicates that First In First Out (FIFO) is disabled for the receiving UART. 195 * 196 * @since 1.0 197 */ 198 #define UART_ATTR_RX_FIFO_DIS 0 199 /** 200 * @brief Indicates that FIFO is enabled for the receiving UART. 201 * 202 * @since 1.0 203 */ 204 #define UART_ATTR_RX_FIFO_EN 1 205 /** 206 * Transmitter FIFO | Description 207 * ------------| ----------------------- 208 * UART_ATTR_TX_FIFO_DIS | FIFO disabled 209 * UART_ATTR_TX_FIFO_EN | FIFO enabled 210 */ 211 unsigned int fifoTxEn : 1; 212 /** 213 * @brief Indicates that FIFO is disabled for the transmitting UART. 214 * 215 * @since 1.0 216 */ 217 #define UART_ATTR_TX_FIFO_DIS 0 218 /** 219 * @brief Indicates that FIFO is enabled for the transmitting UART. 220 * 221 * @since 1.0 222 */ 223 #define UART_ATTR_TX_FIFO_EN 1 224 /** Reserved bits */ 225 unsigned int reserved : 16; 226 }; 227 228 /** 229 * @brief Enumerates UART transmission modes. 230 * 231 * @attention The UART controller determines whether an enumerated transmission mode is supported. 232 * 233 * @since 1.0 234 */ 235 enum UartTransMode { 236 UART_MODE_RD_BLOCK = 0, /**< Blocking mode */ 237 UART_MODE_RD_NONBLOCK, /**< Non-blocking mode */ 238 UART_MODE_DMA_RX_EN, /**< DMA enabled for data receiving */ 239 UART_MODE_DMA_RX_DIS, /**< DMA disabled for data receiving */ 240 UART_MODE_DMA_TX_EN, /**< DMA enabled for data transmitting */ 241 UART_MODE_DMA_TX_DIS, /**< DMA disabled for data transmitting */ 242 }; 243 244 /** 245 * @brief Enumerates UART I/O commands. 246 * 247 * @since 1.0 248 */ 249 enum UartIoCmd { 250 UART_IO_REQUEST = 0, /**< Reference count management and initialize the UART device. */ 251 UART_IO_RELEASE, /**< Reference count management and deinitialize the UART device. */ 252 UART_IO_READ, /**< Read data. */ 253 UART_IO_WRITE, /**< Write data. */ 254 UART_IO_GET_BAUD, /**< Obtain the baud rate. */ 255 UART_IO_SET_BAUD, /**< Set the baud rate. */ 256 UART_IO_GET_ATTRIBUTE, /**< Obtain the device attributes. */ 257 UART_IO_SET_ATTRIBUTE, /**< Set the device attributes. */ 258 UART_IO_SET_TRANSMODE, /**< Set the transmission mode. */ 259 }; 260 261 /** 262 * @brief Obtains the UART device handle. 263 * 264 * Before accessing the UART device, you must call this function to obtain the UART device handle. 265 * 266 * @param port Indicates the UART port. 267 * 268 * @return Returns the pointer to the UART device handle if the handle is obtained; returns <b>NULL</b> otherwise. 269 * @since 1.0 270 */ 271 DevHandle UartOpen(uint32_t port); 272 273 /** 274 * @brief Releases the UART device handle. 275 * 276 * If you no longer need to access the UART device, you should call this function to close its handle so as to 277 * release unused memory resources. 278 * 279 * @param handle Indicates the pointer to the UART device handle, which is obtained via {@link UartOpen}. 280 * 281 * @since 1.0 282 */ 283 void UartClose(DevHandle handle); 284 285 /** 286 * @brief Reads data of a specified size from a UART device. 287 * 288 * @param handle Indicates the pointer to the UART device handle, which is obtained via {@link UartOpen}. 289 * @param data Indicates the pointer to the buffer for receiving the data. 290 * @param size Indicates the size of the data to read. 291 * 292 * @return Returns the size of the data that is successfully read; returns a negative number if the reading fails. 293 * @since 1.0 294 */ 295 int32_t UartRead(DevHandle handle, uint8_t *data, uint32_t size); 296 297 /** 298 * @brief Writes data of a specified size into a UART device. 299 * 300 * @param handle Indicates the pointer to the UART device handle, which is obtained via {@link UartOpen}. 301 * @param data Indicates the pointer to the data to write. 302 * @param size Indicates the size of the data to write. 303 * 304 * @return Returns <b>0</b> if the data is successfully written; returns a negative number otherwise. 305 * @since 1.0 306 */ 307 int32_t UartWrite(DevHandle handle, uint8_t *data, uint32_t size); 308 309 /** 310 * @brief Obtains the baud rate of the UART device. 311 * 312 * @param handle Indicates the pointer to the UART device handle, which is obtained via {@link UartOpen}. 313 * @param baudRate Indicates the pointer to the obtained baud rate. 314 * 315 * @return Returns <b>0</b> if the baud rate is obtained; returns a negative number otherwise. 316 * @since 1.0 317 */ 318 int32_t UartGetBaud(DevHandle handle, uint32_t *baudRate); 319 320 /** 321 * @brief Sets the baud rate for the UART device. 322 * 323 * @param handle Indicates the pointer to the UART device handle, which is obtained via {@link UartOpen}. 324 * @param baudRate Indicates the baud rate to set. 325 * 326 * @return Returns <b>0</b> if the setting is successful; returns a negative number otherwise. 327 * @since 1.0 328 */ 329 int32_t UartSetBaud(DevHandle handle, uint32_t baudRate); 330 331 /** 332 * @brief Obtains the UART attribute. 333 * 334 * UART attributes include data bits, stop bits, parity bit, CTS, RTS, and receiving and transmitting FIFO. 335 * 336 * @param handle Indicates the pointer to the UART device handle, which is obtained via {@link UartOpen}. 337 * @param attribute Indicates the pointer to the obtained UART attribute. 338 * 339 * @return Returns <b>0</b> if the UART attribute is obtained; returns a negative number otherwise. 340 * @since 1.0 */ 341 int32_t UartGetAttribute(DevHandle handle, struct UartAttribute *attribute); 342 343 /** 344 * @brief Sets the UART attribute. 345 * 346 * UART attributes include data bits, stop bits, parity bit, CTS, RTS, and receiving and transmitting FIFO. 347 * 348 * @param handle Indicates the pointer to the UART device handle, which is obtained via {@link UartOpen}. 349 * @param attribute Indicates the pointer to the UART attribute to set. 350 * 351 * @return Returns <b>0</b> if the setting is successful; returns a negative number otherwise. 352 * @since 1.0 353 */ 354 int32_t UartSetAttribute(DevHandle handle, struct UartAttribute *attribute); 355 356 /** 357 * @brief Sets the UART transmission mode. 358 * 359 * @param handle Indicates the pointer to the UART device handle, which is obtained via {@link UartOpen}. 360 * @param mode Indicates a transmission mode enumerated in {@linkUartTransMode}. 361 * 362 * @return Returns <b>0</b> if the setting is successful; returns a negative number otherwise. 363 * @since 1.0 364 */ 365 int32_t UartSetTransMode(DevHandle handle, enum UartTransMode mode); 366 367 #ifdef __cplusplus 368 } 369 #endif /* __cplusplus */ 370 371 #endif /* PAL_UART_IF_H */ 372 /** @} */ 373