UART#
UART(Universal Asynchronous Receiver/Transmitter)提供串口的初始化、去初始化、属性配置与查询、收发数据(轮询、中断、DMA(Direct Memory Access))、接收回调注册、错误回调注册、FIFO(First In First Out)状态查询及低功耗挂起与恢复能力。
模块公共头文件
#include "include/driver/uart.h"
接口清单#
接口名称 |
功能简述 |
|---|---|
初始化指定的串口,配置引脚、基础属性、扩展属性与接收缓存 |
|
去初始化指定的串口,释放引脚与状态资源 |
|
设置指定串口的基础配置参数(波特率、数据位、停止位、校验位、流控) |
|
获取指定串口当前的基础配置参数 |
|
判断指定串口是否存在正在等待或正在进行的传输 |
|
判断指定串口的接收 FIFO 是否为空 |
|
判断指定串口的发送 FIFO 是否为空 |
|
注册接收数据回调,按指定触发条件与数据长度触发 |
|
注销已注册的接收数据回调,并刷新接收 FIFO 中的数据 |
|
注册奇偶校验错误处理回调 |
|
注册帧错误处理回调 |
|
注册溢出错误处理回调 |
|
以轮询方式向指定串口发送数据 |
|
以轮询方式向指定串口发送数据,发送过程不锁中断 |
|
以中断方式向指定串口发送数据,发送完成后触发回调 |
|
通过 DMA 向指定串口发送数据 |
|
通过 DMA 从指定串口读取数据 |
|
注册接收中断触发 DMA 搬运数据的回调配置 |
|
注销接收中断触发 DMA 搬运数据的回调配置 |
|
结束 UART 的不定长数据 DMA 接收 |
|
启动 UART DMA 不定长数据接收,并在接收完成时触发回调 |
|
从指定串口以轮询方式读取数据 |
|
更新指定串口接收缓存的地址和长度 |
|
挂起所有已初始化的 UART 通道 |
|
恢复所有已挂起的 UART 通道 |
|
注册在 UART DMA 发送完成中断中直接进行 DMA 写的回调 |
Functions#
uapi_uart_init #
errcode_t uapi_uart_init(uart_bus_t bus, const uart_pin_config_t *pins, const uart_attr_t *attr, const uart_extra_attr_t *extra_attr, uart_buffer_config_t *uart_buffer_config)
声明头文件
#include "include/driver/uart.h"
功能说明
初始化指定的 UART 串口,配置引脚、基础属性、扩展属性和接收缓冲区。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
bus |
UART 总线号 |
UART_BUS_0 ~ UART_BUS_2 |
|
pins |
const uart_pin_config_t * |
UART 的引脚配置(TX/RX/RTS/CTS) |
不为 NULL |
attr |
const uart_attr_t * |
基础属性配置结构体指针 |
不为 NULL |
extra_attr |
const uart_extra_attr_t * |
扩展属性配置结构体指针 |
可为 NULL |
uart_buffer_config |
接收缓冲区配置结构体指针 |
- |
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
ERRCODE_SUCC:0 |
成功 |
成功初始化 |
Other |
其他错误码,参考errcode_t |
初始化失败 |
参考案例
src/application/samples/peripheral/uart/uart_demo.csrc/application/samples/bt/sle/sle_uart/sle_uart.c
Kconfig配置
配置项 |
宏类型 |
说明 |
默认值 |
|---|---|---|---|
CONFIG_UART_SUPPORT_TX |
特性宏 |
启用 UART 发送支持 |
y |
CONFIG_UART_SUPPORT_RX |
特性宏 |
启用 UART 接收支持 |
y |
CONFIG_UART_SUPPORT_DMA |
特性宏 |
启用 UART DMA 支持 |
y |
uapi_uart_deinit #
errcode_t uapi_uart_deinit(uart_bus_t bus)
声明头文件
#include "include/driver/uart.h"
功能说明
去初始化指定的 UART 串口,释放资源。
前置条件
已调用
uapi_uart_init完成初始化。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
bus |
UART 总线号 |
UART_BUS_0 ~ UART_BUS_2 |
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
ERRCODE_SUCC:0 |
成功 |
成功去初始化 |
Other |
其他错误码,参考errcode_t |
去初始化失败 |
参考案例
src/application/samples/peripheral/uart/uart_demo.csrc/application/samples/bt/sle/sle_uart/sle_uart.c
Kconfig配置
配置项 |
宏类型 |
说明 |
默认值 |
|---|---|---|---|
CONFIG_UART_SUPPORT_RX |
特性宏 |
启用 UART 接收支持 |
y |
CONFIG_UART_SUPPORT_TX |
特性宏 |
启用 UART 发送支持 |
y |
CONFIG_UART_SUPPORT_DMA |
特性宏 |
启用 UART DMA 支持 |
y |
uapi_uart_get_attr #
errcode_t uapi_uart_get_attr(uart_bus_t bus, const uart_attr_t *attr)
声明头文件
#include "include/driver/uart.h"
功能说明
获取 UART 当前基础配置参数。
前置条件
已调用
uapi_uart_init完成初始化。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
bus |
UART 总线号 |
UART_BUS_0 ~ UART_BUS_2 |
|
attr |
const uart_attr_t * |
用于接收当前基础配置的结构体指针(注意:源码签名使用 const 限定,实际无法通过该参数返回配置数据) |
不为 NULL |
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
ERRCODE_SUCC:0 |
成功 |
成功获取 |
Other |
其他错误码,参考errcode_t |
获取失败 |
uapi_uart_has_pending_transmissions #
bool uapi_uart_has_pending_transmissions(uart_bus_t bus)
声明头文件
#include "include/driver/uart.h"
功能说明
判断指定 UART 是否存在正在等待发送的数据。
前置条件
已调用
uapi_uart_init完成初始化。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
bus |
UART 总线号 |
UART_BUS_0 ~ UART_BUS_2 |
返回值
返回类型:bool
返回值 |
文字含义 |
触发场景 |
|---|---|---|
true |
存在正在等待的传输 |
总线存在待发送数据 |
false |
无正在等待的传输 |
总线无待发送数据 |
uapi_uart_rx_fifo_is_empty #
bool uapi_uart_rx_fifo_is_empty(uart_bus_t bus)
声明头文件
#include "include/driver/uart.h"
功能说明
判断指定 UART 的接收 FIFO 是否为空。
前置条件
已调用
uapi_uart_init完成初始化。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
bus |
UART 总线号 |
UART_BUS_0 ~ UART_BUS_2 |
返回值
返回类型:bool
返回值 |
文字含义 |
触发场景 |
|---|---|---|
true |
RX FIFO 为空 |
接收 FIFO 为空 |
false |
RX FIFO 非空 |
接收 FIFO 非空 |
uapi_uart_tx_fifo_is_empty #
bool uapi_uart_tx_fifo_is_empty(uart_bus_t bus)
声明头文件
#include "include/driver/uart.h"
功能说明
判断指定 UART 的发送 FIFO 是否为空。
前置条件
已调用
uapi_uart_init完成初始化。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
bus |
UART 总线号 |
UART_BUS_0 ~ UART_BUS_2 |
返回值
返回类型:bool
返回值 |
文字含义 |
触发场景 |
|---|---|---|
true |
TX FIFO 为空 |
发送 FIFO 为空 |
false |
TX FIFO 非空 |
发送 FIFO 非空 |
uapi_uart_set_attr #
errcode_t uapi_uart_set_attr(uart_bus_t bus, const uart_attr_t *attr)
声明头文件
#include "include/driver/uart.h"
功能说明
设置 UART 基础配置参数,包括波特率、数据位、校验位、停止位等。
前置条件
已调用
uapi_uart_init完成初始化。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
bus |
UART 总线号 |
UART_BUS_0 ~ UART_BUS_2 |
|
attr |
const uart_attr_t * |
基础属性配置结构体指针 |
不为 NULL |
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
ERRCODE_SUCC(0) |
成功 |
成功设置 |
Other |
其他错误码,参考errcode_t |
设置失败 |
uapi_uart_register_rx_callback #
errcode_t uapi_uart_register_rx_callback(uart_bus_t bus, uart_rx_condition_t condition, uint32_t size, uart_rx_callback_t callback)
声明头文件
#include "include/driver/uart.h"
功能说明
注册接收数据回调函数,回调会根据触发条件和数据长度触发,运行于中断上下文。
前置条件
已调用
uapi_uart_init完成初始化。使用中断模式或 DMA 模式。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
bus |
UART 总线号 |
UART_BUS_0 ~ UART_BUS_2 |
|
condition |
回调触发的条件 |
见枚举定义 |
|
size |
uint32_t |
触发条件涉及长度时表示所需的数据长度 |
- |
callback |
接收数据的回调函数 |
不为 NULL |
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
ERRCODE_SUCC:0 |
成功 |
成功注册 |
Other |
其他错误码,参考errcode_t |
注册失败 |
参考案例
src/application/samples/peripheral/uart/uart_demo.csrc/application/samples/bt/sle/sle_uart/sle_uart.c
Kconfig配置
配置项 |
宏类型 |
说明 |
默认值 |
|---|---|---|---|
CONFIG_UART_SUPPORT_RX |
特性宏 |
启用 UART 接收支持 |
y |
uapi_uart_unregister_rx_callback #
void uapi_uart_unregister_rx_callback(uart_bus_t bus)
声明头文件
#include "include/driver/uart.h"
功能说明
去注册 UART 接收数据回调函数。
前置条件
已调用
uapi_uart_register_rx_callback注册回调。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
bus |
UART 总线号 |
UART_BUS_0 ~ UART_BUS_2 |
Kconfig配置
配置项 |
宏类型 |
说明 |
默认值 |
|---|---|---|---|
CONFIG_UART_SUPPORT_RX |
特性宏 |
启用 UART 接收支持 |
y |
uapi_uart_register_parity_error_callback #
errcode_t uapi_uart_register_parity_error_callback(uart_bus_t bus, uart_error_callback_t callback)
声明头文件
#include "include/driver/uart.h"
功能说明
注册奇偶校验错误处理回调函数,当 UART 检测到奇偶校验错误时触发回调,运行于中断上下文。
前置条件
已调用
uapi_uart_init完成初始化。配置了奇偶校验功能。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
bus |
UART 总线号 |
UART_BUS_0 ~ UART_BUS_2 |
|
callback |
奇偶校验错误处理回调函数 |
不为 NULL |
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
ERRCODE_SUCC:0 |
成功 |
成功注册 |
Other |
其他错误码,参考errcode_t |
注册失败 |
Kconfig配置
配置项 |
宏类型 |
说明 |
默认值 |
|---|---|---|---|
CONFIG_UART_SUPPORT_RX |
特性宏 |
启用 UART 接收支持 |
y |
uapi_uart_register_frame_error_callback #
errcode_t uapi_uart_register_frame_error_callback(uart_bus_t bus, uart_error_callback_t callback)
声明头文件
#include "include/driver/uart.h"
功能说明
注册帧错误处理回调函数,当 UART 检测到帧错误时触发回调,运行于中断上下文。
前置条件
已调用
uapi_uart_init完成初始化。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
bus |
UART 总线号 |
UART_BUS_0 ~ UART_BUS_2 |
|
callback |
帧错误处理回调函数 |
不为 NULL |
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
ERRCODE_SUCC:0 |
成功 |
成功注册 |
Other |
其他错误码,参考errcode_t |
注册失败 |
Kconfig配置
配置项 |
宏类型 |
说明 |
默认值 |
|---|---|---|---|
CONFIG_UART_SUPPORT_RX |
特性宏 |
启用 UART 接收支持 |
y |
uapi_uart_register_overrun_error_callback #
errcode_t uapi_uart_register_overrun_error_callback(uart_bus_t bus, uart_error_callback_t callback)
声明头文件
#include "include/driver/uart.h"
功能说明
注册溢出错误处理回调函数,当 UART 检测到溢出错误时触发回调,运行于中断上下文。
前置条件
已调用
uapi_uart_init完成初始化。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
bus |
UART 总线号 |
UART_BUS_0 ~ UART_BUS_2 |
|
callback |
溢出错误处理回调函数 |
不为 NULL |
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
ERRCODE_SUCC:0 |
成功 |
成功注册 |
Other |
其他错误码,参考errcode_t |
注册失败 |
Kconfig配置
配置项 |
宏类型 |
说明 |
默认值 |
|---|---|---|---|
CONFIG_UART_SUPPORT_RX |
特性宏 |
启用 UART 接收支持 |
y |
uapi_uart_write #
int32_t uapi_uart_write(uart_bus_t bus, const uint8_t *buffer, uint32_t length, uint32_t timeout)
声明头文件
#include "include/driver/uart.h"
功能说明
以轮询(直接发送)方式将数据发送到已打开的 UART 上。
前置条件
已调用
uapi_uart_init完成初始化。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
bus |
UART 总线号 |
UART_BUS_0 ~ UART_BUS_2 |
|
buffer |
const uint8_t * |
要发送的数据 Buffer |
不为 NULL |
length |
uint32_t |
要发送的数据 Buffer 长度(字节) |
- |
timeout |
uint32_t |
超时时间(ms) |
- |
返回值
返回类型:int32_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
>=0 |
实际发送到 UART 的数据长度(字节) |
发送完成 |
<0 |
错误码,参考errcode_t |
发送失败 |
参考案例
src/application/samples/peripheral/uart/uart_demo.csrc/application/samples/bt/sle/sle_uart/sle_uart.c
Kconfig配置
配置项 |
宏类型 |
说明 |
默认值 |
|---|---|---|---|
CONFIG_UART_SUPPORT_TX |
特性宏 |
启用 UART 发送支持 |
y |
uapi_uart_write_nolock #
int32_t uapi_uart_write_nolock(uart_bus_t bus, const uint8_t *buffer, uint32_t length, uint32_t timeout)
声明头文件
#include "include/driver/uart.h"
功能说明
以轮询(直接发送)方式将数据发送到已打开的 UART 上,发送过程不锁中断。
前置条件
已调用
uapi_uart_init完成初始化。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
bus |
UART 总线号 |
UART_BUS_0 ~ UART_BUS_2 |
|
buffer |
const uint8_t * |
要发送的数据 Buffer |
不为 NULL |
length |
uint32_t |
要发送的数据 Buffer 长度(字节) |
- |
timeout |
uint32_t |
超时时间(ms) |
- |
返回值
返回类型:int32_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
>=0 |
实际发送到 UART 的数据长度(字节) |
发送完成 |
<0 |
错误码,参考errcode_t |
发送失败 |
Kconfig配置
配置项 |
宏类型 |
说明 |
默认值 |
|---|---|---|---|
CONFIG_UART_SUPPORT_TX |
特性宏 |
启用 UART 发送支持 |
y |
uapi_uart_write_int #
errcode_t uapi_uart_write_int(uart_bus_t bus, const uint8_t *buffer, uint32_t length, void *params, uart_tx_callback_t finished_with_buffer_func)
声明头文件
#include "include/driver/uart.h"
功能说明
以中断模式将数据发送到已打开的 UART 上,发送完成后调用回调函数(运行于中断上下文)。
前置条件
已调用
uapi_uart_init完成初始化。使用中断模式。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
bus |
UART 总线号 |
UART_BUS_0 ~ UART_BUS_2 |
|
buffer |
const uint8_t * |
要发送的数据 Buffer |
不为 NULL |
length |
uint32_t |
要发送的数据 Buffer 长度(字节) |
- |
params |
void * |
传递到完成传输回调函数的参数 |
可为 NULL |
finished_with_buffer_func |
数据发送完成的回调函数 |
可为 NULL |
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
ERRCODE_SUCC:0 |
成功 |
成功发送 |
Other |
其他错误码,参考errcode_t |
发送失败 |
参考案例
src/application/samples/peripheral/uart/uart_demo.c
Kconfig配置
配置项 |
宏类型 |
说明 |
默认值 |
|---|---|---|---|
CONFIG_UART_SUPPORT_TX |
特性宏 |
启用 UART 发送支持 |
y |
CONFIG_UART_SUPPORT_TX_INT |
特性宏 |
支持 UART 中断发送 |
y |
uapi_uart_write_by_dma #
int32_t uapi_uart_write_by_dma(uart_bus_t bus, const void *buffer, uint32_t length, uart_write_dma_config_t *dma_cfg)
声明头文件
#include "include/driver/uart.h"
功能说明
通过 DMA 将数据发送到 UART。
前置条件
已调用
uapi_uart_init完成初始化。使用 DMA 模式。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
bus |
UART 总线号 |
UART_BUS_0 ~ UART_BUS_2 |
|
buffer |
const void * |
要发送的数据 Buffer |
不为 NULL |
length |
uint32_t |
要发送的数据 Buffer 长度(字节) |
- |
dma_cfg |
发送数据时的 DMA 配置 |
不为 NULL |
返回值
返回类型:int32_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
>=0 |
完成发送的数据长度(字节) |
发送完成 |
<0 |
错误码,参考errcode_t |
发送失败 |
参考案例
src/application/samples/peripheral/uart/uart_demo.c
Kconfig配置
配置项 |
宏类型 |
说明 |
默认值 |
|---|---|---|---|
CONFIG_UART_SUPPORT_TX |
特性宏 |
启用 UART 发送支持 |
y |
CONFIG_UART_SUPPORT_DMA |
特性宏 |
启用 UART DMA 支持 |
y |
uapi_uart_read_by_dma #
int32_t uapi_uart_read_by_dma(uart_bus_t bus, const void *buffer, uint32_t length, uart_write_dma_config_t *dma_cfg)
声明头文件
#include "include/driver/uart.h"
功能说明
通过 DMA 从 UART 读取数据。
前置条件
已调用
uapi_uart_init完成初始化。使用 DMA 模式。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
bus |
UART 总线号 |
UART_BUS_0 ~ UART_BUS_2 |
|
buffer |
const void * |
存储接收数据的 Buffer |
不为 NULL |
length |
uint32_t |
存储接收数据的 Buffer 长度(字节) |
- |
dma_cfg |
接收数据时的 DMA 配置 |
不为 NULL |
返回值
返回类型:int32_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
>=0 |
完成接收的数据长度(字节) |
接收完成 |
<0 |
错误码,参考errcode_t |
接收失败 |
参考案例
src/application/samples/peripheral/uart/uart_demo.c
Kconfig配置
配置项 |
宏类型 |
说明 |
默认值 |
|---|---|---|---|
CONFIG_UART_SUPPORT_TX |
特性宏 |
启用 UART 发送支持 |
y |
CONFIG_UART_SUPPORT_DMA |
特性宏 |
启用 UART DMA 支持 |
y |
uapi_uart_register_read_by_dma_callback #
errcode_t uapi_uart_register_read_by_dma_callback(uart_bus_t bus, uart_write_dma_config_t *dma_cfg)
声明头文件
#include "include/driver/uart.h"
功能说明
注册接收中断触发 DMA 搬运数据的回调配置。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
bus |
串口号 |
有效 UART 总线 |
|
dma_cfg |
接收数据时使用的 DMA 配置 |
不为 NULL |
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
ERRCODE_SUCC:0 |
成功 |
成功注册 |
Other |
其他错误码,参考errcode_t |
注册失败 |
Kconfig配置
配置项 |
宏类型 |
说明 |
默认值 |
|---|---|---|---|
CONFIG_UART_SUPPORT_TX |
特性宏 |
支持 UART 发送功能(接口级,嵌套包裹接口声明) |
y |
CONFIG_UART_SUPPORT_DMA |
特性宏 |
支持 UART DMA 传输功能(接口级,嵌套包裹接口声明) |
y |
CONFIG_UART_SUPPORT_INT_TRIGGER_DMA |
特性宏 |
支持中断触发 DMA 功能(接口级,嵌套包裹接口声明) |
y |
uapi_uart_unregister_read_by_dma_callback #
void uapi_uart_unregister_read_by_dma_callback(uart_bus_t bus)
声明头文件
#include "include/driver/uart.h"
功能说明
注销接收中断触发 DMA 搬运数据的回调配置。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
bus |
串口号 |
有效 UART 总线 |
Kconfig配置
配置项 |
宏类型 |
说明 |
默认值 |
|---|---|---|---|
CONFIG_UART_SUPPORT_TX |
特性宏 |
支持 UART 发送功能(接口级,嵌套包裹接口声明) |
y |
CONFIG_UART_SUPPORT_DMA |
特性宏 |
支持 UART DMA 传输功能(接口级,嵌套包裹接口声明) |
y |
CONFIG_UART_SUPPORT_INT_TRIGGER_DMA |
特性宏 |
支持中断触发 DMA 功能(接口级,嵌套包裹接口声明) |
y |
uapi_uart_recv_raw_data_end_transfer #
errcode_t uapi_uart_recv_raw_data_end_transfer(uart_bus_t uart_bus)
声明头文件
#include "include/driver/uart.h"
功能说明
结束 UART 的不定长数据 DMA 接收。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
uart_bus |
串口号 |
有效 UART 总线,小于 UART_BUS_MAX_NUM |
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
ERRCODE_SUCC:0 |
成功执行 |
成功结束 DMA 不定长接收 |
ERRCODE_INVALID_PARAM:0x80000001 |
参数无效 |
uart_bus 越界 |
Other |
其他错误码,参考errcode_t |
执行失败 |
Kconfig配置
配置项 |
宏类型 |
说明 |
默认值 |
|---|---|---|---|
CONFIG_UART_SUPPORT_TX |
特性宏 |
支持 UART 发送功能(接口级,嵌套包裹接口声明) |
y |
CONFIG_UART_SUPPORT_DMA |
特性宏 |
支持 UART DMA 传输功能(接口级,嵌套包裹接口声明) |
y |
CONFIG_UART_SUPPORT_DMA_LLI |
特性宏 |
支持 DMA 链表传输功能(接口级,嵌套包裹接口声明) |
n |
CONFIG_UART_SUPPORT_RECV_RAW_DATA |
特性宏 |
支持不定长数据接收功能(接口级,嵌套包裹接口声明) |
n |
uapi_uart_dma_recv_raw_data #
errcode_t uapi_uart_dma_recv_raw_data(uart_bus_t uart_bus, uart_idle_int_receive_cb_t callback)
声明头文件
#include "include/driver/uart.h"
功能说明
启动 UART DMA 不定长数据接收,并在接收完成时触发回调。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
uart_bus |
串口号 |
有效 UART 总线,小于 UART_BUS_MAX_NUM |
|
callback |
接收完成后触发的 IDLE 回调 |
不为 NULL |
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
ERRCODE_SUCC:0 |
成功执行 |
DMA 不定长接收启动成功 |
ERRCODE_FAIL:0xFFFFFFFF |
执行失败 |
配置或启动 DMA 接收失败 |
Other |
其他错误码,参考errcode_t |
执行失败 |
Kconfig配置
配置项 |
宏类型 |
说明 |
默认值 |
|---|---|---|---|
CONFIG_UART_SUPPORT_TX |
特性宏 |
支持 UART 发送功能(接口级,嵌套包裹接口声明) |
y |
CONFIG_UART_SUPPORT_DMA |
特性宏 |
支持 UART DMA 传输功能(接口级,嵌套包裹接口声明) |
y |
CONFIG_UART_SUPPORT_DMA_LLI |
特性宏 |
支持 DMA 链表传输功能(接口级,嵌套包裹接口声明) |
n |
CONFIG_UART_SUPPORT_RECV_RAW_DATA |
特性宏 |
支持不定长数据接收功能(接口级,嵌套包裹接口声明) |
n |
uapi_uart_read #
int32_t uapi_uart_read(uart_bus_t bus, const uint8_t *buffer, uint32_t length, uint32_t timeout)
声明头文件
#include "include/driver/uart.h"
功能说明
以轮询模式从 UART 读取数据。
前置条件
已调用
uapi_uart_init完成初始化。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
bus |
UART 总线号 |
UART_BUS_0 ~ UART_BUS_2 |
|
buffer |
const uint8_t * |
存储接收数据的 Buffer |
不为 NULL |
length |
uint32_t |
存储接收数据的 Buffer 长度(字节) |
- |
timeout |
uint32_t |
超时时间(ms) |
- |
返回值
返回类型:int32_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
>=0 |
实际读到的数据长度(字节) |
读取完成 |
<0 |
错误码,参考errcode_t |
读取失败 |
参考案例
src/application/samples/peripheral/uart/uart_demo.c
Kconfig配置
配置项 |
宏类型 |
说明 |
默认值 |
|---|---|---|---|
CONFIG_UART_SUPPORT_RX |
特性宏 |
启用 UART 接收支持 |
y |
uapi_uart_update_rx_buff #
errcode_t uapi_uart_update_rx_buff(uart_bus_t bus, uint8_t *rx_buffer, uint16_t rx_buffer_size)
声明头文件
#include "include/driver/uart.h"
功能说明
更新 UART 接收 Buffer 的地址和长度。
前置条件
已调用
uapi_uart_init完成初始化。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
bus |
UART 总线号 |
UART_BUS_0 ~ UART_BUS_2 |
|
rx_buffer |
uint8_t * |
新的接收 Buffer 地址 |
不为 NULL |
rx_buffer_size |
uint16_t |
新的接收 Buffer 长度(字节) |
- |
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
ERRCODE_SUCC:0 |
成功 |
成功更新 |
Other |
其他错误码,参考errcode_t |
更新失败 |
Kconfig配置
配置项 |
宏类型 |
说明 |
默认值 |
|---|---|---|---|
CONFIG_UART_SUPPORT_RX |
特性宏 |
启用 UART 接收支持 |
y |
uapi_uart_suspend #
errcode_t uapi_uart_suspend(uintptr_t arg)
声明头文件
#include "include/driver/uart.h"
功能说明
挂起所有 UART 通道,暂停 UART 操作。
前置条件
已调用
uapi_uart_init完成初始化。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
arg |
uintptr_t |
挂起所需要的参数 |
- |
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
ERRCODE_SUCC:0 |
成功 |
挂起成功 |
Other |
其他错误码,参考errcode_t |
挂起失败 |
Kconfig配置
配置项 |
宏类型 |
说明 |
默认值 |
|---|---|---|---|
CONFIG_UART_SUPPORT_LPM |
特性宏 |
启用 UART 低功耗管理(Low Power Management)支持 |
y |
uapi_uart_resume #
errcode_t uapi_uart_resume(uintptr_t arg)
声明头文件
#include "include/driver/uart.h"
功能说明
恢复所有 UART 通道,从挂起状态恢复 UART 操作。
前置条件
已调用
uapi_uart_suspend挂起 UART。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
arg |
uintptr_t |
恢复所需要的参数 |
- |
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
ERRCODE_SUCC:0 |
成功 |
恢复成功 |
Other |
其他错误码,参考errcode_t |
恢复失败 |
Kconfig配置
配置项 |
宏类型 |
说明 |
默认值 |
|---|---|---|---|
CONFIG_UART_SUPPORT_LPM |
特性宏 |
启用 UART 低功耗管理(Low Power Management)支持 |
y |
uapi_uart_register_write_by_dma_callback #
errcode_t uapi_uart_register_write_by_dma_callback(uart_bus_t bus, uart_tx_by_dma_callback_t tx_dma_cb)
声明头文件
#include "include/driver/uart.h"
功能说明
注册在 UART DMA 发送完成中断中直接进行 DMA 写的回调。
入参
名称 |
参数类型 |
说明 |
约束取值范围 |
|---|---|---|---|
bus |
串口号 |
有效 UART 总线 |
|
tx_dma_cb |
uart_tx_by_dma_callback_t |
DMA 发送完成回调 |
不为 NULL |
返回值
返回类型:errcode_t
返回值 |
文字含义 |
触发场景 |
|---|---|---|
ERRCODE_SUCC:0 |
成功 |
成功注册 |
Other |
其他错误码,参考errcode_t |
注册失败 |
Kconfig配置
配置项 |
宏类型 |
说明 |
默认值 |
|---|---|---|---|
CONFIG_UART_SUPPORT_SEND_IN_DMA_ISR |
特性宏 |
支持在 DMA 发送中断中回调功能(接口级,包裹接口声明) |
n |
Type definitions#
uart_pin_config_t #
typedef hal_uart_pin_config_t uart_pin_config_t;
使用说明
UART 引脚配置类型,等价于 hal_uart_pin_config_t。
uart_attr_t #
typedef hal_uart_attr_t uart_attr_t;
使用说明
UART 基本属性定义类型,等价于 hal_uart_attr_t。
uart_extra_attr_t #
typedef hal_uart_extra_attr_t uart_extra_attr_t;
使用说明
UART 扩展属性定义类型,等价于 hal_uart_extra_attr_t。
uart_rx_callback_t #
typedef void (*uart_rx_callback_t)(const void *buffer, uint16_t length, bool error);
使用说明
UART 接收数据回调函数类型。在中断上下文中执行,接收缓冲区在回调返回后会被释放。
参数 参数名:说明。
参数 buffer:读取数据时用于存储数据的 Buffer。
参数 length:Buffer 的长度。
参数 error:true 表示接收数据时产生了错误,false 表示正常。
uart_tx_callback_t #
typedef void (*uart_tx_callback_t)(const void *buffer, uint32_t length, const void *params);
使用说明
UART 发送数据回调函数类型,在中断上下文中执行。
参数 参数名:说明。
参数 buffer:发送时的数据缓存。
参数 length:发送时的数据长度。
参数 params:传递的参数。
uart_error_callback_t #
typedef void (*uart_error_callback_t)(uint32_t *err_info, uint32_t len);
使用说明
UART 错误处理回调函数类型,在中断上下文中执行,执行完成后会自动释放内存。用于奇偶校验、帧、溢出错误回调注册。
参数 参数名:说明。
参数 err_info:错误信息,每一个成员都是 32-bit。
参数 len:错误信息的长度。
uart_tx_by_dma_callback_t #
typedef errcode_t (*uart_tx_by_dma_callback_t)(void);
使用说明
UART DMA 发送完成回调函数类型,作为 uapi_uart_register_write_by_dma_callback 的入参类型。
回调在中断上下文中执行,返回 errcode_t。
uart_idle_int_receive_cb_t #
typedef bool (*uart_idle_int_receive_cb_t)(uint8_t *receive_buff, uint32_t receive_length, bool error);
使用说明
UART DMA 不定长接收完成后的 IDLE 回调函数类型,作为 uapi_uart_dma_recv_raw_data 的入参类型。
参数 receive_buff:接收数据缓冲区;参数 receive_length:接收数据长度;参数 error:接收是否出错。
返回 true 表示继续接收数据,false 表示停止接收数据。
errcode_t #
typedef uint32_t errcode_t;
使用说明
通用错误码类型,定义于
errcode.h。ERRCODE_SUCC(0)表示成功,其余非零值表示失败,具体含义参考errcode.h
Enumerations#
uart_bus_t #
typedef enum {
UART_BUS_0 = 0, // !< UART L | UART H1
#if UART_BUS_MAX_NUMBER > 1
UART_BUS_1 = 1, // !< UART H | UART H0
#endif
#if UART_BUS_MAX_NUMBER > 2
UART_BUS_2 = 2, // !< M UART | UART L0
#endif
UART_BUS_NONE = UART_BUS_MAX_NUMBER // !< Value used as invalid/unused UART number
} uart_bus_t;
使用说明
UART 总线号枚举,定义于
platform_core.h(UART_BUS_MAX_NUMBER为 3)。
枚举成员 |
取值 |
描述 |
|---|---|---|
UART_BUS_0 |
0 |
UART 总线 0 |
UART_BUS_1 |
1 |
UART 总线 1 |
UART_BUS_2 |
2 |
UART 总线 2 |
UART_BUS_NONE |
3 |
无效总线号(UART_BUS_MAX_NUMBER) |
uart_rx_condition_t #
typedef enum uart_rx_condition {
UART_RX_CONDITION_FULL_OR_IDLE = (UART_RX_CONDITION_MASK_FULL | UART_RX_CONDITION_MASK_IDLE),
UART_RX_CONDITION_FULL_OR_SUFFICIENT_DATA = (UART_RX_CONDITION_MASK_FULL | UART_RX_CONDITION_MASK_SUFFICIENT_DATA),
UART_RX_CONDITION_FULL_OR_SUFFICIENT_DATA_OR_IDLE = (UART_RX_CONDITION_MASK_FULL | UART_RX_CONDITION_MASK_SUFFICIENT_DATA | UART_RX_CONDITION_MASK_IDLE)
} uart_rx_condition_t;
使用说明
UART 接收数据触发回调的条件枚举,定义于
uart.h
枚举成员 |
取值 |
描述 |
|---|---|---|
UART_RX_CONDITION_FULL_OR_IDLE |
5 |
接收缓存已满或接收暂停时触发回调 |
UART_RX_CONDITION_FULL_OR_SUFFICIENT_DATA |
6 |
接收缓存已满或接收数据量达到指定长度时触发回调 |
UART_RX_CONDITION_FULL_OR_SUFFICIENT_DATA_OR_IDLE |
7 |
接收缓存已满、接收数据量达到指定长度或接收暂停时触发回调 |
Structures#
hal_uart_pin_config_t #
typedef struct {
pin_t tx_pin;
pin_t rx_pin;
pin_t cts_pin;
pin_t rts_pin;
} hal_uart_pin_config_t;
使用说明
UART 引脚配置结构体,定义于
hal_uart.h
成员说明
成员名称 |
数据类型 |
描述 |
|---|---|---|
tx_pin |
pin_t |
发送引脚 |
rx_pin |
pin_t |
接收引脚 |
cts_pin |
pin_t |
发送就绪引脚 |
rts_pin |
pin_t |
接收就绪引脚 |
hal_uart_attr_t #
typedef struct uart_attr {
uint32_t baud_rate;
uint8_t data_bits;
uint8_t stop_bits;
uint8_t parity;
uint8_t flow_ctrl;
} hal_uart_attr_t;
使用说明
UART 基本属性配置结构体,定义于
hal_uart.h
成员说明
成员名称 |
数据类型 |
描述 |
|---|---|---|
baud_rate |
uint32_t |
波特率 |
data_bits |
uint8_t |
数据位,参考 uart_data_bit_t |
stop_bits |
uint8_t |
停止位,参考 uart_stop_bit_t |
parity |
uint8_t |
校验位,参考 uart_parity_t |
flow_ctrl |
uint8_t |
流控类型,参考 uart_flow_ctrl_t |
hal_uart_extra_attr_t #
typedef struct uart_extra_attr {
bool tx_dma_enable;
uint8_t tx_int_threshold;
bool rx_dma_enable;
uint8_t rx_int_threshold;
} hal_uart_extra_attr_t;
使用说明
UART 扩展属性配置结构体,定义于
hal_uart.h
成员说明
成员名称 |
数据类型 |
描述 |
|---|---|---|
tx_dma_enable |
bool |
TX 是否使用 DMA。false: 使用 uapi_uart_write 发送; true: 使用 uapi_uart_write_by_dma 发送 |
tx_int_threshold |
uint8_t |
触发中断的 TX FIFO 水线 |
rx_dma_enable |
bool |
RX 是否使用 DMA。false: 使用 uapi_uart_read 接收; true: 使用 uapi_uart_read_by_dma 接收 |
rx_int_threshold |
uint8_t |
触发中断的 RX FIFO 水线 |
uart_buffer_config_t #
typedef struct uart_buffer_config {
void *rx_buffer;
size_t rx_buffer_size;
} uart_buffer_config_t;
使用说明
UART 缓冲区配置结构体,定义于
uart.h
成员说明
成员名称 |
数据类型 |
描述 |
|---|---|---|
rx_buffer |
void * |
接收数据 Buffer 指针 |
rx_buffer_size |
size_t |
接收 Buffer 的长度 |
uart_write_dma_config_t #
typedef struct uart_write_dma_config {
uint8_t src_width;
uint8_t dest_width;
uint8_t burst_length;
uint8_t priority;
} uart_write_dma_config_t;
使用说明
UART DMA 发送配置结构体,定义于
uart.h
成员说明
成员名称 |
数据类型 |
描述 |
|---|---|---|
src_width |
uint8_t |
源端传输数据宽度:0-1 字节,1-2 字节,2-4 字节 |
dest_width |
uint8_t |
目的端传输数据宽度:0-1 字节,1-2 字节,2-4 字节 |
burst_length |
uint8_t |
burst 长度:0-1,1-4,2-8,3-16 |
priority |
uint8_t |
传输通道优先级(最小 0,最大 3) |
Macros#
ERRCODE_SUCC #
#define ERRCODE_SUCC 0UL
ERRCODE_FAIL #
#define ERRCODE_FAIL 0xFFFFFFFF
ERRCODE_INVALID_PARAM #
#define ERRCODE_INVALID_PARAM 0x80000001