跳至主要內容

USART模块用户手册

大约 14 分钟约 4346 字2025/12/26

USART模块用户手册

目录

1. 简介

本模块提供了对 USART (Universal Synchronous/Asynchronous Receiver/Transmitter) 的抽象接口，支持异步全双工通信、同步通信，并集成了DMA传输和中断处理机制。

主要功能包括：

  • 初始化与反初始化: 通过 HLI_Usart_Init 或 HLI_Usart_InitModule 初始化一个或多个USART模块，配置波特率、数据位、停止位、校验位等。
  • 同步数据收发: 提供 HLI_Usart_SyncTransmit 函数，以阻塞方式发送数据。
  • 异步数据收发:
    • 发送: 提供 HLI_Usart_AsyncTransmit (DMA/中断) 和 HLI_Usart_AsyncPollingTransmit (DMA轮询) 函数。
    • 接收: 支持DMA接收，通过 HLI_Usart_SetRxBuffer 配置接收缓冲区，并通过空闲中断回调通知应用层接收完成。
  • 状态查询与控制: 提供 HLI_Usart_GetAsyncTransmitStatus 查询异步发送状态，HLI_Usart_StopAsyncTransmit 停止异步发送。
  • 中断回调: 提供接收数据、接收包（空闲中断）、发送完成等回调接口。

1.1 支持的设备

当前软件适用于以下芯片:

  • KF32A158xxxSF

1.2 名词及缩写

缩写解释
USART通用全\半双工收发器
DMA直接存储器访问模块
ISR中断服务例程

2. 文件结构

文件名称描述
kf32axxx_hli_usart.c此文件包含USART驱动程序的通用功能
kf32axxx_hli_usart.h此头文件输出USART驱动程序的宏、类型定义和函数原型
kf32axxx_hli_usart_Lcfg.cUSART配置
kf32axxx_hli_usart_Lcfg.hUSART配置变量声明
kf32axxx_hli_usart_cfg.hUSART配置DMA使用的buffer大小
__irq_usart.cUSART中断处理

3. 数据结构

3.1 数据类型

3.1.1 宏定义

  1. DMA使能状态

    宏定义解释
    HLI_USART_DMA_DISABLE不使用dma
    HLI_USART_DMA_ENABLE使用dma

3.1.2 枚举

  1. USART模块索引 (HLI_Usart_ModuleType)

    枚举值解释
    HLI_USART_MODULE_0USART0
    HLI_USART_MODULE_1USART1
    HLI_USART_MODULE_2USART2
    HLI_USART_MODULE_3USART3
    HLI_USART_MODULE_6USART6

  2. DMA通道序号 (HLI_Usart_DmaSourceType)

    枚举值解释
    HLI_USART_DMA0_CHANNEL_1DMA0通道1
    HLI_USART_DMA0_CHANNEL_2DMA0通道2
    ......
    HLI_USART_DMA1_CHANNEL_7DMA1通道7

  3. 停止位长度 (HLI_Usart_StopBitType)

    枚举值解释
    HLI_USART_STOP_BIT_11个停止位
    HLI_USART_STOP_BIT_22个停止位

  4. 校验方式 (HLI_Usart_ParityType)

    枚举值解释
    HLI_USART_PARITY_NONE无校验
    HLI_USART_PARITY_ODD奇校验
    HLI_USART_PARITY_EVEN偶校验

  5. 位序 (HLI_Usart_OrderType)

    枚举值解释
    HLI_USART_LSB_FIRSTLSB
    HLI_USART_MSB_FIRSTMSB

  6. 通信波特率 (HLI_Usart_BaudRateType)

    枚举值解释
    HLI_BAUDRATE_4800波特率 4800
    HLI_BAUDRATE_9600波特率 9600
    HLI_BAUDRATE_19200波特率 19200
    HLI_BAUDRATE_115200波特率 115200
    HLI_BAUDRATE_500000波特率 500000
    HLI_BAUDRATE_921600波特率 921600
    HLI_BAUDRATE_1000000波特率 1000000

  7. TX数据输出引脚 (HLI_Usart_PassageWayType)

    枚举值解释
    HLI_USART_TX0通过TX0引脚输出数据
    HLI_USART_TX1通过TX1引脚输出数据

  8. 函数执行结果 (HLI_Usart_StatusType)

    枚举值解释
    HLI_USART_STATUS_OK成功
    HLI_USART_STATUS_INITIALIZED重复初始化
    HLI_USART_STATUS_INVALID_PARAM参数错误
    HLI_USART_STATUS_UNINIT未初始化
    HLI_USART_STATUS_SEND_TIMEOUT发送超时
    HLI_USART_STATUS_NOT_USED_DMA未使用DMA
    HLI_USART_STATUS_NOT_BUSY非忙状态 (停止发送时)

  9. 异步发送状态 (HLI_Usart_AsyncTransmitResultType)

    枚举值解释
    HLI_USART_ASYNC_IDLE空闲
    HLI_USART_ASYNC_BUSY发送中
    HLI_USART_ASYNC_COMPLETED发送完成

