1 /** 2 * @file hi_uart.h 3 * 4 * Copyright (c) 2020 HiSilicon (Shanghai) Technologies CO., LIMITED. 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 * 17 * Description: UART Port APIs. \n 18 */ 19 /** @defgroup iot_uart UART Port 20 * @ingroup drivers 21 */ 22 #ifndef __HI_UART_H__ 23 #define __HI_UART_H__ 24 25 #include <hi_types.h> 26 #include "hi_mdm_types.h" 27 28 #ifdef __cplusplus 29 extern "C" { 30 #endif 31 32 /** 33 * @ingroup iot_uart 34 * 35 * UART serial number. CNcomment:UART序号。CNend 36 */ 37 typedef enum { 38 HI_UART_IDX_0, /**< Physical port number 0.CNcomment:物理端口号0 CNend */ 39 HI_UART_IDX_1, /**< Physical port number 1.CNcomment:物理端口号1 CNend */ 40 HI_UART_IDX_2, /**< Physical port number 2.CNcomment:物理端口号2 CNend */ 41 HI_UART_IDX_MAX /**< Maximum physical port number, which cannot be used. CNcomment:物理端口号最大值， 42 不可使用CNend */ 43 } hi_uart_idx; 44 45 /** 46 * @ingroup iot_uart 47 * 48 * UART data bit. CNcomment:UART数据位。CNend 49 */ 50 typedef enum { 51 HI_UART_DATA_BIT_5 = 5, /**< Data bit: support option 5bit.CNcomment:数据位：支持配置5bit.CNend */ 52 HI_UART_DATA_BIT_6, /**< Data bit: support option 6bit.CNcomment:数据位：支持配置6bit.CNend */ 53 HI_UART_DATA_BIT_7, /**< Data bit: support option 7bit.CNcomment:数据位：支持配置7bit.CNend */ 54 HI_UART_DATA_BIT_8, /**< Data bit: support option 8bit.CNcomment:数据位：支持配置8bit.CNend */ 55 } hi_uart_data_bit; 56 57 /** 58 * @ingroup iot_uart 59 * 60 * UART stop bit. CNcomment:UART停止位。CNend 61 */ 62 typedef enum { 63 HI_UART_STOP_BIT_1 = 1, /**< Stop bit, 1bit.CNcomment:停止位，1bit停止位.CNend */ 64 HI_UART_STOP_BIT_2 = 2, /**< Stop bit, 2bit.CNcomment:停止位，2bit停止位.CNend */ 65 } hi_uart_stop_bit; 66 67 /** 68 * @ingroup iot_uart 69 * 70 * UART parity bit. CNcomment:UART校验位。CNend 71 */ 72 typedef enum { 73 HI_UART_PARITY_NONE = 0, /**< Parity bit, None. CNcomment:校验位，无校验CNend */ 74 HI_UART_PARITY_ODD = 1, /**< Parity bit, odd. CNcomment:校验位，奇校验CNend */ 75 HI_UART_PARITY_EVEN = 2, /**< Parity bit, even. CNcomment:校验位，偶校验CNend */ 76 } hi_uart_parity; 77 78 /** 79 * @ingroup iot_uart 80 * 81 * UART FIFO interruption limitation. CNcomment:UART FIFO中断门限。CNend 82 */ 83 typedef enum { 84 HI_FIFO_LINE_ONE_EIGHT = 1, /**< FIFO interruption limitation, FIFO LINE = 1/8full. 85 CNcomment:FIFO中断门限，FIFO LINE = 1/8full CNend */ 86 HI_FIFO_LINE_ONE_QUARTER, /**< FIFO interruption limitation, FIFO LINE = 1/4full. 87 CNcomment:FIFO中断门限，FIFO LINE = 1/4full CNend */ 88 HI_FIFO_LINE_HALF, /**< FIFO interruption limitation, FIFO LINE = 1/2full. 89 CNcomment:FIFO中断门限，FIFO LINE = 1/2full CNend */ 90 HI_FIFO_LINE_THREE_QUARTERS, /**< FIFO interruption limitation, FIFO LINE = 3/4full. 91 CNcomment:FIFO中断门限，FIFO LINE = 3/4full CNend */ 92 HI_FIFO_LINE_SEVEN_EIGHTS, /**< FIFO interruption limitation, FIFO LINE = 7/8full. 93 CNcomment:FIFO中断门限，FIFO LINE = 7/8full CNend */ 94 } hi_uart_fifo_line; 95 96 /** 97 * @ingroup iot_uart 98 * 99 * UART block mode. CNcomment:UART 阻塞模式。CNend 100 */ 101 typedef enum { 102 HI_UART_BLOCK_STATE_NONE_BLOCK = 1, /**< block mode, none-block. CNcomment:UART阻塞模式，非阻塞传输 CNend */ 103 HI_UART_BLOCK_STATE_BLOCK, /**< block mode, block. CNcomment:UART阻塞模式，阻塞传输 CNend */ 104 } hi_uart_block_state; 105 106 /** 107 * @ingroup iot_uart 108 * 109 * UART DMA transmation mode. CNcomment:UART DMA传输模式。CNend 110 */ 111 typedef enum { 112 HI_UART_NONE_DMA = 1, /**< None-DMA mode. CNcomment:DMA传输，不使用DMA CNend */ 113 HI_UART_USE_DMA, /**< DMA mode. CNcomment:DMA传输，使用DMA CNend */ 114 } hi_uart_dma_state; 115 116 /** 117 * @ingroup iot_uart 118 * 119 * UART hardware flow control mode. CNcomment:UART 硬件流控控制模式。CNend 120 */ 121 typedef enum { 122 HI_FLOW_CTRL_NONE, /**< hardware flow ctrl: disable flow ctrl.CNcomment:不使用。CNend */ 123 HI_FLOW_CTRL_RTS_CTS, /**< hardware flow ctrl: enable rts and cts.CNcomment:使用RTS和CTS CNend */ 124 HI_FLOW_CTRL_RTS_ONLY, /**< hardware flow ctrl: enable rts only.CNcomment:只使用RTS CNend */ 125 HI_FLOW_CTRL_CTS_ONLY, /**< hardware flow ctrl: enable cts only.CNcomment:只使用CTS CNend */ 126 } hi_flow_ctrl; 127 128 /** 129 * @ingroup iot_uart 130 * 131 * UART basic settings. CNcomment:UART端口基本配置参数。CNend 132 */ 133 typedef struct { 134 hi_u32 baud_rate; /**< Baud Rate.CNcomment:波特率。CNend */ 135 hi_u8 data_bits; /**< Data bit. CNcomment:数据位。CNend */ 136 hi_u8 stop_bits; /**< Stop bit. CNcomment:停止位。CNend */ 137 hi_u8 parity; /**< Parity check flag. CNcomment:奇偶校验位。CNend */ 138 hi_u8 pad; /**< reserved pad */ 139 } hi_uart_attribute; 140 141 /** 142 * @ingroup iot_uart 143 * 144 * UART extra attributes.CNcomment:UART端口额外参数配置。CNend 145 */ 146 typedef struct { 147 hi_uart_fifo_line tx_fifo_line; 148 hi_uart_fifo_line rx_fifo_line; 149 hi_uart_fifo_line flow_fifo_line; 150 hi_uart_block_state tx_block; 151 hi_uart_block_state rx_block; 152 hi_u16 tx_buf_size; 153 hi_u16 rx_buf_size; 154 hi_uart_dma_state tx_use_dma; 155 hi_uart_dma_state rx_use_dma; 156 } hi_uart_extra_attr; 157 158 /** 159 * @ingroup iot_uart 160 * @brief UART initialization. CNcomment:UART初始化。CNend 161 * 162 * @par 描述: 163 * Set UART with configuration. CNcomment:根据参数配置指定UART。CNend 164 * 165 * @attention 1.If extra_attr is set to HI_NULL, all optimization parameters of the notification driver use the default 166 * values.CNcomment:extra_attr为HI_NULL表示通知驱动所有优化参数使用默认值；CNend 167 * 2.If the value of the member parameter in extra_attr is 0, it indicates that the member parameter 168 * is notified to the driver. The member parameter uses the default value. 169 * CNcomment:extra_attr中成员参数值为0表示通知驱动该成员参数使用默认值；CNend 170 * 3.After the UART initialization is complete, if you want to change the UART optimization parameter 171 * configuration, you need to call hi_uart_deinit to deinitialize the UART before calling hi_uart_init 172 * to change the optimization parameter configuration. CNcomment:UART初始化完成后，若要变更UART 173 优化参数配置，需先调用hi_uart_deinit去初始化UART，再调用hi_uart_init变更优化参数配置。CNend 174 * 175 * @param id [IN] type #hi_uart_idx，UART port id. CNcomment:UART端口号。CNend 176 * @param param [IN] type #const hi_uart_attribute*，UART base settings.CNcomment:UART基本参数。CNend 177 * @param extra_attr [IN] type #const hi_uart_extra_attr*，UART extra settings. CNcomment:UART优化参数。CNend 178 * 179 * @retval #HI_ERR_SUCCESS Success. 180 * @retval #HI_ERR_FAILURE Failure. 181 * @par 依赖: 182 * @li hi_uart.h：Describes UART APIs.CNcomment:UART相关接口。CNend 183 * @see hi_uart_deinit。 184 */ 185 hi_u32 hi_uart_init(hi_uart_idx id, const hi_uart_attribute *param, const hi_uart_extra_attr *extra_attr); 186 187 /** 188 * @ingroup iot_uart 189 * @brief Reads data.CNcomment:读数据。CNend 190 * 191 * @par 描述: 192 * Reads the data received by the UART. CNcomment:将UART接收到的数据读取出来。CNend 193 * 194 * @attention This API must be used after the hi_uart_open function is called. 195 CNcomment:须在调用完hi_uart_init函数之后使用。CNend 196 * @param id [IN] type #hi_uart_idx，UART port id. CNcomment:UART端口号。CNend 197 * @param data [OUT] type #hi_u8*，Start address of the data to be read.CNcomment:读到数据的首地址。CNend 198 * @param data_len [IN] type #hi_u32，Number of bytes to be read.CNcomment:要读取数据的字节数。CNend 199 * 200 * @retval #>=0 Number of bytes that are actually read.CNcomment:实际读到数据的字节数。CNend 201 * @retval #HI_ERR_FAILURE Data read error.CNcomment:读数据失败。CNend 202 * @par 依赖: 203 * @li hi_uart.h：Describes UART APIs.CNcomment:UART相关接口。CNend 204 * @see hi_uart_write。 205 */ 206 hi_s32 hi_uart_read(hi_uart_idx id, hi_u8 *data, hi_u32 data_len); 207 208 /** 209 * @ingroup iot_uart 210 * @brief Reads data in specified timeout time.CNomment:在指定超时时间内读取数据。CNend 211 * 212 * @par 描述: 213 * Reads data in specified timeout time.CNomment:在指定超时时间内读取数据。CNend 214 * if Reads all data before timeout, function will return. 215 CNomment:超时前读取完成所有数据后，函数会立即返回。CNend 216 * 217 * @attention This API must be used after the hi_uart_open function is called. 218 CNcomment:须在调用完hi_uart_init函数之后使用。CNend 219 * @param id [IN] type #hi_uart_idx，UART port id. CNcomment:UART端口号。CNend 220 * @param data [OUT] type #hi_u8*，Start address of the data to be read.CNcomment:读到数据的首地址。CNend 221 * @param data_len [IN] type #hi_u32，Number of bytes to be read.CNcomment:要读取数据的字节数。CNend 222 * @param timeout_ms [IN] type #hi_u32，timeout.CNcomment:超时时间。CNend 223 * 224 * @retval #>=0 Number of bytes that are actually read.CNcomment:实际读到数据的字节数。CNend 225 * @retval #HI_ERR_FAILURE Data read error.CNcomment:读数据失败。CNend 226 * @par 依赖: 227 * @li hi_uart.h：Describes UART APIs.CNcomment:UART相关接口。CNend 228 * @see hi_uart_write。 229 */ 230 hi_s32 hi_uart_read_timeout(hi_uart_idx id, hi_u8 *data, hi_u32 len, hi_u32 timeout_ms); 231 232 /** 233 * @ingroup iot_uart 234 * @brief Writes data.CNcomment:写数据。CNend 235 * 236 * @par 描述: 237 * Writes the data to be sent to the UART. The block mode is used by default. 238 CNcomment:将待发送的数据写到UART。CNend 239 * 240 * @attention This API must be used after the hi_uart_init function is called. 241 CNcomment:须在调用完hi_uart_init函数之后使用。CNend 242 * @param id [IN] type #hi_uart_idx，UART port id. CNcomment:UART端口号。CNend 243 * @param data [IN] type #const hi_u8*，Start address of the data to be written.CNcomment:待写数据的首地址。CNend 244 * @param data_len [IN] type #hi_u32，Number of bytes to be written.CNcomment:待写数据的字节数。CNend 245 * 246 * @retval #>=0 Number of bytes to be sent.CNcomment:实际发送数据的字节数。CNend 247 * @retval #HI_ERR_FAILURE Data send failure. CNcomment:发送数据失败。CNend 248 * @par 依赖: 249 * @li hi_uart.h：Describes UART APIs.CNcomment:UART相关接口。CNend 250 * @see hi_uart_read。 251 */ 252 hi_s32 hi_uart_write(hi_uart_idx id, const hi_u8 *data, hi_u32 data_len); 253 254 /** 255 * @ingroup iot_uart 256 * @brief Deinitializes UART.CNcomment:去初始化UART。CNend 257 * 258 * @par 描述: 259 * Deinitializes UART.CNcomment:去初始化UART。CNend 260 * 261 * @attention This API is used together with hi_uart_init.CNcomment:与hi_uart_init成对使用。CNend 262 * @param id [IN] type #hi_uart_idx，UART port id. CNcomment:UART端口号。CNend 263 * 264 * @retval #HI_ERR_SUCCESS Success. 265 * @retval #Other Failure. For details, see hi_errno.h. 266 * @par 依赖: 267 * @li hi_uart.h：Describes UART APIs.CNcomment:UART相关接口。CNend 268 * @see hi_uart_init。 269 */ 270 hi_u32 hi_uart_deinit(hi_uart_idx id); 271 272 /** 273 * @ingroup iot_uart 274 * @brief Set UART hardware flow control.CNcomment:配置UART硬件流控功能。CNend 275 * 276 * @par 描述: 277 * Set UART hardware flow control.CNcomment:配置UART硬件流控功能。CNend 278 * 279 * @attention This API must be used after the hi_uart_init function is called. UART0 doesn't support flow control. 280 CNcomment:须在调用完hi_uart_init函数之后使用;UART0不支持流控功能。CNend 281 * 282 * @param id [IN] type #hi_uart_idx，UART port id. CNcomment:UART端口号。CNend 283 * @param flow_ctrl [IN] type #hi_flow_ctrl，haredware flow control mode. 284 CNcomment:硬件流控功能控制模式。CNend 285 * 286 * @retval #HI_ERR_SUCCESS Success. 287 * @retval #Other Failure. For details, see hi_errno.h. 288 * @par 依赖: 289 * @li hi_uart.h：Describes UART APIs.CNcomment:UART相关接口。CNend 290 * @see 无。 291 */ 292 hi_u32 hi_uart_set_flow_ctrl(hi_uart_idx id, hi_flow_ctrl flow_ctrl); 293 294 /** 295 * @ingroup iot_uart 296 * @brief Write data by polling. CNcomment:轮询写数据。CNend 297 * 298 * @par 描述: 299 * Write data by polling. CNcomment:通过轮询的方式将待发送的数据写到UART。CNend 300 * 301 * @attention This API must be used after the hi_uart_init function is called. 302 CNcomment:须在调用完hi_uart_init函数之后使用。CNend 303 * 304 * @param id [IN] type #hi_uart_idx，UART port id. CNcomment:UART端口号。CNend 305 * @param data [IN] type #const hi_u8*，Start address of the data to be written.CNcomment:待写数据的首地址。CNend 306 * @param data_len [IN] type #hi_u32，Number of bytes to be written.CNcomment:待写数据的字节数。CNend 307 * 308 * @retval #>=0 Number of bytes to be sent.CNcomment:实际发送数据的字节数。CNend 309 * @retval #HI_ERR_FAILURE Data send failure. CNcomment:发送数据失败。CNend 310 * @par 依赖: 311 * @li hi_uart.h：Describes UART APIs.CNcomment:UART相关接口。CNend 312 * @see None 313 */ 314 hi_s32 hi_uart_write_immediately(hi_uart_idx id, const hi_u8 *data, hi_u32 data_len); 315 316 /** 317 * @ingroup iot_uart 318 * @brief Obtains UART settings. CNcomment:获取UART配置参数。CNend 319 * 320 * @par 描述: 321 * Obtains UART settings. CNcomment:获取指定UART当前配置参数。CNend 322 * 323 * @attention If extra_attr is HI_NULL, the current UART optimization parameters are not requested. This parameter 324 * must be used after the hi_uart_init function is invoked.CNcomment:extra_attr为HI_NULL表示不请求 325 当前UART的优化参数;须在调用完hi_uart_init函数之后使用。CNend 326 * 327 * @param id [IN] type #hi_uart_idx，UART port id. CNcomment:UART端口号。CNend 328 * @param attr [OUT] type #hi_uart_attribute*，UART base settings.CNcomment:UART基本参数。CNend 329 * @param extra_attr [OUT] type #hi_uart_extra_attr*，UART extra settings. CNcomment:UART优化参数。CNend 330 * 331 * @retval #HI_ERR_SUCCESS Success. 332 * @retval #HI_ERR_FAILURE Failure. 333 * @par 依赖: 334 * @li hi_uart.h：Describes UART APIs.CNcomment:UART相关接口。CNend 335 * @see hi_uart_init。 336 */ 337 hi_u32 hi_uart_get_attribute(hi_uart_idx id, hi_uart_attribute *attr, hi_uart_extra_attr *extra_attr); 338 339 /** 340 * @ingroup iot_uart 341 * @brief Determine FIFO and soft buf is empty. CNcomment:判断FIFO与软件BUF是否为空。CNend 342 * 343 * @par 描述: 344 * Determine FIFO and soft buf is empty. CNcomment:判断指定UART的FIFO与软件BUF是否为空。CNend 345 * 346 * @attention This API must be used after the hi_uart_init function is called. 347 CNcomment:须在调用完hi_uart_init函数之后使用。CNend 348 * 349 * @param id [IN] type #hi_uart_idx，UART port id. CNcomment:UART端口号。CNend 350 * @param empty [OUT] type #hi_bool*，Store query result, HI_TRUE means empty, HI_FALSE means non-empty. 351 CNcomment:存储查询结果，如果为HI_TRUE代表FIFO与软件BUF都为空，如果为HI_FALSE表示非空。CNend 352 * 353 * @retval #HI_ERR_SUCCESS Success. 354 * @retval #HI_ERR_FAILURE Failure. 355 * @par 依赖: 356 * @li hi_uart.h：Describes UART APIs.CNcomment:UART相关接口。CNend 357 * @see hi_uart_init。 358 */ 359 BSP_RAM_TEXT_SECTION hi_u32 hi_uart_is_buf_empty(hi_uart_idx id, hi_bool *empty); 360 361 /** 362 * @ingroup iot_uart 363 * @brief Determine UART is busy. CNcomment:判断UART是否忙。CNend 364 * 365 * @par 描述: 366 * Determine UART is busy. CNcomment:判断指定UART是否忙。CNend 367 * 368 * @attention This API must be used after the hi_uart_init function is called. 369 CNcomment:须在调用完hi_uart_init函数之后使用。CNend 370 * 371 * @param id [IN] type #hi_uart_idx，UART port id. CNcomment:UART端口号。CNend 372 * @param busy [OUT] type #hi_bool*，Store query result, HI_TRUE means busy, HI_FALSE means not busy. 373 CNcomment:存储查询结果，如果为HI_TRUE代表UART在忙，如果为HI_FALSE表示空闲。CNend 374 * 375 * @retval #HI_ERR_SUCCESS Success. 376 * @retval #HI_ERR_FAILURE Failure. 377 * @par 依赖: 378 * @li hi_uart.h：Describes UART APIs.CNcomment:UART相关接口。CNend 379 * @see hi_uart_init。 380 */ 381 BSP_RAM_TEXT_SECTION hi_u32 hi_uart_is_busy(hi_uart_idx id, hi_bool *busy); 382 383 /** 384 * @ingroup iot_uart 385 * @brief Quits Read data.CNcomment:退出阻塞读数据。CNend 386 * 387 * @par 描述: 388 * Quits Read data. CNcomment:退出阻塞读数据。CNend 389 * 390 * @attention Only apply in block read mode. 391 CNcomment:该接口仅应用在阻塞读数据模式下。CNend 392 * @param id [IN] type #hi_uart_idx，UART port id. CNcomment:UART端口号。CNend 393 * 394 * @retval #HI_ERR_SUCCESS Success. 395 * @retval #Other Failure. 396 * @par 依赖: 397 * @li hi_uart.h：Describes UART APIs.CNcomment:UART相关接口。CNend 398 * @see hi_uart_quit_read。 399 */ 400 hi_u32 hi_uart_quit_read(hi_uart_idx id); 401 402 /** 403 * @ingroup iot_uart 404 * @brief Save register-related values before going to deep sleep.CNcomment:深睡前保存相关寄存器内容。CNend 405 * 406 * @par 描述: 407 * Regs-related values are saved before entering deep sleep to facilitate sleep recovery. 408 CNcomment:深睡前保存相关寄存器内容，以便于睡醒恢复UART。CNend 409 * 410 * @attention Called before deep sleep. 411 CNcomment:在深睡前调用。CNend 412 * @param id [IN] type #hi_uart_idx，UART port id. CNcomment:UART端口号。CNend 413 * 414 * @retval #HI_ERR_SUCCESS Success. 415 * @retval #Other Failure. 416 * @par 依赖: 417 * @li hi_uart.h：Describes UART APIs.CNcomment:UART相关接口。CNend 418 * @see hi_uart_lp_save。 419 */ 420 hi_u32 hi_uart_lp_save(hi_uart_idx id); 421 422 /** 423 * @ingroup iot_uart 424 * @brief Restore register related values after deep sleep wake up.CNcomment:深睡唤醒后恢复寄存器内容。CNend 425 * 426 * @par 描述: 427 * Restore register related values after deep sleep wake up.CNcomment:深睡唤醒后恢复寄存器内容。CNend 428 * 429 * @attention Called after deep sleep wake up. 430 CNcomment:深睡唤醒后调用。CNend 431 * @param id [IN] type #hi_uart_idx，UART port id. CNcomment:UART端口号。CNend 432 * 433 * @retval #HI_ERR_SUCCESS Success. 434 * @retval #Other Failure. 435 * @par 依赖: 436 * @li hi_uart.h：Describes UART APIs.CNcomment:UART相关接口。CNend 437 * @see hi_uart_lp_restore。 438 */ 439 hi_u32 hi_uart_lp_restore(hi_uart_idx id); 440 441 #ifdef __cplusplus 442 } 443 #endif 444 445 #endif 446