xt_hal_pwm - PWM 脉宽调制驱动

版本：0.1 | 日期：2026-07-03 | 路径： platforms/components/xtiny/xt_hal/

---

一、概述

xt_hal_pwm 是 xtiny 平台的 PWM（脉冲宽度调制）驱动模块，提供 PWM 初始化、占空比更新、启停控制五个接口。

设计理念： 先配置后启动 。 setup 配置频率和占空比后不会立即输出，需显式调用 start ；运行时可通过 set_duty 动态调整占空比。

1.1 设计原则

• 配置与输出分离 ： setup 只配置参数不启动， start / stop 控制输出，允许在启动前完成所有配置
• 16 位占空比 ：占空比范围为 0~65535（ XT_HAL_PWM_DUTY_MAX ），对应 0%~100%
• 频率近似 ：硬件可能无法精确匹配任意频率，平台实现会自动取最接近的值

1.2 依赖

仅依赖 xt_hal_internal.h （ xt_error.h ）。

---

二、核心概念

2.1 占空比计算

占空比使用 16 位无符号值，0 为最小（0），65535 为最大（~100）。模块提供宏 XT_HAL_PWM_DUTY(percentage) 将 0~100 的百分比转换为占空比值。

uint16_t duty_50 = XT_HAL_PWM_DUTY(50);   // 50%
uint16_t duty_75 = XT_HAL_PWM_DUTY(75);   // 75%

2.2 频率与占空比的近似

硬件通常基于定时器分频和周期计数实现 PWM，因此：

• 某些频率无法精确匹配，会自动取最接近值
• set_duty 的占空比也会被近似到硬件支持的最接近值

---

三、API 参考

以下为函数签名大纲，完整的参数说明、返回值、注意事项请查看 xt_hal_pwm（PWM 驱动） 。

3.1 生命周期

函数签名	说明
xt_err_t xt_hal_pwm_setup(uint16_t pwm_id, uint32_t freq, uint16_t duty)	初始化 PWM，设置频率（Hz）和占空比
xt_err_t xt_hal_pwm_close(uint16_t pwm_id)	关闭 PWM

3.2 控制

函数签名	说明
xt_err_t xt_hal_pwm_set_duty(uint16_t pwm_id)	更新占空比（触发硬件刷新约到的占空比）
xt_err_t xt_hal_pwm_start(uint16_t pwm_id)	启动 PWM 输出
xt_err_t xt_hal_pwm_stop(uint16_t pwm_id)	停止 PWM 输出

3.3 常量与宏

常量/宏	说明
XT_HAL_PWM_INVALID_ID	无效 PWM ID（ 0xFFFF ）
XT_HAL_PWM_DUTY_MAX	最大占空比值（ UINT16_MAX ）
XT_HAL_PWM_DUTY(percentage)	0~100 百分比转 16 位占空比

---

四、常见模式

4.1 基本使用流程

#include "xt_hal_pwm.h"
 
uint16_t pwm_id = 0;
 
xt_hal_pwm_setup(pwm_id, 1000, XT_HAL_PWM_DUTY(50));
xt_hal_pwm_start(pwm_id);
 
xt_hal_pwm_set_duty(pwm_id);
 
xt_hal_pwm_stop(pwm_id);
xt_hal_pwm_close(pwm_id);

---

五、已知行为与限制

• setup 后不会自动启动输出，必须调用 start
• 频率和占空比可能被近似到硬件支持的最接近值
• 不提供回调机制，所有操作为同步
• stop 后引脚电平状态取决于平台实现