3.1.3 类型定义

无。

3.2 配置项说明

  1. 静态配置

    静态配置在 kf32axxx_hli_usart_cfg.h 文件中通过宏定义完成。

    宏定义解释取值范围
    USART_FEATURE_PASSAGEWAY_ENABLEUSART模块输出通道TX0/TX1可选特性使能开关。
    true：TX0/TX1可选
    false：默认TX0    		true / false

  2. DMA资源配置 (HLI_Usart_DmaSourceConfigType)

    成员解释取值范围
    ReceiveDmaSwitch接收是否使用dmaHLI_USART_DMA_ENABLE / _DISABLE
    SendDmaSwitch发送是否使用dmaHLI_USART_DMA_ENABLE / _DISABLE
    RxDmaSource接收通道DMA资源可选范围参考 HLI_Usart_DmaSourceType
    TxDmaSource发送通道DMA资源可选范围参考 HLI_Usart_DmaSourceType

  3. 单元配置 (HLI_Usart_UnitConfigType)

    成员解释取值范围
    BaudRate波特率可选范围参考 HLI_Usart_BaudRateType
    StopBit停止位配置可选范围参考 HLI_Usart_StopBitType
    ParityMode校验方式配置可选范围参考 HLI_Usart_ParityType
    ReceiveOrder接收位序可选范围参考 HLI_Usart_OrderType
    SendOrder发送位序可选范围参考 HLI_Usart_OrderType
    PassageWay数据发送通道可选范围参考 HLI_Usart_PassageWayType (仅当 USART_FEATURE_PASSAGEWAY_ENABLE 为 true 时有效)
    DmaConfigPtrDMA配置信息指向 HLI_Usart_DmaSourceConfigType 的指针
    ReceivePacketCallbackDMA接收回调函数HLI_Usart_ReceivePacketFcnType 类型的函数指针
    ReceiveDataCallback单字节中断接收回调函数HLI_Usart_ReceiveDataFcnType 类型的函数指针
    ReceiveIdleCallback空闲中断回调函数HLI_Usart_ReceiveIdleFcnType 类型的函数指针
    SendCompletedCallback发送完成回调函数HLI_Usart_SendCompletedFcnType 类型的函数指针

  4. 模块信息配置 (HLI_Usart_InformationConfigType)

    成员解释取值范围
    Moduleusart选择可选范围参考 HLI_Usart_ModuleType
    UsartUnitConfigUSART单元配置信息指向 HLI_Usart_UnitConfigType 类型的结构体指针

  5. 顶层配置 (HLI_Usart_ConfigType)

    成员解释取值范围
    UsartNum配置的USART数量1 ~ HLI_USART_MAX_NUM
    UsartConfig[HLI_USART_MAX_NUM]配置信息数组指向 HLI_Usart_InformationConfigType 的指针数组

