1 /** 2 * Copyright (c) 2020 HiSilicon (Shanghai) Technologies CO., LIMITED. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 * 15 * Description: Provides UART driver api \n 16 * 17 * History: \n 18 * 2022-06-01, Create file. \n 19 */ 20 #ifndef UART_H 21 #define UART_H 22 23 #include <stdint.h> 24 #include <stddef.h> 25 #include "errcode.h" 26 #include "hal_uart.h" 27 #include "uart_porting.h" 28 29 #if !defined(CONFIG_UART_SUPPORT_TX) && !defined(CONFIG_UART_SUPPORT_RX) 30 #error UART must support TX or RX 31 #endif /* !defined(CONFIG_UART_SUPPORT_TX) && !defined(CONFIG_UART_SUPPORT_RX) */ 32 33 #ifdef __cplusplus 34 #if __cplusplus 35 extern "C" { 36 #endif /* __cplusplus */ 37 #endif /* __cplusplus */ 38 39 /** 40 * @defgroup drivers_driver_uart UART 41 * @ingroup drivers_driver 42 * @{ 43 */ 44 45 /** 46 * @if Eng 47 * @brief Definition of UART pin configuration. 48 * @else 49 * @brief UART PIN配置结构体。 50 * @endif 51 */ 52 typedef hal_uart_pin_config_t uart_pin_config_t; 53 54 /** 55 * @if Eng 56 * @brief Definition of UART data bit. 57 * @else 58 * @brief UART停止位定义。 59 * @endif 60 */ 61 typedef hal_uart_data_bit_t uart_data_bit_t; 62 63 /** 64 * @if Eng 65 * @brief Definition of UART parity. 66 * @else 67 * @brief UART奇偶校验位定义。 68 * @endif 69 */ 70 typedef hal_uart_parity_t uart_parity_t; 71 72 /** 73 * @if Eng 74 * @brief Definition of UART stop bit. 75 * @else 76 * @brief UART停止位定义。 77 * @endif 78 */ 79 typedef hal_uart_stop_bit_t uart_stop_bit_t; 80 81 /** 82 * @if Eng 83 * @brief Definition of UART attributes. 84 * @else 85 * @brief UART基本属性定义。 86 * @endif 87 */ 88 typedef hal_uart_attr_t uart_attr_t; 89 90 /** 91 * @if Eng 92 * @brief Definition of UART extral attributes. 93 * @else 94 * @brief UART扩展属性定义。 95 * @endif 96 */ 97 typedef hal_uart_extra_attr_t uart_extra_attr_t; 98 99 /** 100 * @if Eng 101 * @brief Definition of UART Flow Control. 102 * @else 103 * @brief UART流控类型定义。 104 * @endif 105 */ 106 typedef hal_uart_flow_ctrl_t uart_flow_ctrl_t; 107 108 #if defined(CONFIG_UART_SUPPORT_TX) && defined(CONFIG_UART_SUPPORT_DMA) 109 /** 110 * @if Eng 111 * @brief Definition of UART DMA configuration. 112 * @else 113 * @brief UART DMA配置数据结构定义。 114 * @endif 115 */ 116 typedef struct uart_write_dma_config { 117 uint8_t src_width; /*!< @if Eng Transfer data width of the source. 118 * - 0: 1byte 119 * - 1: 2byte 120 * - 2: 4byte 121 * @else 源端传输数据宽度 \n 122 * - 0: 1字节 123 * - 1: 2字节 124 * - 2: 4字节 125 * @endif */ 126 uint8_t dest_width; /*!< @if Eng Transfer data width of the destination. 127 * - 0: 1byte 128 * - 1: 2byte 129 * - 2: 4byte 130 * @else 目的端传输数据宽度 \n 131 * - 0: 1字节 132 * - 1: 2字节 133 * - 2: 4字节 134 * @endif */ 135 uint8_t burst_length; /*!< @if Eng Number of data items, to be written to the destination every time 136 * a destination burst transaction request is made from 137 * either the corresponding hardware or software handshaking interface. 138 * - 0: burst length is 1 139 * - 1: burst length is 4 140 * - 2: burst length is 8 141 * - 3: burst length is 16 142 * @else 每次从相应的硬件或软件握手接口发出目的burst请求时,要写入目的端数据量 143 * - 0: burst长度是1 144 * - 1: burst长度是4 145 * - 2: burst长度是8 146 * - 3: burst长度是16 147 * @endif */ 148 uint8_t priority; /*!< @if Eng Transfer channel priority(Minimum: 0 and Maximum: 3). 149 * @else 传输通道优先级(最小为0以及最大为3) @endif */ 150 } uart_write_dma_config_t; 151 #endif /* defined(CONFIG_UART_SUPPORT_TX) && defined(CONFIG_UART_SUPPORT_DMA) */ 152 153 /** 154 * @if Eng 155 * @brief UART buffer configuration 156 * @else 157 * @brief UART 缓存数据结构定义。 158 * @endif 159 */ 160 typedef struct uart_buffer_config { 161 void *rx_buffer; /*!< @if Eng Reception buffer pointer. 162 @else 接收数据的buffer指针 @endif */ 163 size_t rx_buffer_size; /*!< @if Eng Reception buffer size in bytes. 164 @else 接收Buffer的长度 @endif */ 165 } uart_buffer_config_t; 166 167 #if defined(CONFIG_UART_SUPPORT_RX) 168 169 #define UART_RX_CONDITION_MASK_IDLE 1 170 #define UART_RX_CONDITION_MASK_SUFFICIENT_DATA 2 171 #define UART_RX_CONDITION_MASK_FULL 4 172 173 /** 174 * @if Eng 175 * @brief UART Condition under the RX Callback will be invoked 176 * @else 177 * @brief UART在数据接收的时候触发回调的条件定义。 178 * @endif 179 */ 180 typedef enum uart_rx_condition { 181 /** @if Eng A call-back will be made if the RX data pauses or there is no more RX buffer space. \n 182 * So data is no longer being accepted. When registering this condition, a back-log of. 183 * @else 如果数据接收暂停，或者接收缓存已经满了，就触发数据接收回调，\n 184 * 在接收回调处理过程中接收到的UART数据，会直接丢弃。 185 * @endif */ 186 UART_RX_CONDITION_FULL_OR_IDLE = (UART_RX_CONDITION_MASK_FULL | UART_RX_CONDITION_MASK_IDLE), 187 /** @if Eng A call-back will be made as soon as possible after the specified amount of data is 188 * received or there is no more RX buffer space. \n 189 * So data is no longer being accepted. More than the requested data may be 190 * provided to the call-back if there was a back-log of received data. 191 * @else 如果接收缓存已满，或者接收的数据量到达指定的数据长度，就触发数据接收回调，\n 192 * 在接收回调处理过程中接收到的UART数据，会直接丢弃。 193 * 如果存在接收数据的积压数据，则可以向回调提供超过请求的数据。 @endif */ 194 UART_RX_CONDITION_FULL_OR_SUFFICIENT_DATA = (UART_RX_CONDITION_MASK_FULL | UART_RX_CONDITION_MASK_SUFFICIENT_DATA), 195 196 /** @if Eng A call-back will be made if the RX data buffer is full or 197 * the specified number of bytes has been received or there is a pause. \n 198 * So data is no longer being accepted. 199 * @else 如果接收缓存已满，或者接收的数据量到达指定的数据长度，或者接收数据暂停，就触发数据接收回调，\n 200 * 在接收回调处理过程中接收到的UART数据，会直接丢弃。 @endif */ 201 UART_RX_CONDITION_FULL_OR_SUFFICIENT_DATA_OR_IDLE = (UART_RX_CONDITION_MASK_FULL | 202 UART_RX_CONDITION_MASK_SUFFICIENT_DATA | 203 UART_RX_CONDITION_MASK_IDLE) 204 } uart_rx_condition_t; 205 206 /** 207 * @if Eng 208 * @brief UART Transmission Callback type to call when the RX condition registered on 209 * @ref uapi_uart_register_rx_callback call or on error. 210 * @note This callback is invoked in an interrupt context and the buffer will be freed after the call. 211 * @param buffer pointer to the beginning of the buffer read. 212 * @param length length of the buffer. 213 * @param error true if there was an error on the line for this buffer, false otherwise. 214 * Errors registered are parity, stop bits, data bits. 215 * @else 216 * @brief UART接收数据的回调函数，通过 @ref uapi_uart_register_rx_callback 注册到驱动中。 217 * @note 这个函数是在中断上下文中执行的。 218 * @param buffer 读取数据时用于存储数据的Buffer。 219 * @param length 读取数据时用于存储数据的Buffer的长度。 220 * @param error true表示在接收数据时产生了错误（可能的错误是parity, stop bits, data bits），否则表示正常的数据读取。 221 * @endif 222 */ 223 typedef void (*uart_rx_callback_t)(const void *buffer, uint16_t length, bool error); 224 225 #if defined(CONFIG_UART_SUPPORT_INT_TRIGGER_DMA) && defined(CONFIG_UART_SUPPORT_DMA) 226 /** 227 * @if Eng 228 * @brief UART RX interrupt triggers DMA transfer data 229 * @ref uapi_uart_register_read_by_dma_callback call or on error. 230 * @note This callback is invoked in an interrupt context. 231 * @param [in] bus The UART bus. see @ref uart_bus_t 232 * @param [in] buffer Destination address transferred by the DMA. 233 * @param [in] length Length of the data transferred by the DMA. 234 * @param [in] dma_cfg Dma configuration of UART. see @ref uart_write_dma_config_t 235 * @else 236 * @brief UART RX中断触发DMA搬运数据，通过 @ref uapi_uart_register_read_by_dma_callback 注册到驱动中。 237 * @note 这个函数是在中断上下文中执行的。 238 * @param [in] bus 串口号， 参考 @ref uart_bus_t 239 * @param [in] buffer DMA搬运的目的地址。 240 * @param [in] length DMA搬运的数据长度。 241 * @param [in] dma_cfg 接收数据时候的DMA配置，参考 @ref uart_write_dma_config_t 242 * @endif 243 */ 244 typedef void (*uart_rx_by_dma_callback_t)(uart_bus_t bus, const void *buffer, uint32_t length, 245 uart_write_dma_config_t *dma_cfg); 246 #endif /* defined(CONFIG_UART_SUPPORT_INT_TRIGGER_DMA) && defined(CONFIG_UART_SUPPORT_DMA) */ 247 #endif /* CONFIG_UART_SUPPORT_RX */ 248 249 #if defined(CONFIG_UART_SUPPORT_TX) 250 /** 251 * @if Eng 252 * @brief UART Transmission Callback type to pass to the @ref uapi_uart_write_int function. 253 * @note This callback is invoked in an interrupt context. 254 * @param buffer buffer given on the @ref uapi_uart_write_int call. 255 * @param length length given on the @ref uapi_uart_write_int call. 256 * @param params params given on the @ref uapi_uart_write_int call. 257 * @else 258 * @brief UART发送数据的回调函数，在调用 @ref uapi_uart_write_int 时传递给函数。 259 * @note 这个函数是在中断上下文中执行的。 260 * @param buffer @ref uapi_uart_write_int 调用时的数据缓存。 261 * @param length @ref uapi_uart_write_int 调用时的数据长度。 262 * @param params @ref uapi_uart_write_int 调用时传递进去的参数。 263 * @endif 264 */ 265 typedef void (*uart_tx_callback_t)(const void *buffer, uint32_t length, const void *params); 266 #endif /* CONFIG_UART_SUPPORT_TX */ 267 268 /** 269 * @if Eng 270 * @brief UART Transmission Callback type to call when the RX condition registered on 271 * uapi_uart_register_frame_error_callback call or uart_register_parity_error_callback on error. 272 * @note This callback is invoked in an interrupt context and the buffer will be freed after the call. 273 * Errors registered are frame. 274 * @param err_info The UART error info data, every data is 32-bit. 275 * @param len The UART error info data, every data is 32-bit. 276 * @else 277 * @brief UART错误处理回调函数，通过uapi_uart_register_frame_error_callback注册到驱动中。 278 * @note 这个函数是在中断上下文中执行的，而且在执行完成之后会自动释放内存。 279 * @param err_info 错误信息，每一个成员都是32-bit的。 280 * @param len 错误信息的长度。 281 * @endif 282 */ 283 typedef void (*uart_error_callback_t)(uint32_t *err_info, uint32_t len); 284 285 /** 286 * @if Eng 287 * @brief Initialize the serial port. 288 * @param [in] bus The UART bus. see @ref uart_bus_t. 289 * @param [in] pins The PINs to use for UART TX, RX, RTS and CTS. 290 * @param [in] attr Basic configuration of UART. see @ref uart_attr_t. 291 * @param [in] extra_attr High-level configuration of UART. see @ref uart_extra_attr_t. 292 * @param [in] uart_buffer_config Specify a reception buffer. 293 * @retval ERRCODE_SUCC Success. 294 * @retval Other Failure. For details, see @ref errcode_t 295 * @else 296 * @brief 初始化指定的串口。 297 * @param [in] bus 串口号，参考 @ref uart_bus_t 。 298 * @param [in] pins UART中使用的PIN，包括TX, RX, RTS和CTS。 299 * @param [in] attr UART的基础配置参数，参考 @ref uart_attr_t 。 300 * @param [in] extra_attr UART的高级配置参数，参考 @ref uart_extra_attr_t 。 301 * @param [in] uart_buffer_config 指定UART的接收Buffer。 302 * @retval ERRCODE_SUCC 成功。 303 * @retval Other 失败，参考 @ref errcode_t 。 304 * @endif 305 */ 306 errcode_t uapi_uart_init(uart_bus_t bus, const uart_pin_config_t *pins, 307 const uart_attr_t *attr, const uart_extra_attr_t *extra_attr, 308 uart_buffer_config_t *uart_buffer_config); 309 310 /** 311 * @if Eng 312 * @brief Deinitialize the serial port. 313 * @param [in] bus The UART bus, see @ref uart_bus_t. 314 * @retval ERRCODE_SUCC Success. 315 * @retval Other Failure. For details, see @ref errcode_t. 316 * @else 317 * @brief 去初始化指定的串口。 318 * @param [in] bus 串口号，参考 @ref uart_bus_t 。 319 * @retval ERRCODE_SUCC 成功。 320 * @retval Other 失败，参考 @ref errcode_t 。 321 * @endif 322 */ 323 errcode_t uapi_uart_deinit(uart_bus_t bus); 324 325 /** 326 * @if Eng 327 * @brief Set UART basic configuration. 328 * @param [in] bus The UART bus. see @ref uart_bus_t. 329 * @param [in] attr Basic configuration of UART. see @ref uart_attr_t. 330 * @retval ERRCODE_SUCC Success. 331 * @retval Other Failure. For details, see @ref errcode_t. 332 * @else 333 * @brief 设置串口的基础配置参数。 334 * @param [in] bus 串口号，参考 @ref uart_bus_t 。 335 * @param [in] attr UART的基础配置参数，参考 @ref uart_attr_t 。 336 * @retval ERRCODE_SUCC 成功。 337 * @retval Other 失败，参考 @ref errcode_t 。 338 * @endif 339 */ 340 errcode_t uapi_uart_set_attr(uart_bus_t bus, const uart_attr_t *attr); 341 342 /** 343 * @if Eng 344 * @brief Get UART basic configuration. 345 * @param [in] bus The UART bus. see @ref uart_bus_t. 346 * @param [in] attr Basic configuration of UART. see @ref uart_attr_t. 347 * @retval ERRCODE_SUCC Success. 348 * @retval Other Failure. For details, see @ref errcode_t. 349 * @else 350 * @brief 获取串口的基础配置参数。 351 * @param [in] bus 串口号，参考 @ref uart_bus_t 。 352 * @param [in] attr UART的基础配置参数，参考 @ref uart_attr_t 。 353 * @retval ERRCODE_SUCC 成功。 354 * @retval Other 失败，参考 @ref errcode_t 。 355 * @endif 356 */ 357 errcode_t uapi_uart_get_attr(uart_bus_t bus, const uart_attr_t *attr); 358 359 /** 360 * @if Eng 361 * @brief Returns true if there are pending transmissions. 362 * @param [in] bus The UART bus. see @ref uart_bus_t. 363 * @return true indicates that there're pending transmissions, otherwise false. 364 * @else 365 * @brief 判断是否存在正在等待的传输。 366 * @param [in] bus 串口号，参考 @ref uart_bus_t 。 367 * @return true表示存在正在等待的传输，false表示没有正在等待的传输。 368 * @endif 369 */ 370 bool uapi_uart_has_pending_transmissions(uart_bus_t bus); 371 372 /** 373 * @if Eng 374 * @brief Returns true if rx fifo is empty. 375 * @param [in] bus The UART bus. see @ref uart_bus_t. 376 * @return true indicates that rx fifo is empty, otherwise false. 377 * @else 378 * @brief 判断RX FIFO是否为空。 379 * @param [in] bus 串口号，参考 @ref uart_bus_t 。 380 * @return true表示RX FIFO为空，false表示RX FIFO非空。 381 * @endif 382 */ 383 bool uapi_uart_rx_fifo_is_empty(uart_bus_t bus); 384 385 /** 386 * @if Eng 387 * @brief Returns true if tx fifo is empty. 388 * @param [in] bus The UART bus. see @ref uart_bus_t. 389 * @return true indicates that tx fifo is empty, otherwise false. 390 * @else 391 * @brief 判断TX FIFO是否为空。 392 * @param [in] bus 串口号，参考 @ref uart_bus_t 。 393 * @return true表示TX FIFO为空，false表示TX FIFO非空。 394 * @endif 395 */ 396 bool uapi_uart_tx_fifo_is_empty(uart_bus_t bus); 397 398 #if defined(CONFIG_UART_SUPPORT_RX) 399 /** 400 * @if Eng 401 * @brief Registers a receive callback that will be triggered depending on condition and size. 402 * @note Callback will be called in an interrupt context. 403 * @param [in] bus The UART bus. see @ref uart_bus_t. 404 * @param [in] condition Condition on which the callback will be triggered. 405 * @param [in] size If condition implies a size this will be used. 406 * @param [in] callback Receive callback to call. 407 * @retval ERRCODE_SUCC Success. 408 * @retval Other Failure. For details, see @ref errcode_t 409 * @else 410 * @brief 注册接收回调函数，这个回调函数会根据触发条件和Size触发。 411 * @note 回调函数在中断上下文执行。 412 * @param [in] bus 串口号，参考 @ref uart_bus_t 。 413 * @param [in] condition 回调触发的条件，参考 @ref uart_rx_condition_t 。 414 * @param [in] size 如果触发条件涉及到数据长度，这个参数就表示需要的数据长度。 415 * @param [in] callback 接收数据的回调函数。 416 * @retval ERRCODE_SUCC 成功。 417 * @retval Other 失败，参考 @ref errcode_t 。 418 * @endif 419 */ 420 errcode_t uapi_uart_register_rx_callback(uart_bus_t bus, uart_rx_condition_t condition, 421 uint32_t size, uart_rx_callback_t callback); 422 423 /** 424 * @if Eng 425 * @brief Unregisters a receive callback. 426 * @param [in] bus The UART bus. see @ref uart_bus_t. 427 * @else 428 * @brief 去注册接收回调函数。 429 * @param [in] bus 串口号，参考 @ref uart_bus_t 。 430 * @endif 431 */ 432 void uapi_uart_unregister_rx_callback(uart_bus_t bus); 433 434 /** 435 * @if Eng 436 * @brief Registers a parity error callback that will be triggered. 437 * @note Callback will be called in an interrupt context. 438 * @param [in] bus The UART bus. see @ref uart_bus_t. 439 * @param [in] callback Parity error callback to call. 440 * @retval ERRCODE_SUCC Success. 441 * @retval Other Failure. For details, see @ref errcode_t. 442 * @else 443 * @brief 注册奇偶校验错误处理的回调函数。 444 * @note 回调函数在中断上下文执行。 445 * @param [in] bus 串口号，参考 @ref uart_bus_t 。 446 * @param [in] callback 奇偶校验错误处理回调函数。 447 * @retval ERRCODE_SUCC 成功。 448 * @retval Other 失败，参考 @ref errcode_t 。 449 * @endif 450 */ 451 errcode_t uapi_uart_register_parity_error_callback(uart_bus_t bus, uart_error_callback_t callback); 452 453 /** 454 * @if Eng 455 * @brief Registers a frame error callback that will be triggered. 456 * @note Callback will be called in an interrupt context. 457 * @param [in] bus The UART bus. see @ref uart_bus_t. 458 * @param [in] callback Frame error callback to call. 459 * @retval ERRCODE_SUCC Success. 460 * @retval Other Failure. For details, see @ref errcode_t. 461 * @else 462 * @brief 注册帧错误处理回调函数。 463 * @note 回调函数在中断上下文执行。 464 * @param [in] bus 串口号，参考 @ref uart_bus_t 。 465 * @param [in] callback 帧错误错误处理回调函数。 466 * @retval ERRCODE_SUCC 成功。 467 * @retval Other 失败，参考 @ref errcode_t 。 468 * @endif 469 */ 470 errcode_t uapi_uart_register_frame_error_callback(uart_bus_t bus, uart_error_callback_t callback); 471 472 /** 473 * @if Eng 474 * @brief Registers a overrun error callback that will be triggered. 475 * @note Callback will be called in an interrupt context. 476 * @param [in] bus The UART bus. see @ref uart_bus_t. 477 * @param [in] callback overrun error callback to call. 478 * @retval ERRCODE_SUCC Success. 479 * @retval Other Failure. For details, see @ref errcode_t. 480 * @else 481 * @brief 注册溢出错误处理回调函数。 482 * @note 回调函数在中断上下文执行。 483 * @param [in] bus 串口号，参考 @ref uart_bus_t 。 484 * @param [in] callback 溢出错误错误处理回调函数。 485 * @retval ERRCODE_SUCC 成功。 486 * @retval Other 失败，参考 @ref errcode_t 。 487 * @endif 488 */ 489 errcode_t uapi_uart_register_overrun_error_callback(uart_bus_t bus, uart_error_callback_t callback); 490 #endif /* CONFIG_UART_SUPPORT_RX */ 491 492 #if defined(CONFIG_UART_SUPPORT_TX) 493 /** 494 * @if Eng 495 * @brief Writes a buffer to an opened UART in polling mode. 496 * @param [in] bus The UART bus. see @ref uart_bus_t 497 * @param [in] buffer Pointer to the buffer to write through the UART. 498 * @param [in] length Length of the buffer to write. 499 * @param [in] timeout Timeout duration. 500 * @return Amount of data write to UART. 501 * @else 502 * @brief 将数据发送到已经打开的UART上，使用直接发送的方式。 503 * @param [in] bus 串口号，参考 @ref uart_bus_t 。 504 * @param [in] buffer 要发送的数据Buffer。 505 * @param [in] length 要发送的数据Buffer长度。 506 * @param [in] timeout 超时时间。 507 * @return 实际发送的数据长度。 508 * @endif 509 */ 510 int32_t uapi_uart_write(uart_bus_t bus, const uint8_t *buffer, uint32_t length, uint32_t timeout); 511 512 /** 513 * @if Eng 514 * @brief Writes a buffer to an opened UART by interrupt and 515 * calls a finished_with_buffer_func call back when it finish. 516 * @note callback will be called in an interrupt context. 517 * @param [in] bus The UART bus. see @ref uart_bus_t 518 * @param [in] buffer Pointer to the buffer to write through the UART. 519 * @param [in] length Length of the buffer to write. 520 * @param [in] params Parameter to pass to finished_with_buffer_func. 521 * @param [in] finished_with_buffer_func Function to call when the buffer is fully transmitted. it will be called in 522 * the way finished_with_buffer_func(buffer, length, params). 523 * @retval ERRCODE_SUCC Success. 524 * @retval Other Failure. For details, see @ref errcode_t. 525 * @else 526 * @brief 使用中断模式将数据发送到已经打开的UART上，当数据发送完成，会调用回调函数。 527 * @note 回调函数在中断上下文执行。 528 * @param [in] bus 串口号，参考 @ref uart_bus_t 。 529 * @param [in] buffer 要发送的数据Buffer。 530 * @param [in] length 要发送的数据Buffer长度。 531 * @param [in] params 传递到完成传输的回调函数的参数。 532 * @param [in] finished_with_buffer_func 数据发送完成的回调函数。 533 * @retval ERRCODE_SUCC 成功。 534 * @retval Other 失败，参考 @ref errcode_t 。 535 * @endif 536 */ 537 errcode_t uapi_uart_write_int(uart_bus_t bus, const uint8_t *buffer, uint32_t length, 538 void *params, uart_tx_callback_t finished_with_buffer_func); 539 540 #if defined(CONFIG_UART_SUPPORT_DMA) 541 /** 542 * @if Eng 543 * @brief Write data to the UART by dma. 544 * @param [in] bus The UART bus. see @ref uart_bus_t. 545 * @param [in] buffer Pointer to the write buffer. 546 * @param [in] length Length of the buffer. 547 * @param [in] dma_cfg Dma configuration of UART. see @ref uart_write_dma_config_t. 548 * @return The count of data have been sent by UART. 549 * @else 550 * @brief 通过DMA发送数据。 551 * @param [in] bus 串口号，参考 @ref uart_bus_t 。 552 * @param [in] buffer 要发送的数据Buffer。 553 * @param [in] length 要发送的数据Buffer长度。 554 * @param [in] dma_cfg 发送数据时候的DMA配置，参考 @ref uart_write_dma_config_t 。 555 * @return 完成发送的数据长度。 556 * @endif 557 */ 558 int32_t uapi_uart_write_by_dma(uart_bus_t bus, const void *buffer, uint32_t length, uart_write_dma_config_t *dma_cfg); 559 560 /** 561 * @if Eng 562 * @brief Read data from the UART by dma. 563 * @param [in] bus The UART bus. see @ref uart_bus_t 564 * @param [in] buffer Pointer to the read buffer. 565 * @param [in] length Length of the buffer. 566 * @param [in] dma_cfg Dma configuration of UART. see @ref uart_write_dma_config_t. 567 * @return The count of data have been receive by UART. 568 * @else 569 * @brief 通过DMA读取数据。 570 * @param [in] bus 串口号，参考 @ref uart_bus_t 。 571 * @param [in] buffer 要发送的数据Buffer。 572 * @param [in] length 要发送的数据Buffer长度。 573 * @param [in] dma_cfg 接收数据时候的DMA配置，参考 @ref uart_write_dma_config_t 。 574 * @return 完成接收的数据长度。 575 * @endif 576 */ 577 int32_t uapi_uart_read_by_dma(uart_bus_t bus, const void *buffer, uint32_t length, uart_write_dma_config_t *dma_cfg); 578 579 #if defined(CONFIG_UART_SUPPORT_INT_TRIGGER_DMA) 580 /** 581 * @if Eng 582 * @brief Registers a rx interrupt trigger dma callback. 583 * @param [in] bus The UART bus. see @ref uart_bus_t. 584 * @param [in] dma_cfg Dma configuration of UART. see @ref uart_write_dma_config_t 585 * @retval ERRCODE_SUCC Success. 586 * @retval Other Failure. For details, see @ref errcode_t. 587 * @else 588 * @brief 注册中断触发DMA搬运的回调。 589 * @param [in] bus 串口号，参考 @ref uart_bus_t 。 590 * @param [in] dma_cfg 接收数据时候的DMA配置，参考 @ref uart_write_dma_config_t。 591 * @retval ERRCODE_SUCC 成功。 592 * @retval Other 失败，参考 @ref errcode_t 。 593 * @endif 594 */ 595 errcode_t uapi_uart_register_read_by_dma_callback(uart_bus_t bus, uart_write_dma_config_t *dma_cfg); 596 597 /** 598 * @if Eng 599 * @brief Unregisters a rx interrupt trigger dma callback. 600 * @param [in] bus The UART bus. see @ref uart_bus_t. 601 * @else 602 * @brief 去注册中断触发DMA搬运的回调。 603 * @param [in] bus 串口号，参考 @ref uart_bus_t。 604 * @endif 605 */ 606 void uapi_uart_unregister_read_by_dma_callback(uart_bus_t bus); 607 #endif /* CONFIG_UART_SUPPORT_INT_TRIGGER_DMA */ 608 #endif /* CONFIG_UART_SUPPORT_DMA */ 609 #endif /* CONFIG_UART_SUPPORT_TX */ 610 611 #if defined(CONFIG_UART_SUPPORT_RX) 612 /** 613 * @if Eng 614 * @brief Read data from UART. 615 * @param [in] bus The UART bus. see @ref uart_bus_t. 616 * @param [in] buffer Pointer to the read buffer. 617 * @param [in] length Amount of data to be received. 618 * @param [in] timeout Timeout duration. 619 * @return Amount of data read from UART. 620 * @else 621 * @brief 从UART读取数据。 622 * @param [in] bus 串口号，参考 @ref uart_bus_t 。 623 * @param [in] buffer 存储接收数据的Buffer。 624 * @param [in] length 存储接收数据的Buffer长度。 625 * @param [in] timeout 超时时间。 626 * @return 实际读到的数据长度。 627 * @endif 628 */ 629 int32_t uapi_uart_read(uart_bus_t bus, const uint8_t *buffer, uint32_t length, uint32_t timeout); 630 631 /** 632 * @if Eng 633 * @brief Flush all data held in the supplied UART's RX buffer. 634 * @param [in] bus The UART bus. see @ref uart_bus_t. 635 * @retval ERRCODE_SUCC Success. 636 * @retval Other Failure. For details, see @ref errcode_t. 637 * @else 638 * @brief 刷新UART接收Buffer中的数据。 639 * @param [in] bus 串口号，参考 @ref uart_bus_t 。 640 * @retval ERRCODE_SUCC 成功。 641 * @retval Other 失败，参考 @ref errcode_t 。 642 * @endif 643 */ 644 errcode_t uapi_uart_flush_rx_data(uart_bus_t bus); 645 646 /** 647 * @if Eng 648 * @brief Update UART's RX buffer address and length. 649 * @param [in] bus The UART bus. see @ref uart_bus_t. 650 * @param [in] rx_buffer buffer address. 651 * @param [in] rx_buffer_size buffer size. 652 * @retval ERRCODE_SUCC Success. 653 * @retval Other Failure. For details, see @ref errcode_t. 654 * @else 655 * @brief 更新UART接收Buffer的地址和长度。 656 * @param [in] bus 串口号，参考 @ref uart_bus_t 。 657 * @param [in] rx_buffer buffer的地址 。 658 * @param [in] rx_buffer_size buffer的长度 。 659 * @retval ERRCODE_SUCC 成功。 660 * @retval Other 失败，参考 @ref errcode_t 。 661 * @endif 662 */ 663 errcode_t uapi_uart_update_rx_buff(uart_bus_t bus, uint8_t *rx_buffer, uint16_t rx_buffer_size); 664 #endif /* CONFIG_UART_SUPPORT_RX */ 665 666 #if defined(CONFIG_UART_SUPPORT_LPM) 667 /** 668 * @if Eng 669 * @brief Suspend all of the UART channels. 670 * @param [in] arg Argument for suspend. 671 * @retval ERRCODE_SUCC Success. 672 * @retval Other Failure. For details, see @ref errcode_t. 673 * @else 674 * @brief 挂起所有的UART通道。 675 * @param [in] arg 挂起所需要的参数。 676 * @retval ERRCODE_SUCC 成功。 677 * @retval Other 失败，参考 @ref errcode_t 。 678 * @endif 679 */ 680 errcode_t uapi_uart_suspend(uintptr_t arg); 681 682 /** 683 * @if Eng 684 * @brief Resume all of the UART channels. 685 * @param [in] arg Argument for resume. 686 * @retval ERRCODE_SUCC Success. 687 * @retval Other Failure. For details, see @ref errcode_t. 688 * @else 689 * @brief 恢复所有的UART通道。 690 * @param [in] arg 恢复所需要的参数。 691 * @retval ERRCODE_SUCC 成功。 692 * @retval Other 失败，参考 @ref errcode_t 。 693 * @endif 694 */ 695 errcode_t uapi_uart_resume(uintptr_t arg); 696 #endif /* CONFIG_UART_SUPPORT_LPM */ 697 698 /** 699 * @} 700 */ 701 702 #ifdef __cplusplus 703 #if __cplusplus 704 } 705 #endif /* __cplusplus */ 706 #endif /* __cplusplus */ 707 708 #endif