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