4. 驱动函数

4.1 函数接口

4.1.1 HLI_Uart_Init

NameDescription
函数名称HLI_Uart_Init
语法HLI_Usart_StatusType HLI_Uart_Init(const HLI_Usart_ConfigType *UsartConfigPtr)
同步/异步同步
重入性USART对象不同时可重入
形参(输入)UsartConfigPtr : 配置信息
返回值HLI_USART_STATUS_OK: 初始化成功
返回值HLI_USART_STATUS_INITIALIZED: 重复初始化
返回值HLI_USART_STATUS_INVALID_PARAM: 参数错误
描述初始化所有在配置结构体中定义的USART模块。
注意事项USART默认使用系统时钟源。

4.1.2 HLI_Usart_InitModule

NameDescription
函数名称HLI_Usart_InitModule
语法HLI_Usart_StatusType HLI_Usart_InitModule(HLI_Usart_ModuleType UsartxModule, const HLI_Usart_UnitConfigType *UsartModuleConfigPtr)
同步/异步同步
重入性USART对象不同时可重入
形参(输入)UsartxModule : USART编号
形参(输入)UsartModuleConfigPtr : 配置信息
返回值HLI_USART_STATUS_OK: 初始化成功
返回值HLI_USART_STATUS_INITIALIZED: 重复初始化
描述初始化单个USART模块。
注意事项初始化后, 如果配置DMA接收, 必须使用 HLI_Usart_SetRxBuffer 开始接收, 否则不开启接收。

4.1.3 HLI_Usart_SyncTransmit

NameDescription
函数名称HLI_Usart_SyncTransmit
语法HLI_Usart_StatusType HLI_Usart_SyncTransmit(HLI_Usart_ModuleType UsartxModule, const uint8_t *SendData, uint16_t SendLength, uint32_t TimeOut)
同步/异步同步
重入性USART对象不同时可重入
形参(输入)UsartxModule : USART编号
形参(输入)SendData : 发送数据缓冲区指针
形参(输入)SendLength : 发送长度
形参(输入)TimeOut : 超时时间, 0表示无限等待
返回值HLI_USART_STATUS_OK : 发送成功
返回值HLI_USART_STATUS_UNINIT : USART未初始化
返回值HLI_USART_STATUS_SEND_TIMEOUT : USART发送超时
返回值HLI_USART_STATUS_INVALID_PARAM : 参数错误
描述使用串口同步发送数据。若配置了DMA，则使用DMA发送并轮询等待完成；否则使用寄存器写入并轮询。
注意事项SendData不为空且SendLength大于0。

4.1.4 HLI_Usart_AsyncPollingTransmit

NameDescription
函数名称HLI_Usart_AsyncPollingTransmit
语法HLI_Usart_StatusType HLI_Usart_AsyncPollingTransmit(HLI_Usart_ModuleType UsartxModule, const uint8_t *SendData, uint16_t SendLength)
同步/异步异步
重入性USART对象不同时可重入
形参(输入)UsartxModule : USART编号
形参(输入)SendData : 发送数据缓冲区指针
形参(输入)SendLength : 发送长度
返回值HLI_USART_STATUS_OK: 开始发送数据
返回值HLI_USART_STATUS_UNINIT: USART未初始化
返回值HLI_USART_STATUS_NOT_USED_DMA: USART未配置DMA功能
返回值HLI_USART_STATUS_INVALID_PARAM: 参数错误
描述使用DMA异步发送数据，不启用发送完成中断。发送结果需通过 HLI_Usart_GetAsyncTransmitStatus 轮询获取。
注意事项必须配置DMA功能。

4.1.5 HLI_Usart_GetAsyncTransmitStatus

