# UART使用指导
- [使用流程](#section47784125013)
- [获取UART设备句柄](#section146445153110)
- [UART设置波特率](#section1862705516339)
- [UART获取波特率](#section1263651563414)
- [UART设置设备属性](#section1770091483814)
- [UART获取设备属性](#section117543316384)
- [设置UART传输模式](#section187233112369)
- [向UART设备写入指定长度的数据](#section82416423368)
- [从UART设备中读取指定长度的数据](#section192177171373)
- [销毁UART设备句柄](#section63131236354)
## 使用流程
使用UART的一般流程如[图1](#p58686354483)所示。
**图 1** UART使用流程图
## 获取UART设备句柄
在使用UART进行通信时，首先要调用UartOpen获取UART设备句柄，该函数会返回指定端口号的UART设备句柄。
DevHandle UartOpen\(uint32\_t port\);
**表 1** UartOpen参数和返回值描述
参数
|
参数描述
|
|---|
port
|
UART设备号
|
返回值
|
返回值描述
|
NULL
|
获取UART设备句柄失败
|
设备句柄
|
UART设备句柄
|
假设系统中的UART端口号为3，获取该UART设备句柄的示例如下：
```
DevHandle handle = NULL; /* UART设备句柄 */
uint32_t port = 3; /* UART设备端口号 */
handle = UartOpen(port);
if (handle == NULL) {
HDF_LOGE("UartOpen: failed!\n");
return;
}
```
## UART设置波特率
在通信之前，需要设置UART的波特率，设置波特率的函数如下所示：
int32\_t UartSetBaud\(DevHandle handle, uint32\_t baudRate\);
**表 2** UartSetBaud参数和返回值描述
参数
|
参数描述
|
|---|
handle
|
UART设备句柄
|
baudRate
|
待设置的波特率值
|
返回值
|
返回值描述
|
0
|
UART设置波特率成功
|
负数
|
UART设置波特率失败
|
假设需要设置的UART波特率为9600，设置波特率的实例如下：
```
int32_t ret;
/* 设置UART波特率 */
ret = UartSetBaud(handle, 9600);
if (ret != 0) {
HDF_LOGE("UartSetBaud: failed, ret %d\n", ret);
}
```
## UART获取波特率
设置UART的波特率后，可以通过获取波特率接口来查看UART当前的波特率，获取波特率的函数如下所示：
int32\_t UartGetBaud\(DevHandle handle, uint32\_t \*baudRate\);
**表 3** UartGetBaud参数和返回值描述
参数
|
参数描述
|
|---|
handle
|
UART设备句柄
|
baudRate
|
接收波特率值的指针
|
返回值
|
返回值描述
|
0
|
UART获取波特率成功
|
负数
|
UART获取波特率失败
|
获取波特率的实例如下：
```
int32_t ret;
uint32_t baudRate;
/* 获取UART波特率 */
ret = UartGetBaud(handle, &baudRate);
if (ret != 0) {
HDF_LOGE("UartGetBaud: failed, ret %d\n", ret);
}
```
## UART设置设备属性
在通信之前，需要设置UART的设备属性，设置设备属性的函数如下图所示：
int32\_t UartSetAttribute\(DevHandle handle, struct UartAttribute \*attribute\)；
**表 4** UartSetAttribute参数和返回值描述
参数
|
参数描述
|
|---|
handle
|
UART设备句柄
|
attribute
|
待设置的设备属性
|
返回值
|
返回值描述
|
0
|
UART设置设备属性成功
|
负数
|
UART设置设备属性失败
|
设置UART的设备属性的实例如下：
```
int32_t ret;
struct UartAttribute attribute;
attribute.dataBits = UART_ATTR_DATABIT_7; /* UART传输数据位宽，一次传输7个bit */
attribute.parity = UART_ATTR_PARITY_NONE; /* UART传输数据无校检 */
attribute.stopBits = UART_ATTR_STOPBIT_1; /* UART传输数据停止位为1位 */
attribute.rts = UART_ATTR_RTS_DIS; /* UART禁用RTS */
attribute.cts = UART_ATTR_CTS_DIS; /* UART禁用CTS */
attribute.fifoRxEn = UART_ATTR_RX_FIFO_EN; /* UART使能RX FIFO */
attribute.fifoTxEn = UART_ATTR_TX_FIFO_EN; /* UART使能TX FIFO */
/* 设置UART设备属性 */
ret = UartSetAttribute(handle, &attribute);
if (ret != 0) {
HDF_LOGE("UartSetAttribute: failed, ret %d\n", ret);
}
```
## UART获取设备属性
设置UART的设备属性后，可以通过获取设备属性接口来查看UART当前的设备属性，获取设备属性的函数如下图所示：
int32\_t UartGetAttribute\(DevHandle handle, struct UartAttribute \*attribute\);
**表 5** UartGetAttribute参数和返回值描述
参数
|
参数描述
|
|---|
handle
|
UART设备句柄
|
attribute
|
接收UART设备属性的指针
|
返回值
|
返回值描述
|
0
|
UART获取设备属性成功
|
负数
|
UART获取设备属性失败
|
获取UART的设备属性的实例如下：
```
int32_t ret;
struct UartAttribute attribute;
/* 获取UART设备属性 */
ret = UartGetAttribute(handle, &attribute);
if (ret != 0) {
HDF_LOGE("UartGetAttribute: failed, ret %d\n", ret);
}
```
## 设置UART传输模式
在通信之前，需要设置UART的传输模式，设置传输模式的函数如下图所示：
int32\_t UartSetTransMode\(DevHandle handle, enum UartTransMode mode\)；
**表 6** UartSetTransMode参数和返回值描述
参数
|
参数描述
|
|---|
handle
|
UART设备句柄
|
mode
|
待设置的传输模式，
|
返回值
|
返回值描述
|
0
|
UART设置传输模式成功
|
负数
|
UART设置传输模式失败
|
假设需要设置的UART传输模式为UART\_MODE\_RD\_BLOCK，设置传输模式的实例如下：
```
int32_t ret;
/* 设置UART传输模式 */
ret = UartSetTransMode(handle, UART_MODE_RD_BLOCK);
if (ret != 0) {
HDF_LOGE("UartSetTransMode: failed, ret %d\n", ret);
}
```
## 向UART设备写入指定长度的数据
对应的接口函数如下所示：
int32\_t UartWrite\(DevHandle handle, uint8\_t \*data, uint32\_t size\);
**表 7** UartWrite参数和返回值描述
参数
|
参数描述
|
|---|
handle
|
UART设备句柄
|
data
|
待写入数据的指针
|
size
|
待写入数据的长度
|
返回值
|
返回值描述
|
0
|
UART写数据成功
|
负数
|
UART写数据失败
|
写入指定长度数据的实例如下：
```
int32_t ret;
uint8_t wbuff[5] = {1, 2, 3, 4, 5};
/* 向UART设备写入指定长度的数据 */
ret = UartWrite(handle, wbuff, 5);
if (ret != 0) {
HDF_LOGE("UartWrite: failed, ret %d\n", ret);
}
```
## 从UART设备中读取指定长度的数据
对应的接口函数如下所示：
int32\_t UartRead\(DevHandle handle, uint8\_t \*data, uint32\_t size\);
**表 8** UartRead参数和返回值描述
参数
|
参数描述
|
|---|
handle
|
UART设备句柄
|
data
|
接收读取数据的指针
|
size
|
待读取数据的长度
|
返回值
|
返回值描述
|
非负数
|
UART读取到的数据长度
|
负数
|
UART读取数据失败
|
读取指定长度数据的实例如下：
```
int32_t ret;
uint8_t rbuff[5] = {0};
/* 从UART设备读取指定长度的数据 */
ret = UartRead(handle, rbuff, 5);
if (ret < 0) {
HDF_LOGE("UartRead: failed, ret %d\n", ret);
}
```
> **注意：**
>UART返回值为非负值，表示UART读取成功。若返回值等于0，表示UART无有效数据可以读取。若返回值大于0，表示实际读取到的数据长度，该长度小于或等于传入的参数size的大小，并且不超过当前正在使用的UART控制器规定的最大单次读取数据长度的值。
## 销毁UART设备句柄
UART通信完成之后，需要销毁UART设备句柄，函数如下所示：
void UartClose\(DevHandle handle\);
该函数会释放申请的资源。
**表 9** UartClose参数和返回值描述
销毁UART设备句柄的实例如下：
```
UartClose(handle); /* 销毁UART设备句柄 *
```