1# UART 2 3## 概述 4 5### 功能简介 6 7UART指异步收发传输器（Universal Asynchronous Receiver/Transmitter），是通用串行数据总线，用于异步通信。该总线双向通信，可以实现全双工传输。 8 9两个UART设备的连接示意图如下，UART与其他模块一般用2线（图1）或4线（图2）相连，它们分别是： 10 11 - TX：发送数据端，和对端的RX相连。 12 - RX：接收数据端，和对端的TX相连。 13 - RTS：发送请求信号，用于指示本设备是否准备好，可接受数据，和对端CTS相连。 14 - CTS：允许发送信号，用于判断是否可以向对端发送数据，和对端RTS相连。 15 16**图1** 2线UART设备连接示意图 17 18 19 20**图2** 4线UART设备连接示意图 21 22 23 24UART通信之前，收发双方需要约定好一些参数：波特率、数据格式（起始位、数据位、校验位、停止位）等。通信过程中，UART通过TX发送给对端数据，通过RX接收对端发送的数据。当UART接收缓存达到预定的门限值时，RTS变为不可发送数据，对端的CTS检测到不可发送数据，则停止发送数据。 25 26UART接口定义了操作UART端口的通用方法集合，包括： 27 28- 打开/关闭UART设备 29- 读写数据 30- 设置/获取UART设备波特率 31- 设置/获取UART设备属性 32 33### 基本概念 34 35- 异步通信 36 37 异步通信中，数据通常以字符或者字节为单位组成字符帧传送。字符帧由发送端逐帧发送，通过传输线被接收设备逐帧接收。发送端和接收端可以由各自的时钟来控制数据的发送和接收，这两个时钟源彼此独立，互不同步。异步通信以一个字符为传输单位，通信中两个字符间的时间间隔是不固定的，然而在同一个字符中的两个相邻位代码间的时间间隔是固定的。 38 39- 全双工传输（Full Duplex） 40 41 此通信模式允许数据在两个方向上同时传输，它在能力上相当于两个单工通信方式的结合。全双工可以同时进行信号的双向传输。 42 43### 运作机制 44 45在HDF框架中，UART接口适配模式采用独立服务模式（如图3所示）。在这种模式下，每一个设备对象会独立发布一个设备服务来处理外部访问，设备管理器收到API的访问请求之后，通过提取该请求的参数，达到调用实际设备对象的相应内部方法的目的。独立服务模式可以直接借助HDF设备管理器的服务管理能力，但需要为每个设备单独配置设备节点，增加内存占用。 46 47独立服务模式下，核心层不会统一发布一个服务供上层使用，因此这种模式下驱动要为每个控制器发布一个服务，具体表现为： 48 49- 驱动适配者需要实现HdfDriverEntry的Bind钩子函数以绑定服务。 50- device_info.hcs文件中deviceNode的policy字段为1或2，不能为0。 51 52UART模块各分层作用： 53 54- 接口层提供打开UART设备、UART设备读取指定长度数据、UART设备写入指定长度数据、设置UART设备波特率、获取设UART设备波特率、设置UART设备属性、获取UART设备波特率、设置UART设备传输模式、关闭UART设备的接口。 55- 核心层主要提供看UART控制器的创建、移除以及管理的能力，通过钩子函数与适配层交互。 56- 适配层主要是将钩子函数的功能实例化，实现具体的功能。 57 58**图3** UART独立服务模式结构图 59 60 61 62## 使用指导 63 64### 场景介绍 65 66UART模块应用比较广泛，主要用于实现设备之间的低速串行通信，例如输出打印信息，当然也可以外接各种模块，如GPS、蓝牙等。 67 68### 接口说明 69 70**表1** UART驱动API接口功能介绍 71 72| 接口名 | 接口描述 | 73| -------- | -------- | 74| DevHandle UartOpen(uint32_t port) | UART获取设备句柄 | 75| void UartClose(DevHandle handle) | UART释放设备句柄 | 76| int32_t UartRead(DevHandle handle, uint8_t *data, uint32_t size) | 从UART设备中读取指定长度的数据 | 77| int32_t UartWrite(DevHandle handle, uint8_t *data, uint32_t size) | 向UART设备中写入指定长度的数据 | 78| int32_t UartGetBaud(DevHandle handle, uint32_t *baudRate) | UART获取波特率 | 79| int32_t UartSetBaud(DevHandle handle, uint32_t baudRate) | UART设置波特率 | 80| int32_t UartGetAttribute(DevHandle handle, struct UartAttribute *attribute) | UART获取设备属性 | 81| int32_t UartSetAttribute(DevHandle handle, struct UartAttribute *attribute) | UART设置设备属性 | 82| int32_t UartSetTransMode(DevHandle handle, enum UartTransMode mode) | UART设置传输模式 | 83 84>  **说明：**<br> 85> 本文涉及的UART所有接口，支持内核态及用户态使用。 86 87### 开发步骤 88 89使用UART的一般流程如下图所示。 90 91**图3** UART使用流程图 92 93 94 95 96#### 获取UART设备句柄 97 98在使用UART进行通信时，首先要调用UartOpen获取UART设备句柄，该函数会返回指定端口号的UART设备句柄。 99 100```c 101DevHandle UartOpen(uint32_t port); 102``` 103 104**表2** UartOpen参数和返回值描述 105 106| 参数 | 参数描述 | 107| -------- | -------- | 108| port | UART设备号 | 109| **返回值** | **返回值描述** | 110| NULL | 获取UART设备句柄失败 | 111| 设备句柄 | UART设备句柄 | 112 113假设系统中的UART端口号为1，获取该UART设备句柄的示例如下： 114 115```c 116DevHandle handle = NULL; // UART设备句柄 117uint32_t port = 1; // UART设备端口号 118 119handle = UartOpen(port); 120if (handle == NULL) { 121 HDF_LOGE("UartOpen: open uart_%u failed!\n", port); 122 return; 123} 124``` 125 126#### UART设置波特率 127 128在通信之前，需要设置UART的波特率，设置波特率的函数如下所示： 129 130```c 131int32_t UartSetBaud(DevHandle handle, uint32_t baudRate); 132``` 133 134**表3** UartSetBaud参数和返回值描述 135 136| 参数 | 参数描述 | 137| -------- | -------- | 138| handle | UART设备句柄 | 139| baudRate | 待设置的波特率值 | 140| **返回值** | **返回值描述** | 141| HDF_SUCCESS | UART设置波特率成功 | 142| 负数 | UART设置波特率失败 | 143 144假设需要设置的UART波特率为9600，设置波特率的实例如下： 145 146```c 147int32_t ret; 148 149ret = UartSetBaud(handle, 9600); // 设置UART波特率 150if (ret != HDF_SUCCESS) { 151 HDF_LOGE("UartSetBaud: failed, ret %d\n", ret); 152 return ret; 153} 154``` 155 156#### UART获取波特率 157 158设置UART的波特率后，可以通过获取波特率接口来查看UART当前的波特率，获取波特率的函数如下所示： 159 160```c 161int32_t UartGetBaud(DevHandle handle, uint32_t *baudRate); 162``` 163 164**表4** UartGetBaud参数和返回值描述 165 166| 参数 | 参数描述 | 167| -------- | -------- | 168| handle | UART设备句柄 | 169| baudRate | 接收波特率值的指针 | 170| **返回值** | **返回值描述** | 171| HDF_SUCCESS | UART获取波特率成功 | 172| 负数 | UART获取波特率失败 | 173 174获取波特率的实例如下： 175 176```c 177int32_t ret; 178uint32_t baudRate; 179 180ret = UartGetBaud(handle, &baudRate); // 获取UART波特率 181if (ret != HDF_SUCCESS) { 182 HDF_LOGE("UartGetBaud: failed, ret %d\n", ret); 183 return ret; 184} 185``` 186 187#### UART设置设备属性 188 189在通信之前，需要设置UART的设备属性，设置设备属性的函数如下所示： 190 191```c 192int32_t UartSetAttribute(DevHandle handle, struct UartAttribute *attribute); 193``` 194 195**表5** UartSetAttribute参数和返回值描述 196 197| 参数 | 参数描述 | 198| -------- | -------- | 199| handle | UART设备句柄 | 200| attribute | 待设置的设备属性 | 201| **返回值** | **返回值描述** | 202| HDF_SUCCESS | UART设置设备属性成功 | 203| 负数 | UART设置设备属性失败 | 204 205设置UART的设备属性的实例如下： 206 207```c 208int32_t ret; 209struct UartAttribute attribute; 210 211attribute.dataBits = UART_ATTR_DATABIT_7; // UART传输数据位宽，一次传输7个bit 212attribute.parity = UART_ATTR_PARITY_NONE; // UART传输数据无校检 213attribute.stopBits = UART_ATTR_STOPBIT_1; // UART传输数据停止位为1位 214attribute.rts = UART_ATTR_RTS_DIS; // UART禁用RTS 215attribute.cts = UART_ATTR_CTS_DIS; // UART禁用CTS 216attribute.fifoRxEn = UART_ATTR_RX_FIFO_EN; // UART使能RX FIFO 217attribute.fifoTxEn = UART_ATTR_TX_FIFO_EN; // UART使能TX FIFO 218 219ret = UartSetAttribute(handle, &attribute); // 设置UART设备属性 220if (ret != HDF_SUCCESS) { 221 HDF_LOGE("UartSetAttribute: failed, ret %d\n", ret); 222turn ret; 223} 224``` 225 226#### UART获取设备属性 227 228设置UART的设备属性后，可以通过获取设备属性接口来查看UART当前的设备属性，获取设备属性的函数如下所示： 229 230```c 231int32_t UartGetAttribute(DevHandle handle, struct UartAttribute *attribute); 232``` 233 234**表6** UartGetAttribute参数和返回值描述 235 236| 参数 | 参数描述 | 237| -------- | -------- | 238| handle | UART设备句柄 | 239| attribute | 接收UART设备属性的指针 | 240| **返回值** | **返回值描述** | 241| HDF_SUCCESS | UART获取设备属性成功 | 242| 负数 | UART获取设备属性失败 | 243 244获取UART的设备属性的实例如下： 245 246```c 247int32_t ret; 248struct UartAttribute attribute; 249 250ret = UartGetAttribute(handle, &attribute); // 获取UART设备属性 251if (ret != HDF_SUCCESS) { 252 HDF_LOGE("UartGetAttribute: failed, ret %d\n", ret); 253 return ret; 254} 255``` 256 257#### 设置UART传输模式 258 259在通信之前，需要设置UART的传输模式，设置传输模式的函数如下所示： 260 261```c 262int32_t UartSetTransMode(DevHandle handle, enum UartTransMode mode); 263``` 264 265**表7** UartSetTransMode参数和返回值描述 266 267| 参数 | 参数描述 | 268| -------- | -------- | 269| handle | UART设备句柄 | 270| mode | 待设置的传输模式， | 271| **返回值** | **返回值描述** | 272| HDF_SUCCESS | UART设置传输模式成功 | 273| 负数 | UART设置传输模式失败 | 274 275假设需要设置的UART传输模式为UART_MODE_RD_BLOCK，设置传输模式的实例如下： 276 277```c 278int32_t ret; 279 280ret = UartSetTransMode(handle, UART_MODE_RD_BLOCK); // 设置UART传输模式 281if (ret != HDF_SUCCESS) { 282 HDF_LOGE("UartSetTransMode: failed, ret %d\n", ret); 283 return ret; 284} 285``` 286 287#### 向UART设备写入指定长度的数据 288 289对应的接口函数如下所示： 290 291```c 292int32_t UartWrite(DevHandle handle, uint8_t *data, uint32_t size); 293``` 294 295**表8** UartWrite参数和返回值描述 296 297| 参数 | 参数描述 | 298| -------- | -------- | 299| handle | UART设备句柄 | 300| data | 待写入数据的指针 | 301| size | 待写入数据的长度 | 302| **返回值** | **返回值描述** | 303| HDF_SUCCESS | UART写数据成功 | 304| 负数 | UART写数据失败 | 305 306写入指定长度数据的实例如下： 307 308```c 309int32_t ret; 310uint8_t wbuff[5] = {1, 2, 3, 4, 5}; 311 312ret = UartWrite(handle, wbuff, 5); // 向UART设备写入指定长度的数据 313if (ret != HDF_SUCCESS) { 314 HDF_LOGE("UartWrite: failed, ret %d\n", ret); 315 return ret; 316} 317``` 318 319#### 从UART设备中读取指定长度的数据 320 321对应的接口函数如下所示： 322 323```c 324int32_t UartRead(DevHandle handle, uint8_t *data, uint32_t size); 325``` 326 327**表9** UartRead参数和返回值描述 328 329| 参数 | 参数描述 | 330| -------- | -------- | 331| handle | UART设备句柄 | 332| data | 接收读取数据的指针 | 333| size | 待读取数据的长度 | 334| **返回值** | **返回值描述** | 335| 非负数 | UART读取到的数据长度 | 336| 负数 | UART读取数据失败 | 337 338读取指定长度数据的实例如下： 339 340```c 341int32_t ret; 342uint8_t rbuff[5] = {0}; 343 344ret = UartRead(handle, rbuff, 5); // 从UART设备读取指定长度的数据 345if (ret < 0) { 346 HDF_LOGE("UartRead: failed, ret %d\n", ret); 347 return ret; 348} 349``` 350 351>  **注意：** 352> UART返回值为非负值，表示UART读取成功。若返回值等于0，表示UART无有效数据可以读取。若返回值大于0，表示实际读取到的数据长度，该长度小于或等于传入的参数size的大小，并且不超过当前正在使用的UART控制器规定的最大单次读取数据长度的值。 353 354 355#### 销毁UART设备句柄 356 357UART通信完成之后，需要销毁UART设备句柄，函数如下所示： 358 359```c 360void UartClose(DevHandle handle); 361``` 362 363该函数会释放申请的资源。 364 365**表10** UartClose参数和返回值描述 366 367| 参数 | 参数描述 | 368| -------- | -------- | 369| handle | UART设备句柄 | 370 371销毁UART设备句柄的实例如下： 372 373```c 374UartClose(handle); // 销毁UART设备句柄 375``` 376 377## 使用实例 378 379下面将基于Hi3516DV300开发板展示使用UART完整操作，步骤主要如下： 380 3811. 传入UART端口号num，打开端口号对应的UART设备并获得UART设备句柄。 3822. 通过UART设备句柄及设置的波特率，设置UART设备的波特率。 3833. 通过UART设备句柄及待获取的波特率，获取UART设备的波特率。 3844. 通过UART设备句柄及待设置的设备属性，设置UART设备的设备属性。 3855. 通过UART设备句柄及待获取的设备属性，获取UART设备的设备属性。 3866. 通过UART设备句柄及待设置的传输模式，设置UART设备的传输模式。 3877. 通过UART设备句柄及待传输的数据及大小，传输指定长度的数据。 3888. 通过UART设备句柄及待接收的数据及大小，接收指定长度的数据。 3899. 通过UART设备句柄，关闭UART设备。 390 391```c 392#include "hdf_log.h" 393#include "uart_if.h" 394 395void UartTestSample(void) 396{ 397 int32_t ret; 398 uint32_t port; 399 uint32_t baud; 400 DevHandle handle = NULL; 401 uint8_t wbuff[5] = { 1, 2, 3, 4, 5 }; 402 uint8_t rbuff[5] = { 0 }; 403 struct UartAttribute attribute; 404 405 attribute.dataBits = UART_ATTR_DATABIT_7; // UART传输数据位宽，一次传输7个bit 406 attribute.parity = UART_ATTR_PARITY_NONE; // UART传输数据无校检 407 attribute.stopBits = UART_ATTR_STOPBIT_1; // UART传输数据停止位为1位 408 attribute.rts = UART_ATTR_RTS_DIS; // UART禁用RTS 409 attribute.cts = UART_ATTR_CTS_DIS; // UART禁用CTS 410 attribute.fifoRxEn = UART_ATTR_RX_FIFO_EN; // UART使能RX FIFO 411 attribute.fifoTxEn = UART_ATTR_TX_FIFO_EN; // UART使能TX FIFO 412 413 port = 1; // UART设备端口号，要填写实际平台上的端口号 414 415 handle = UartOpen(port); // 获取UART设备句柄 416 if (handle == NULL) { 417 HDF_LOGE("UartOpen: open uart_%u failed!\n", port); 418 return; 419 } 420 421 ret = UartSetBaud(handle, 9600); // 设置UART波特率为9600 422 if (ret != HDF_SUCCESS) { 423 HDF_LOGE("UartSetBaud: set baud failed, ret %d\n", ret); 424 goto ERR; 425 } 426 427 ret = UartGetBaud(handle, &baud); // 获取UART波特率 428 if (ret != HDF_SUCCESS) { 429 HDF_LOGE("UartGetBaud: get baud failed, ret %d\n", ret); 430 goto ERR; 431 } 432 433 ret = UartSetAttribute(handle, &attribute); // 设置UART设备属性 434 if (ret != HDF_SUCCESS) { 435 HDF_LOGE("UartSetAttribute: set attribute failed, ret %d\n", ret); 436 goto ERR; 437 } 438 439 ret = UartGetAttribute(handle, &attribute); // 获取UART设备属性 440 if (ret != HDF_SUCCESS) { 441 HDF_LOGE("UartGetAttribute: get attribute failed, ret %d\n", ret); 442 goto ERR; 443 } 444 445 ret = UartSetTransMode(handle, UART_MODE_RD_NONBLOCK); // 设置UART传输模式为非阻塞模式 446 if (ret != HDF_SUCCESS) { 447 HDF_LOGE("UartSetTransMode: set trans mode failed, ret %d\n", ret); 448 goto ERR; 449 } 450 451 ret = UartWrite(handle, wbuff, 5); // 向UART设备写入5字节的数据 452 if (ret != HDF_SUCCESS) { 453 HDF_LOGE("UartWrite: write data failed, ret %d\n", ret); 454 goto ERR; 455 } 456 457 ret = UartRead(handle, rbuff, 5); // 从UART设备读取5字节的数据 458 if (ret < 0) { 459 HDF_LOGE("UartRead: read data failed, ret %d\n", ret); 460 goto ERR; 461 } 462ERR: 463 UartClose(handle); // 销毁UART设备句柄 464 return ret; 465} 466``` 467