NameDescription
函数名称HLI_Usart_GetAsyncTransmitStatus
语法HLI_Usart_AsyncTransmitResultType HLI_Usart_GetAsyncTransmitStatus(HLI_Usart_ModuleType UsartxModule)
同步/异步同步
重入性USART对象不同时可重入
形参(输入)UsartxModule : USART编号
返回值HLI_USART_ASYNC_IDLE : 空闲
返回值HLI_USART_ASYNC_BUSY : 发送中
返回值HLI_USART_ASYNC_COMPLETED : 发送完成
描述获取串口DMA发送数据状态。
注意事项调用异步发送接口前, 建议先获取一下发送状态。

4.1.6 HLI_Usart_StopAsyncTransmit

NameDescription
函数名称HLI_Usart_StopAsyncTransmit
语法HLI_Usart_StatusType HLI_Usart_StopAsyncTransmit(HLI_Usart_ModuleType UsartxModule)
同步/异步同步
重入性不可重入
形参(输入)UsartxModule : USART编号
返回值HLI_USART_STATUS_OK: 停止发送
返回值HLI_USART_STATUS_UNINIT: USART未初始化
返回值HLI_USART_STATUS_NOT_BUSY: USART未在发送数据
描述停止异步发送。
注意事项用于发送时间较长或异常情况处理。

4.1.7 HLI_Usart_SetRxBuffer

NameDescription
函数名称HLI_Usart_SetRxBuffer
语法HLI_Usart_StatusType HLI_Usart_SetRxBuffer(HLI_Usart_ModuleType UsartxModule, uint32_t MemoryAddr, uint16_t ReceiveLen)
同步/异步同步
重入性可重入
形参(输入)UsartxModule : USART编号
形参(输入)MemoryAddr : DMA接收数据地址
形参(输入)ReceiveLen : DMA接收数据长度
返回值HLI_USART_STATUS_OK: 更新地址和长度成功
返回值HLI_USART_STATUS_UNINIT: USART未初始化
返回值HLI_USART_STATUS_NOT_USED_DMA: USART未配置DMA功能
返回值HLI_USART_STATUS_INVALID_PARAM: 参数错误
描述修改USART接下来的DMA接收缓冲区地址和长度，并启动接收。
注意事项在初始化后必须调用此函数开启接收。在 HLI_Usart_ReceivePacketFcnType 中断回调中也必须调用此函数以开启下一次接收。

4.1.8 HLI_Usart_AsyncTransmit

NameDescription
函数名称HLI_Usart_AsyncTransmit
语法HLI_Usart_StatusType HLI_Usart_AsyncTransmit(HLI_Usart_ModuleType UsartxModule, const uint8_t *SendData, uint16_t SendLength)
同步/异步异步
重入性USART对象不同时可重入
形参(输入)UsartxModule : USART编号
形参(输入)SendData : 发送数据缓冲区指针
形参(输入)SendLength : 发送长度
返回值HLI_USART_STATUS_OK: 开始发送
返回值HLI_USART_STATUS_UNINIT: USART未初始化
返回值HLI_USART_STATUS_INVALID_PARAM : 参数错误
描述异步发送。若配置了DMA，则使用DMA发送并开启中断；若未配置DMA，则使用中断发送。
注意事项发送buffer必须在发送完成前保持有效（建议使用全局或静态变量），否则可能导致发送数据错误。

4.1.9 HLI_Usart_DeInit

NameDescription
函数名称HLI_Usart_DeInit
语法HLI_Usart_StatusType HLI_Usart_DeInit(HLI_Usart_ModuleType UsartxModule)
同步/异步同步
重入性USART对象不同时可重入
形参(输入)UsartxModule : USART编号
返回值HLI_USART_STATUS_OK: 反初始化成功
返回值HLI_USART_STATUS_UNINIT: 模块未初始化
描述反初始化USART。
注意事项只反初始化已经初始化的USART。

4.2 中断回调

4.2.1 HLI_Usart_ReceiveDataFcnType

