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