NameDescription
回调类型HLI_Usart_ReceiveDataFcnType
语法void (*HLI_Usart_ReceiveDataFcnType)(uint8_t RxData)
形参(输入)RxData : 接收到的单个字节数据
返回值void
描述不使用DMA接收时, 单个字节接收中断回调。
注意事项函数内不应该有时间长处理, 需要处理完后立刻退出。

4.2.2 HLI_Usart_ReceivePacketFcnType

NameDescription
回调类型HLI_Usart_ReceivePacketFcnType
语法void (*HLI_Usart_ReceivePacketFcnType)(uint32_t RxLength)
形参(输入)RxLength : 实际接收的数据长度
返回值void
描述使用DMA接收时，触发空闲中断后调用此回调，通知用户已接收一组数据。
注意事项函数内必须调用 HLI_Usart_SetRxBuffer 更新下一次DMA接收数据的地址和长度。

4.2.3 HLI_Usart_ReceiveIdleFcnType

NameDescription
回调类型HLI_Usart_ReceiveIdleFcnType
语法void (*HLI_Usart_ReceiveIdleFcnType)(void)
形参(输入)无
返回值void
描述空闲中断回调。
注意事项用户可根据实际应用添加逻辑代码。

4.2.4 HLI_Usart_SendCompletedFcnType

NameDescription
回调类型HLI_Usart_SendCompletedFcnType
语法void (*HLI_Usart_SendCompletedFcnType)(void)
形参(输入)无
返回值void
描述发送完成回调, 通知发送完一组数据。
注意事项用户可根据实际应用添加逻辑代码。

5. 使用示例

注

示例中使用的参数仅用作示例演示，应用时以实际为准。

5.1 异步DMA发送与接收 (AsyncDmaTransmit)

此示例展示了配置DMA进行异步发送和接收。

  • 发送: 使用 HLI_Usart_AsyncTransmit 配合DMA，发送完成后触发回调。
  • 接收: 使用DMA接收，通过空闲中断触发包接收回调。

5.2 异步中断发送与接收 (AsyncModuleTransmit)

此示例展示了不使用DMA，完全依赖中断进行异步发送和接收。

  • 发送: 使用 HLI_Usart_AsyncTransmit，通过TXE中断逐字节发送，完成后触发回调。
  • 接收: 通过接收中断（RXE）逐字节接收，触发数据接收回调。

5.3 异步DMA轮询发送与接收 (AsyncDmaPollingTransmit)

此示例展示了使用DMA发送但不使用中断通知完成，而是由用户轮询状态。

  • 发送: 使用 HLI_Usart_AsyncPollingTransmit 启动DMA发送，用户循环调用 HLI_Usart_GetAsyncTransmitStatus 检查是否完成。
  • 接收: 使用DMA接收（同5.1）。

5.4 同步DMA发送与接收 (SyncDmaTransmit)

此示例展示了同步（阻塞）发送方式，底层使用DMA传输。

  • 发送: 使用 HLI_Usart_SyncTransmit，函数内部启动DMA并轮询等待完成，直到超时或成功。
  • 接收: 使用DMA接收（同5.1）。

5.5 同步寄存器发送与中断接收 (SyncModuleTransmit)

此示例展示了同步（阻塞）发送方式，底层使用寄存器写入；接收使用中断。

  • 发送: 使用 HLI_Usart_SyncTransmit，函数内部循环写DR寄存器并等待，直到完成。
  • 接收: 使用中断逐字节接收（同5.2）。

6. 限制与假设

  1. 波特率范围: 支持 4800、9600、19200、115200、500000、921600、1000000bps。
  2. 时钟源: 默认使用系统时钟源。
  3. DMA配置: 若使用DMA接收，必须在初始化后及每次接收完成回调中调用 HLI_Usart_SetRxBuffer。
  4. 缓冲区: 使用异步发送时，发送缓冲区必须在发送完成前保持有效（建议使用静态或全局变量）。

7. 变更记录

版本时间变更记录
v1.02025-11-24新增初版文档
最近更新
贡献者: 翟宇