G32S10 PWM HAL 接口

1. 资源模型与公开类型

1.1 模块基地址与实例

PWM模块当前公开一个实例。

当前SDK中 PWM_IOBASE 定义在 base.h，pwm_regs.h 中提供如下实例宏：

#define PWM  ((pwm_regs_t *)(uintptr_t)PWM_IOBASE)

说明：

• 实例宏使用 (uintptr_t) 完成整数地址到指针的中间转换

• HAL通过 hal_pwm_handle_t.instance 保存PWM寄存器基地址

• LL接口通过 pwm_regs_t *pwmx 或 const pwm_regs_t *pwmx 传递实例

1.2 HAL公开宏

1.3 HAL运行状态

typedef enum {
    HAL_PWM_STATE_RESET = 0U,
    HAL_PWM_STATE_READY = 1U,
} hal_pwm_state_t;

1.4 PWM组选择类型

typedef enum {
    HAL_PWM_GROUP_NONE = 0U,
    HAL_PWM_GROUP_0 = (1UL << 0U),
    HAL_PWM_GROUP_1 = (1UL << 1U),
    HAL_PWM_GROUP_2 = (1UL << 2U),
    HAL_PWM_GROUP_3 = (1UL << 3U),
    HAL_PWM_GROUP_4 = (1UL << 4U),
    HAL_PWM_GROUP_5 = (1UL << 5U),
    HAL_PWM_GROUP_6 = (1UL << 6U),
    HAL_PWM_GROUP_7 = (1UL << 7U),
    HAL_PWM_GROUP_ALL = 0xFFUL,
} hal_pwm_group_t;

说明：枚举值用于按位选择PWM组，不是0至7的连续下标。HAL_PWM_GROUP_NONE 表示不选择任何PWM组，HAL_PWM_GROUP_ALL 表示同时选择全部8个PWM组。

1.5 PWM时钟分频类型

typedef enum {
    HAL_PWM_CLK_DIV_1 = 0U,
    HAL_PWM_CLK_DIV_2 = 1U,
    HAL_PWM_CLK_DIV_4 = 2U,
    HAL_PWM_CLK_DIV_8 = 3U,
    HAL_PWM_CLK_DIV_16 = 4U,
    HAL_PWM_CLK_DIV_32 = 5U,
    HAL_PWM_CLK_DIV_64 = 6U,
    HAL_PWM_CLK_DIV_128 = 7U,
} hal_pwm_clk_div_t;

说明：字段编码为 div 时，硬件分频系数为 2^div。同一PWM组的P/N输出共享时钟分频，因此具有相同基频。

1.6 PWM波形模式

typedef enum {
    HAL_PWM_MODE_EDGE_ALIGNED = 0U,
    HAL_PWM_MODE_CENTER_ALIGNED = 1U,
} hal_pwm_wave_mode_t;

说明：硬件 WMODE 字段支持四种模式。HAL当前只开放普通边沿对齐模式和中心对齐互补模式，不提供编码2的边沿对齐推挽模式和编码3的中心对齐推挽模式。

1.7 PWM单路输出电平

typedef enum {
    HAL_PWM_LEVEL_LOW = 0U,
    HAL_PWM_LEVEL_HIGH = 1U,
} hal_pwm_level_t;

说明：用于单独配置P输出或N输出的低、高电平。

1.8 PWM P/N组合电平

typedef enum {
    HAL_PWM_PL_NL = 0U,
    HAL_PWM_PH_NL = 1U,
    HAL_PWM_PL_NH = 2U,
    HAL_PWM_PH_NH = 3U,
} hal_pwm_pn_level_t;

说明：以2位编码同时表示一个PWM组的P/N电平。中心对齐模式下，N有效输出由硬件按P的反相信号处理；HAL不禁止P/N电平字段写入相同值。

1.9 PWM输出控制模式

typedef enum {
    HAL_PWM_OUTPUT_NORMAL = 0U,
    HAL_PWM_OUTPUT_L = 1U,
    HAL_PWM_OUTPUT_H = 2U,
} hal_pwm_output_control_t;

说明：用于选择OSCR正常输出、强制低或强制高状态。硬件OSCR编码2和3均表示强制高，HAL读取接口统一返回 HAL_PWM_OUTPUT_H。

1.10 ADC触发端点

typedef enum {
    HAL_PWM_ADC0_TRIGGER0 = 0U,
    HAL_PWM_ADC0_TRIGGER1 = 1U,
    HAL_PWM_ADC1_TRIGGER0 = 2U,
    HAL_PWM_ADC1_TRIGGER1 = 3U,
} hal_pwm_adc_trigger_t;

说明：每个ADC触发端点可独立选择一个PWM组作为触发源，每个PWM组提供两个触发阈值。

1.11 ADC触发调试输出

typedef enum {
    HAL_PWM_ADC_DEBUG_IO_0 = 0U,
    HAL_PWM_ADC_DEBUG_IO_1 = 1U,
    HAL_PWM_ADC_DEBUG_IO_2 = 2U,
    HAL_PWM_ADC_DEBUG_IO_3 = 3U,
} hal_pwm_adc_debug_io_t;

说明：HAL只写PWM路由寄存器，不配置GPIO引脚复用。

1.12 FAIL保护使能模式

typedef enum {
    HAL_PWM_FAIL_DISABLE = 0U,
    HAL_PWM_FAIL_ENABLE_IO = 1U,
    HAL_PWM_FAIL_ENABLE_ADC = 2U,
    HAL_PWM_FAIL_ENABLE_BOTH = 3U,
} hal_pwm_fail_enable_t;

说明：用于关闭失效保护、仅使能IO失效保护、仅使能ADC失效保护或同时使能两者。

1.13 FAIL保护源

typedef enum {
    HAL_PWM_FAIL_SOURCE_IO0 = 0U,
    HAL_PWM_FAIL_SOURCE_IO1 = 1U,
    HAL_PWM_FAIL_SOURCE_ADC0 = 0U,
    HAL_PWM_FAIL_SOURCE_ADC1 = 2U,
} hal_pwm_fail_source_t;

说明：位0选择IO0或IO1，位1选择ADC0或ADC1；一个IO选择值和一个ADC选择值按位或后使用。

1.14 FAIL状态位

typedef enum {
    HAL_PWM_FAIL_BIT_NONE = 0U,
    HAL_PWM_FAIL_BIT_IO = 1U,
    HAL_PWM_FAIL_BIT_ADC = 2U,
    HAL_PWM_FAIL_BIT_BOTH = 3U,
} hal_pwm_fail_bits_t;

说明：用于指示一个PWM组内的IO失效状态位、ADC失效状态位或两者。

1.15 PWM主中断类型

typedef enum {
    HAL_PWM_IRQ_TYPE_EVENT = 0U,
    HAL_PWM_IRQ_TYPE_GLOBAL = 1U,
    HAL_PWM_IRQ_TYPE_FAIL_IO = 2U,
    HAL_PWM_IRQ_TYPE_FAIL_ADC = 3U,
} hal_pwm_irq_type_t;

1.16 PWM波形参数配置

typedef struct {
    uint16_t period_count;
    uint16_t p_threshold;
    uint16_t n_threshold;
    uint16_t p_dead_time;
    uint16_t n_dead_time;
} hal_pwm_param_config_t;

说明：特殊周期值和比较阈值组合可自然形成静态高或静态低输出，具体结果取决于波形模式和初始电平。

1.17 PWM组初始化配置

typedef struct {
    hal_pwm_clk_div_t clk_div;
    hal_pwm_wave_mode_t mode;
    hal_pwm_pn_level_t init_level;
    hal_pwm_pn_level_t idle_level;
    hal_pwm_param_config_t param;
} hal_pwm_init_config_t;

说明：hal_pwm_group_init() 接收该结构，但只写配置寄存器，不触发参数更新，也不启动输出。

1.18 ADC触发调试输出配置

typedef struct {
    hal_pwm_adc_trigger_t adc_trigger;
    hal_pwm_adc_debug_io_t debug_io;
} hal_pwm_adc_debug_config_t;

1.19 FAIL保护配置

typedef struct {
    hal_pwm_fail_enable_t mode;
    hal_pwm_fail_source_t source;
    hal_pwm_level_t valid_level;
    hal_pwm_pn_level_t default_output;
    uint8_t filter_div;
} hal_pwm_fail_config_t;

1.20 PWM主中断回调类型

typedef void (*hal_pwm_irq_callback_t)(hal_pwm_handle_t *hpwm,
                                       uint32_t pending_bits);

说明：pending_bits 的含义由注册的 hal_pwm_irq_type_t 决定。回调可通过 hpwm->user_data 获取调用方上下文。

1.21 PWM参数更新中断回调类型

typedef void (*hal_pwm_update_irq_callback_t)(hal_pwm_handle_t *hpwm,
                                              uint32_t pending_groups);

说明：pending_groups 为参数更新待处理PWM组掩码，位0至位7对应PWM组0至PWM组7。回调可通过 hpwm->user_data 获取调用方上下文。

1.22 PWM句柄

typedef struct hal_pwm_handle hal_pwm_handle_t;

struct hal_pwm_handle {
    pwm_regs_t *instance;
    hal_pwm_state_t state;
    hal_pwm_irq_callback_t irq_callbacks[HAL_PWM_IRQ_TYPE_COUNT];
    hal_pwm_update_irq_callback_t update_irq_callback;
    void *user_data;
};

说明：回调运行在中断上下文中，不应阻塞。句柄不包含锁，同一PWM实例的寄存器或回调被多个执行上下文并发访问时，调用方负责同步。

2. HAL 接口规范

2.1 HAL层实现边界

• HAL层公开接口通过 hal_pwm_handle_t 保存PWM实例、运行状态、回调和调用方上下文，寄存器基地址通过 hpwm->instance 传递。

• 对不修改句柄内容的接口使用 const hal_pwm_handle_t *；这不影响通过 hpwm->instance 写硬件寄存器。

• HAL层使用 IM_HAL_PARAM_CHECK、IM_HAL_PARAM_CHECK_RETURN_VOID 和 IM_HAL_STATE_CHECK_RETURN 检查参数与状态；普通可失败接口返回 error_code_t，IRQ handler参数非法时直接返回。

• group 表示单PWM组选择值，只允许 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的一个位；HAL内部将其转换为0至7的 group_index。

• groups 表示多PWM组掩码，位0至位7分别对应PWM组0至PWM组7。完整位图写接口允许传入0，用于覆盖清除全部有效位；增量使能、关闭、设置、清除、屏蔽、解除屏蔽和状态清除接口要求至少选择一个PWM组。

• 硬件 WMODE 字段支持四种波形模式；HAL只提供普通边沿对齐和中心对齐互补模式，不提供边沿对齐推挽和中心对齐推挽模式，HAL配置接口会拒绝对应的编码2和编码3。

• 基础配置、单项setter和参数更新是独立操作。配置接口只写寄存器，不自动触发参数更新或启动输出；运行中修改波形或ADC触发阈值后，调用方必须显式触发对应更新。

• hal_pwm_group_init()、hal_pwm_set_clk_div() 和 hal_pwm_set_wave_mode() 在目标PWM组工作时返回 IM_ERR_BUSY；clock和参数更新接口不轮询busy、不重试、不等待完成。

• HAL层不提供内部锁。共享寄存器的读改写、分步配置和更新、回调注册与IRQ并发访问均由调用方根据执行环境完成同步。

2.2 初始化和生命周期

hal_pwm_init() 只初始化软件 handle；group 配置、参数装载和输出启动均由后续接口显式完成。

handle生命周期变化如下：

当前HAL不提供公开deinit接口。hal_pwm_soft_reset() 不清空callback和 user_data；再次调用 hal_pwm_init() 会重置软件handle并清空二者，但不会复位PWM硬件寄存器。

2.2.1 hal_pwm_init

error_code_t hal_pwm_init(hal_pwm_handle_t *hpwm, pwm_regs_t *instance);

功能说明： 初始化 PWM HAL 软件 handle 并绑定 PWM 实例。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm不能为空；instance必须为 PWM。

• 该接口只初始化软件状态，不访问硬件寄存器。

• 调用成功后状态为 HAL_PWM_STATE_READY，callback 和 user_data 被清空。

2.2.2 hal_pwm_state_get

error_code_t hal_pwm_state_get(const hal_pwm_handle_t *hpwm,
                               hal_pwm_state_t *state_out);

功能说明： 读取 PWM HAL handle 的生命周期状态。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；不要求句柄处于 HAL_PWM_STATE_READY；state_out不能为空。

2.3 基础配置

基础配置接口按单个PWM组写入波形寄存器，不触发参数更新，也不启动输出。

2.3.1 hal_pwm_group_init

error_code_t hal_pwm_group_init(hal_pwm_handle_t *hpwm,
                                const hal_pwm_group_t group,
                                const hal_pwm_init_config_t *config);

功能说明： 使用完整基础配置初始化一个 PWM group。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；config不能为空，时钟分频、波形模式、初始电平和空闲电平必须使用对应类型的有效值，param内各成员均为16位字段值；目标PWM组必须未处于工作状态。

• 目标 group 正在工作时返回 IM_ERR_BUSY。

• 接口只写配置寄存器，不触发 参数更新，也不启动输出。

• 中心对齐模式下，0死区自动替换为 HAL_PWM_CENTER_ALIGNED_DEAD_TIME。

2.3.2 hal_pwm_param_config

error_code_t hal_pwm_param_config(hal_pwm_handle_t *hpwm,
                                  const hal_pwm_group_t group,
                                  const hal_pwm_param_config_t *config);

功能说明： 配置一个 PWM group 的周期、P/N阈值和P/N死区。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；config不能为空，结构体内各计数值均为16位字段值。

• 接口只写参数寄存器；运行中修改后需另行触发波形比较参数更新。

• 中心对齐模式下，0死区自动替换为 HAL_PWM_CENTER_ALIGNED_DEAD_TIME。

• 特殊周期/阈值组合可自然形成静态高或静态低输出。

2.4 启停、时钟、计数器和参数更新

HAL的时钟和参数更新接口直接触发硬件，不轮询busy、不重试，也不等待更新完成。完整bitmap写接口允许写入0；增量动作接口要求至少选择一个group。

2.4.1 hal_pwm_enable

error_code_t hal_pwm_enable(hal_pwm_handle_t *hpwm, const uint32_t groups);

功能说明： 启动指定 PWM group 的波形输出。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；groups只允许位0至位7且不能为0。

• 接口设置 CLKEN 后触发 CLK_UPDATE，正常启动流程中的 CNTEN 由硬件同步更新。

• HAL 不检查 clock-update busy。

2.4.2 hal_pwm_disable

error_code_t hal_pwm_disable(hal_pwm_handle_t *hpwm, const uint32_t groups);

功能说明： 停止指定 PWM group 的波形输出。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；groups只允许位0至位7且不能为0。

• 接口清除 CLKEN 后触发 CLK_UPDATE，正常停止流程中的 CNTEN 由硬件同步更新。

• HAL 不检查 clock-update busy。

2.4.3 hal_pwm_set_clk_div

error_code_t hal_pwm_set_clk_div(hal_pwm_handle_t *hpwm,
                                 const hal_pwm_group_t group,
                                 const hal_pwm_clk_div_t div);

功能说明： 设置一个 PWM group 的时钟分频。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；div必须使用 hal_pwm_clk_div_t 定义的有效值；目标PWM组必须未处于工作状态。

• P/N 输出共享同一时钟分频，因此具有相同基频。

• 目标 group 工作时返回 IM_ERR_BUSY。

2.4.4 hal_pwm_get_clk_div

error_code_t hal_pwm_get_clk_div(const hal_pwm_handle_t *hpwm,
                                 const hal_pwm_group_t group,
                                 hal_pwm_clk_div_t *div_out);

功能说明： 读取一个 PWM group 的时钟分频。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；div_out不能为空。

2.4.5 hal_pwm_write_clk_enable_bits

error_code_t hal_pwm_write_clk_enable_bits(hal_pwm_handle_t *hpwm, const uint32_t groups);

功能说明： 覆盖写 clock-enable bitmap。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；groups只允许位0至位7且可为0。

• 该接口覆盖整个 CLKEN 有效 bitmap，不自动触发 CLK_UPDATE。

2.4.6 hal_pwm_is_clk_enabled

error_code_t hal_pwm_is_clk_enabled(const hal_pwm_handle_t *hpwm,
                                    const hal_pwm_group_t group,
                                    bool *enabled_out);

功能说明： 查询一个 PWM group 的 clock-enable 状态。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；enabled_out不能为空。

2.4.7 hal_pwm_clk_update

error_code_t hal_pwm_clk_update(hal_pwm_handle_t *hpwm);

功能说明： 触发一次 clock-enable update。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY。

• 该接口不检查 CLK_BUSY。

2.4.8 hal_pwm_write_counter_enable_bits

error_code_t hal_pwm_write_counter_enable_bits(hal_pwm_handle_t *hpwm, const uint32_t groups);

功能说明： 覆盖写计数器使能 bitmap。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；groups只允许位0至位7且可为0。

• 该接口覆盖整个 CNTEN 有效 bitmap。

2.4.9 hal_pwm_resume_counter

error_code_t hal_pwm_resume_counter(hal_pwm_handle_t *hpwm, const uint32_t groups);

功能说明： 直接使能指定 PWM group 的波形计数器。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；groups只允许位0至位7且不能为0。

• 该接口直接设置 CNTEN，可用于 Fail 源解除后的计数恢复。

2.4.10 hal_pwm_pause_counter

error_code_t hal_pwm_pause_counter(hal_pwm_handle_t *hpwm, const uint32_t groups);

功能说明： 直接关闭指定 PWM group 的波形计数器。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；groups只允许位0至位7且不能为0。

• 该接口直接清除 CNTEN，不修改 CLKEN。

2.4.11 hal_pwm_is_counter_enabled

error_code_t hal_pwm_is_counter_enabled(const hal_pwm_handle_t *hpwm,
                                        const hal_pwm_group_t group,
                                        bool *enabled_out);

功能说明： 查询一个 PWM group 的计数器使能状态。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；enabled_out不能为空。

2.4.12 hal_pwm_write_event_enable_bits

error_code_t hal_pwm_write_event_enable_bits(hal_pwm_handle_t *hpwm, const uint32_t groups);

功能说明： 覆盖写 ADC事件计数器使能 bitmap。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；groups只允许位0至位7且可为0。

• 该接口覆盖整个 EVTEN 有效 bitmap。

2.4.13 hal_pwm_event_enable

error_code_t hal_pwm_event_enable(hal_pwm_handle_t *hpwm, const uint32_t groups);

功能说明： 使能指定 PWM group 的 ADC事件计数器。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；groups只允许位0至位7且不能为0。

2.4.14 hal_pwm_event_disable

error_code_t hal_pwm_event_disable(hal_pwm_handle_t *hpwm, const uint32_t groups);

功能说明： 关闭指定 PWM group 的 ADC事件计数器。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；groups只允许位0至位7且不能为0。

2.4.15 hal_pwm_is_event_enabled

error_code_t hal_pwm_is_event_enabled(const hal_pwm_handle_t *hpwm,
                                      const hal_pwm_group_t group,
                                      bool *enabled_out);

功能说明： 查询一个 PWM group 的 ADC事件计数器使能状态。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；enabled_out不能为空。

2.4.16 hal_pwm_compare_param_update

error_code_t hal_pwm_compare_param_update(hal_pwm_handle_t *hpwm, const uint32_t groups);

功能说明： 触发指定 PWM group 的 compare 参数更新。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；groups只允许位0至位7且不能为0。

• 该接口不检查 PARAM_BUSY。

2.4.17 hal_pwm_event_param_update

error_code_t hal_pwm_event_param_update(hal_pwm_handle_t *hpwm, const uint32_t groups);

功能说明： 触发指定 PWM group 的 ADC event 参数更新。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；groups只允许位0至位7且不能为0。

• 该接口不检查 PARAM_BUSY。

2.4.18 hal_pwm_is_counter_working

error_code_t hal_pwm_is_counter_working(const hal_pwm_handle_t *hpwm,
                                        const hal_pwm_group_t group,
                                        bool *working_out);

功能说明： 查询一个 PWM group 的波形计数器工作状态。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；working_out不能为空。

2.5 模式、电平和 OSCR

中心对齐模式下 N 的有效输出由硬件按 P 的反相信号处理。HAL 不拦截 P/N 同电平配置；OSCR getter 会把硬件强制高编码 3 归一化为 HAL_PWM_OUTPUT_H。

2.5.1 hal_pwm_set_wave_mode

error_code_t hal_pwm_set_wave_mode(hal_pwm_handle_t *hpwm,
                                   const hal_pwm_group_t group,
                                   const hal_pwm_wave_mode_t mode);

功能说明： 设置一个 PWM group 的波形模式。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；mode必须使用 hal_pwm_wave_mode_t 定义的有效值；目标PWM组必须未处于工作状态。

• 目标 group 工作时返回 IM_ERR_BUSY。

• 切换到中心对齐模式前，调用方应先配置非0死区；本接口不提供兜底值。

2.5.2 hal_pwm_get_wave_mode

error_code_t hal_pwm_get_wave_mode(const hal_pwm_handle_t *hpwm,
                                   const hal_pwm_group_t group,
                                   hal_pwm_wave_mode_t *mode_out);

功能说明： 读取一个 PWM group 的波形模式。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；mode_out不能为空。

2.5.3 hal_pwm_set_init_level

error_code_t hal_pwm_set_init_level(hal_pwm_handle_t *hpwm,
                                    const hal_pwm_group_t group,
                                    const hal_pwm_pn_level_t level);

功能说明： 设置一个 PWM group 的 P/N 初始电平。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；level必须使用 hal_pwm_pn_level_t 定义的有效值。

2.5.4 hal_pwm_get_init_level

error_code_t hal_pwm_get_init_level(const hal_pwm_handle_t *hpwm,
                                    const hal_pwm_group_t group,
                                    hal_pwm_pn_level_t *level_out);

功能说明： 读取一个 PWM group 的 P/N 初始电平。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；level_out不能为空。

2.5.5 hal_pwm_set_idle_level

error_code_t hal_pwm_set_idle_level(hal_pwm_handle_t *hpwm,
                                    const hal_pwm_group_t group,
                                    const hal_pwm_pn_level_t level);

功能说明： 设置一个 PWM group 的 P/N 空闲电平。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；level必须使用 hal_pwm_pn_level_t 定义的有效值。

2.5.6 hal_pwm_get_idle_level

error_code_t hal_pwm_get_idle_level(const hal_pwm_handle_t *hpwm,
                                    const hal_pwm_group_t group,
                                    hal_pwm_pn_level_t *level_out);

功能说明： 读取一个 PWM group 的 P/N 空闲电平。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；level_out不能为空。

2.5.7 hal_pwm_set_p_init_level

error_code_t hal_pwm_set_p_init_level(hal_pwm_handle_t *hpwm,
                                      const hal_pwm_group_t group,
                                      const hal_pwm_level_t level);

功能说明： 设置一个 PWM group 的 P 初始电平。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；level必须使用 hal_pwm_level_t 定义的有效值。

2.5.8 hal_pwm_get_p_init_level

error_code_t hal_pwm_get_p_init_level(const hal_pwm_handle_t *hpwm,
                                      const hal_pwm_group_t group,
                                      hal_pwm_level_t *level_out);

功能说明： 读取一个 PWM group 的 P 初始电平。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；level_out不能为空。

2.5.9 hal_pwm_set_n_init_level

error_code_t hal_pwm_set_n_init_level(hal_pwm_handle_t *hpwm,
                                      const hal_pwm_group_t group,
                                      const hal_pwm_level_t level);

功能说明： 设置一个 PWM group 的 N 初始电平。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；level必须使用 hal_pwm_level_t 定义的有效值。

2.5.10 hal_pwm_get_n_init_level

error_code_t hal_pwm_get_n_init_level(const hal_pwm_handle_t *hpwm,
                                      const hal_pwm_group_t group,
                                      hal_pwm_level_t *level_out);

功能说明： 读取一个 PWM group 的 N 初始电平。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；level_out不能为空。

2.5.11 hal_pwm_set_p_idle_level

error_code_t hal_pwm_set_p_idle_level(hal_pwm_handle_t *hpwm,
                                      const hal_pwm_group_t group,
                                      const hal_pwm_level_t level);

功能说明： 设置一个 PWM group 的 P 空闲电平。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；level必须使用 hal_pwm_level_t 定义的有效值。

2.5.12 hal_pwm_get_p_idle_level

error_code_t hal_pwm_get_p_idle_level(const hal_pwm_handle_t *hpwm,
                                      const hal_pwm_group_t group,
                                      hal_pwm_level_t *level_out);

功能说明： 读取一个 PWM group 的 P 空闲电平。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；level_out不能为空。

2.5.13 hal_pwm_set_n_idle_level

error_code_t hal_pwm_set_n_idle_level(hal_pwm_handle_t *hpwm,
                                      const hal_pwm_group_t group,
                                      const hal_pwm_level_t level);

功能说明： 设置一个 PWM group 的 N 空闲电平。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；level必须使用 hal_pwm_level_t 定义的有效值。

2.5.14 hal_pwm_get_n_idle_level

error_code_t hal_pwm_get_n_idle_level(const hal_pwm_handle_t *hpwm,
                                      const hal_pwm_group_t group,
                                      hal_pwm_level_t *level_out);

功能说明： 读取一个 PWM group 的 N 空闲电平。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；level_out不能为空。

2.5.15 hal_pwm_set_p_oscr

error_code_t hal_pwm_set_p_oscr(hal_pwm_handle_t *hpwm,
                                const hal_pwm_group_t group,
                                const hal_pwm_output_control_t control);

功能说明： 设置一个 PWM group 的 P 输出状态控制。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；control必须使用 hal_pwm_output_control_t 定义的有效值。

• 运行中修改后需调用 hal_pwm_compare_param_update()。

2.5.16 hal_pwm_get_p_oscr

error_code_t hal_pwm_get_p_oscr(const hal_pwm_handle_t *hpwm,
                                const hal_pwm_group_t group,
                                hal_pwm_output_control_t *control_out);

功能说明： 读取一个 PWM group 的 P 输出状态控制。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；control_out不能为空。

• 硬件编码 2 和 3 均表示强制高，接口统一返回 HAL_PWM_OUTPUT_H。

2.5.17 hal_pwm_set_n_oscr

error_code_t hal_pwm_set_n_oscr(hal_pwm_handle_t *hpwm,
                                const hal_pwm_group_t group,
                                const hal_pwm_output_control_t control);

功能说明： 设置一个 PWM group 的 N 输出状态控制。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；control必须使用 hal_pwm_output_control_t 定义的有效值。

• 运行中修改后需调用 hal_pwm_compare_param_update()。

2.5.18 hal_pwm_get_n_oscr

error_code_t hal_pwm_get_n_oscr(const hal_pwm_handle_t *hpwm,
                                const hal_pwm_group_t group,
                                hal_pwm_output_control_t *control_out);

功能说明： 读取一个 PWM group 的 N 输出状态控制。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；control_out不能为空。

• 硬件编码 2 和 3 均表示强制高，接口统一返回 HAL_PWM_OUTPUT_H。

2.6 周期、阈值、死区和计数器

本节 setter 只写参数寄存器。运行中修改周期、阈值或死区后，应显式调用 hal_pwm_compare_param_update()。

2.6.1 hal_pwm_set_period_count

error_code_t hal_pwm_set_period_count(hal_pwm_handle_t *hpwm,
                                      const hal_pwm_group_t group,
                                      const uint16_t count);

功能说明： 设置一个 PWM group 的周期计数值。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；count为16位字段值，范围0至0xFFFF。

• 运行中修改后需调用 hal_pwm_compare_param_update()。

2.6.2 hal_pwm_get_period_count

error_code_t hal_pwm_get_period_count(const hal_pwm_handle_t *hpwm,
                                      const hal_pwm_group_t group,
                                      uint32_t *count_out);

功能说明： 读取一个 PWM group 的周期计数值。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；count_out不能为空。

2.6.3 hal_pwm_set_p_threshold

error_code_t hal_pwm_set_p_threshold(hal_pwm_handle_t *hpwm,
                                     const hal_pwm_group_t group,
                                     const uint16_t threshold);

功能说明： 设置一个 PWM group 的 P阈值。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；threshold为16位字段值，范围0至0xFFFF。

• 运行中修改后需调用 hal_pwm_compare_param_update()。

2.6.4 hal_pwm_set_n_threshold

error_code_t hal_pwm_set_n_threshold(hal_pwm_handle_t *hpwm,
                                     const hal_pwm_group_t group,
                                     const uint16_t threshold);

功能说明： 设置一个 PWM group 的 N阈值。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；threshold为16位字段值，范围0至0xFFFF。

• 运行中修改后需调用 hal_pwm_compare_param_update()。

2.6.5 hal_pwm_get_p_threshold

error_code_t hal_pwm_get_p_threshold(const hal_pwm_handle_t *hpwm,
                                     const hal_pwm_group_t group,
                                     uint32_t *threshold_out);

功能说明： 读取一个 PWM group 的 P阈值。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；threshold_out不能为空。

2.6.6 hal_pwm_get_n_threshold

error_code_t hal_pwm_get_n_threshold(const hal_pwm_handle_t *hpwm,
                                     const hal_pwm_group_t group,
                                     uint32_t *threshold_out);

功能说明： 读取一个 PWM group 的 N阈值。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；threshold_out不能为空。

2.6.7 hal_pwm_set_pn_threshold

error_code_t hal_pwm_set_pn_threshold(hal_pwm_handle_t *hpwm,
                                      const hal_pwm_group_t group,
                                      const uint16_t p_threshold,
                                      const uint16_t n_threshold);

功能说明： 设置一个 PWM group 的 P/N阈值。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；p_threshold、n_threshold均为16位字段值，范围0至0xFFFF。

• P/N阈值通过一次 32 bit 写入同时更新；运行中修改后需触发波形比较参数更新。

2.6.8 hal_pwm_get_pn_threshold

error_code_t hal_pwm_get_pn_threshold(const hal_pwm_handle_t *hpwm,
                                      const hal_pwm_group_t group,
                                      uint32_t *p_threshold_out,
                                      uint32_t *n_threshold_out);

功能说明： 读取一个 PWM group 的 P/N阈值。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；p_threshold_out、n_threshold_out均不能为空。

2.6.9 hal_pwm_set_p_dead_time

error_code_t hal_pwm_set_p_dead_time(hal_pwm_handle_t *hpwm,
                                     const hal_pwm_group_t group,
                                     const uint16_t dead_time);

功能说明： 设置一个 PWM group 的 P死区。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；dead_time范围1至0xFFFF。

• 死区不允许为 0；运行中修改后需触发波形比较参数更新。

2.6.10 hal_pwm_set_n_dead_time

error_code_t hal_pwm_set_n_dead_time(hal_pwm_handle_t *hpwm,
                                     const hal_pwm_group_t group,
                                     const uint16_t dead_time);

功能说明： 设置一个 PWM group 的 N死区。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；dead_time范围1至0xFFFF。

• 死区不允许为 0；运行中修改后需触发波形比较参数更新。

2.6.11 hal_pwm_get_p_dead_time

error_code_t hal_pwm_get_p_dead_time(const hal_pwm_handle_t *hpwm,
                                     const hal_pwm_group_t group,
                                     uint32_t *dead_time_out);

功能说明： 读取一个 PWM group 的 P死区。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；dead_time_out不能为空。

2.6.12 hal_pwm_get_n_dead_time

error_code_t hal_pwm_get_n_dead_time(const hal_pwm_handle_t *hpwm,
                                     const hal_pwm_group_t group,
                                     uint32_t *dead_time_out);

功能说明： 读取一个 PWM group 的 N死区。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；dead_time_out不能为空。

2.6.13 hal_pwm_set_pn_dead_time

error_code_t hal_pwm_set_pn_dead_time(hal_pwm_handle_t *hpwm,
                                      const hal_pwm_group_t group,
                                      const uint16_t p_dead_time,
                                      const uint16_t n_dead_time);

功能说明： 设置一个 PWM group 的 P/N死区。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；p_dead_time和 n_dead_time 范围均为1至0xFFFF。

• 两个死区均不允许为 0；接口通过一次 32 bit 写入同时更新。

2.6.14 hal_pwm_get_pn_dead_time

error_code_t hal_pwm_get_pn_dead_time(const hal_pwm_handle_t *hpwm,
                                      const hal_pwm_group_t group,
                                      uint32_t *p_dead_time_out,
                                      uint32_t *n_dead_time_out);

功能说明： 读取一个 PWM group 的 P/N死区。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；p_dead_time_out、n_dead_time_out均不能为空。

2.6.15 hal_pwm_get_counter

error_code_t hal_pwm_get_counter(const hal_pwm_handle_t *hpwm,
                                 const hal_pwm_group_t group,
                                 uint32_t *counter_out);

功能说明： 读取一个 PWM group 的当前PWM计数值。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；counter_out不能为空。

2.7 ADC trigger 和 debug

PWM HAL 只配置 trigger 时序、路径和 debug 路由，不配置 GPIO pinmux。debug IO0至IO3 分别对应 PA18至PA21，均使用 GPIO_FUNC_3。ADC事件计数器需通过 hal_pwm_event_enable() 单独使能。

2.7.1 hal_pwm_get_adc_trigger_timing

error_code_t hal_pwm_get_adc_trigger_timing(const hal_pwm_handle_t *hpwm,
                                            const hal_pwm_group_t group,
                                            uint32_t *threshold0_out,
                                            uint32_t *threshold1_out);

功能说明： 读取一个 PWM group 的ADC trigger阈值。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；threshold0_out、threshold1_out均不能为空。

2.7.2 hal_pwm_adc_trigger_timing_config

error_code_t hal_pwm_adc_trigger_timing_config(hal_pwm_handle_t *hpwm,
                                               const hal_pwm_group_t group,
                                               const uint16_t threshold0,
                                               const uint16_t threshold1);

功能说明： 配置一个 PWM group 的两个 ADC trigger阈值。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；threshold0、threshold1均为16位字段值，范围0至0xFFFF。

• 运行中修改后需调用 hal_pwm_event_param_update()。

• 同时使用两个阈值时，二者的时间/计数间隔应大于 ADC debug hold time。

2.7.3 hal_pwm_get_adc_trigger_path

error_code_t hal_pwm_get_adc_trigger_path(const hal_pwm_handle_t *hpwm,
                                          const hal_pwm_adc_trigger_t adc_trigger,
                                          hal_pwm_group_t *group_out);

功能说明： 读取一个 ADC trigger endpoint 当前选择的 PWM group。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group_out不能为空；adc_trigger必须使用 hal_pwm_adc_trigger_t 定义的有效值。

• 寄存器中的 group 编码超出 0至7 时返回 IM_ERR_INVALID_PARAM。

2.7.4 hal_pwm_adc_trigger_path_config

error_code_t hal_pwm_adc_trigger_path_config(hal_pwm_handle_t *hpwm,
                                             const hal_pwm_adc_trigger_t adc_trigger,
                                             const hal_pwm_group_t group);

功能说明： 为一个 ADC trigger endpoint 选择 PWM group 触发源。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；adc_trigger必须使用 hal_pwm_adc_trigger_t 定义的有效值。

2.7.5 hal_pwm_adc_debug_config

error_code_t hal_pwm_adc_debug_config(hal_pwm_handle_t *hpwm,
                                      const hal_pwm_adc_debug_config_t *config);

功能说明： 通过配置结构体设置一条 ADC trigger debug IO 路由。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；config不能为空，且 adc_trigger 和 debug_io 必须使用对应类型的有效值。

• 调用方需另行将对应 PA18至PA21 配置为 GPIO_FUNC_3。

2.7.6 hal_pwm_set_adc_debug_io

error_code_t hal_pwm_set_adc_debug_io(hal_pwm_handle_t *hpwm,
                                      const hal_pwm_adc_trigger_t adc_trigger,
                                      const hal_pwm_adc_debug_io_t debug_io);

功能说明： 设置一个 ADC trigger endpoint 的 debug IO 路由。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；adc_trigger必须使用 hal_pwm_adc_trigger_t 定义的有效值；debug_io必须使用 hal_pwm_adc_debug_io_t 定义的有效值。

• 调用方需另行将对应 PA18至PA21 配置为 GPIO_FUNC_3。

2.7.7 hal_pwm_get_adc_debug_io

error_code_t hal_pwm_get_adc_debug_io(const hal_pwm_handle_t *hpwm,
                                      const hal_pwm_adc_trigger_t adc_trigger,
                                      hal_pwm_adc_debug_io_t *debug_io_out);

功能说明： 读取一个 ADC trigger endpoint 的 debug IO 路由。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；debug_io_out不能为空；adc_trigger必须使用 hal_pwm_adc_trigger_t 定义的有效值。

2.7.8 hal_pwm_set_adc_debug_hold_count

error_code_t hal_pwm_set_adc_debug_hold_count(hal_pwm_handle_t *hpwm, const uint16_t hold_count);

功能说明： 设置四条 ADC debug 路由共享的 hold count。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；hold_count为16位字段值，范围0至0xFFFF。

• 该字段由四条 ADC trigger debug 路由共享。

• 两个 trigger阈值的间隔应大于该 hold time。

2.7.9 hal_pwm_get_adc_debug_hold_count

error_code_t hal_pwm_get_adc_debug_hold_count(const hal_pwm_handle_t *hpwm,
                                              uint32_t *hold_count_out);

功能说明： 读取四条 ADC debug 路由共享的 hold count。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；hold_count_out不能为空。

2.8 Global 控制

Global 用于暂停内部计数，不等同于 FAIL 急停。Global 有效期间 FAIL 仍可触发；清除 Global 后计数从暂停位置继续。

2.8.1 hal_pwm_write_global_bits

error_code_t hal_pwm_write_global_bits(hal_pwm_handle_t *hpwm, const uint32_t groups);

功能说明： 覆盖写完整 PWM Global 控制 bitmap。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；groups只允许位0至位7且可为0。

• 该接口覆盖整个 PWM_GLOBAL 有效 bitmap。

2.8.2 hal_pwm_set_global

error_code_t hal_pwm_set_global(hal_pwm_handle_t *hpwm, const uint32_t groups);

功能说明： 设置指定 PWM group 的 Global 控制，暂停内部计数。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；groups只允许位0至位7且不能为0。

2.8.3 hal_pwm_clear_global

error_code_t hal_pwm_clear_global(hal_pwm_handle_t *hpwm, const uint32_t groups);

功能说明： 清除指定 PWM group 的 Global 控制，恢复内部计数。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；groups只允许位0至位7且不能为0。

2.8.4 hal_pwm_is_global_set

error_code_t hal_pwm_is_global_set(const hal_pwm_handle_t *hpwm,
                                   const hal_pwm_group_t group,
                                   bool *set_out);

功能说明： 查询一个 PWM group 的 Global 控制状态。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；set_out不能为空。

2.9 FAIL 配置

IO valid level 和 filter divider 只作用于 IO FAIL。FAIL 源解除后的软复位、波形重配和计数器恢复由上层流程负责。

2.9.1 hal_pwm_fail_config

error_code_t hal_pwm_fail_config(hal_pwm_handle_t *hpwm,
                                 const hal_pwm_group_t group,
                                 const hal_pwm_fail_config_t *config);

功能说明： 配置一个 PWM group 的完整 Fail 保护路径。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；config不能为空，使能模式、失效源、有效电平和默认输出必须使用对应类型的有效值，filter_div范围为0至0xFF。

• 接口先配置 source、有效电平、默认输出和 filter，最后写入 enable mode。

2.9.2 hal_pwm_set_fail_enable_mode

error_code_t hal_pwm_set_fail_enable_mode(hal_pwm_handle_t *hpwm,
                                          const hal_pwm_group_t group,
                                          const hal_pwm_fail_enable_t mode);

功能说明： 设置一个 PWM group 的 Fail enable mode。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；mode必须使用 hal_pwm_fail_enable_t 定义的有效值。

2.9.3 hal_pwm_get_fail_enable_mode

error_code_t hal_pwm_get_fail_enable_mode(const hal_pwm_handle_t *hpwm,
                                          const hal_pwm_group_t group,
                                          hal_pwm_fail_enable_t *mode_out);

功能说明： 读取一个 PWM group 的 Fail enable mode。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；mode_out不能为空。

2.9.4 hal_pwm_set_fail_source

error_code_t hal_pwm_set_fail_source(hal_pwm_handle_t *hpwm,
                                     const hal_pwm_group_t group,
                                     const hal_pwm_fail_source_t source);

功能说明： 设置一个 PWM group 的 Fail source。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；source由一个IO失效源选择值和一个ADC失效源选择值按位或组成。

2.9.5 hal_pwm_get_fail_source

error_code_t hal_pwm_get_fail_source(const hal_pwm_handle_t *hpwm,
                                     const hal_pwm_group_t group,
                                     hal_pwm_fail_source_t *source_out);

功能说明： 读取一个 PWM group 的 Fail source。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；source_out不能为空。

2.9.6 hal_pwm_set_fail_io_valid_level

error_code_t hal_pwm_set_fail_io_valid_level(hal_pwm_handle_t *hpwm,
                                             const hal_pwm_group_t group,
                                             const hal_pwm_level_t valid_level);

功能说明： 设置一个 PWM group 的 IO Fail 有效电平。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；valid_level必须使用 hal_pwm_level_t 定义的有效值。

• 该配置只作用于 IO Fail。

2.9.7 hal_pwm_get_fail_io_valid_level

error_code_t hal_pwm_get_fail_io_valid_level(const hal_pwm_handle_t *hpwm,
                                             const hal_pwm_group_t group,
                                             hal_pwm_level_t *valid_level_out);

功能说明： 读取一个 PWM group 的 IO Fail 有效电平。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；valid_level_out不能为空。

2.9.8 hal_pwm_set_p_fail_default_output

error_code_t hal_pwm_set_p_fail_default_output(hal_pwm_handle_t *hpwm,
                                               const hal_pwm_group_t group,
                                               const hal_pwm_level_t level);

功能说明： 设置一个 PWM group 的 P Fail 默认输出电平。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；level必须使用 hal_pwm_level_t 定义的有效值。

• 中心对齐模式下，N 有效输出仍遵循硬件对 P 的反相规则。

2.9.9 hal_pwm_set_n_fail_default_output

error_code_t hal_pwm_set_n_fail_default_output(hal_pwm_handle_t *hpwm,
                                               const hal_pwm_group_t group,
                                               const hal_pwm_level_t level);

功能说明： 设置一个 PWM group 的 N Fail 默认输出电平。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；level必须使用 hal_pwm_level_t 定义的有效值。

• 中心对齐模式下，N 有效输出仍遵循硬件对 P 的反相规则。

2.9.10 hal_pwm_get_p_fail_default_output

error_code_t hal_pwm_get_p_fail_default_output(const hal_pwm_handle_t *hpwm,
                                               const hal_pwm_group_t group,
                                               hal_pwm_level_t *level_out);

功能说明： 读取一个 PWM group 的 P Fail 默认输出电平。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；level_out不能为空。

2.9.11 hal_pwm_get_n_fail_default_output

error_code_t hal_pwm_get_n_fail_default_output(const hal_pwm_handle_t *hpwm,
                                               const hal_pwm_group_t group,
                                               hal_pwm_level_t *level_out);

功能说明： 读取一个 PWM group 的 N Fail 默认输出电平。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；level_out不能为空。

2.9.12 hal_pwm_set_fail_default_output

error_code_t hal_pwm_set_fail_default_output(hal_pwm_handle_t *hpwm,
                                             const hal_pwm_group_t group,
                                             const hal_pwm_pn_level_t level);

功能说明： 设置一个 PWM group 的 P/N Fail 默认输出电平。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；level必须使用 hal_pwm_pn_level_t 定义的有效值。

• 中心对齐模式下，N 有效输出仍遵循硬件对 P 的反相规则。

2.9.13 hal_pwm_get_fail_default_output

error_code_t hal_pwm_get_fail_default_output(const hal_pwm_handle_t *hpwm,
                                             const hal_pwm_group_t group,
                                             hal_pwm_pn_level_t *level_out);

功能说明： 读取一个 PWM group 的 P/N Fail 默认输出电平。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；level_out不能为空。

2.9.14 hal_pwm_set_fail_io_filter_div

error_code_t hal_pwm_set_fail_io_filter_div(hal_pwm_handle_t *hpwm,
                                            const hal_pwm_group_t group,
                                            const uint8_t div);

功能说明： 设置一个 PWM group 的 IO Fail filter divider。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；div范围为0至0xFF。

• 该配置只作用于 IO Fail。

2.9.15 hal_pwm_get_fail_io_filter_div

error_code_t hal_pwm_get_fail_io_filter_div(const hal_pwm_handle_t *hpwm,
                                            const hal_pwm_group_t group,
                                            uint32_t *div_out);

功能说明： 读取一个 PWM group 的 IO Fail filter divider。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；div_out不能为空。

2.10 中断管理

ADC trigger 中断

ADC trigger status 为 W1C；中断 mask 位取 1 表示 masked，取 0 表示 unmasked。

2.10.1 hal_pwm_clear_adc_trigger_interrupt_status

error_code_t hal_pwm_clear_adc_trigger_interrupt_status(hal_pwm_handle_t *hpwm,
                                                        const uint32_t groups);

功能说明： 清除指定 PWM group 的 ADC trigger 中断状态。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；groups只允许位0至位7且不能为0。

2.10.2 hal_pwm_is_adc_trigger_interrupt_pending

error_code_t hal_pwm_is_adc_trigger_interrupt_pending(const hal_pwm_handle_t *hpwm,
                                                      const hal_pwm_group_t group,
                                                      bool *pending_out);

功能说明： 查询一个 PWM group 的ADC trigger 中断 pending 状态。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；pending_out不能为空。

2.10.3 hal_pwm_adc_trigger_interrupt_mask

error_code_t hal_pwm_adc_trigger_interrupt_mask(hal_pwm_handle_t *hpwm, const uint32_t groups);

功能说明： 屏蔽指定 PWM group 的 ADC trigger 中断。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；groups只允许位0至位7且不能为0。

2.10.4 hal_pwm_adc_trigger_interrupt_unmask

error_code_t hal_pwm_adc_trigger_interrupt_unmask(hal_pwm_handle_t *hpwm, const uint32_t groups);

功能说明： 解除指定 PWM group 的 ADC trigger 中断屏蔽。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；groups只允许位0至位7且不能为0。

2.10.5 hal_pwm_is_adc_trigger_interrupt_masked

error_code_t hal_pwm_is_adc_trigger_interrupt_masked(const hal_pwm_handle_t *hpwm,
                                                     const hal_pwm_group_t group,
                                                     bool *masked_out);

功能说明： 查询一个 PWM group 的ADC trigger 中断 mask 状态。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；masked_out不能为空。

Global 中断

Global 中断状态由软件显式清除；中断 mask 位取 1 表示 masked，取 0 表示 unmasked。

2.10.6 hal_pwm_clear_global_interrupt_status

error_code_t hal_pwm_clear_global_interrupt_status(hal_pwm_handle_t *hpwm, const uint32_t groups);

功能说明： 清除指定 PWM group 的 Global 中断状态。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；groups只允许位0至位7且不能为0。

• 状态按 W1C 语义清除。

2.10.7 hal_pwm_is_global_interrupt_pending

error_code_t hal_pwm_is_global_interrupt_pending(const hal_pwm_handle_t *hpwm,
                                                 const hal_pwm_group_t group,
                                                 bool *pending_out);

功能说明： 查询一个 PWM group 的 Global 中断 pending 状态。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；pending_out不能为空。

2.10.8 hal_pwm_global_interrupt_mask

error_code_t hal_pwm_global_interrupt_mask(hal_pwm_handle_t *hpwm, const uint32_t groups);

功能说明： 屏蔽指定 PWM group 的 Global 中断。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；groups只允许位0至位7且不能为0。

2.10.9 hal_pwm_global_interrupt_unmask

error_code_t hal_pwm_global_interrupt_unmask(hal_pwm_handle_t *hpwm, const uint32_t groups);

功能说明： 解除指定 PWM group 的 Global 中断屏蔽。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；groups只允许位0至位7且不能为0。

2.10.10 hal_pwm_is_global_interrupt_masked

error_code_t hal_pwm_is_global_interrupt_masked(const hal_pwm_handle_t *hpwm,
                                                const hal_pwm_group_t group,
                                                bool *masked_out);

功能说明： 查询一个 PWM group 的 Global 中断 mask 状态。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；masked_out不能为空。

FAIL 状态与中断

每个 PWM 组的 FAIL 状态占 2 bit，低 bit 为 IO FAIL，高 bit 为 ADC FAIL；状态清除使用 W1C 语义。

2.10.11 hal_pwm_clear_fail_status_bits

error_code_t hal_pwm_clear_fail_status_bits(hal_pwm_handle_t *hpwm, const uint16_t status_bits);

功能说明： 按原始 16 bit packed bitmap 清除 Fail 状态。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；status_bits为非0的16位 FST 打包位图。

• 参数直接对应 FST packed W1C bitmap。

2.10.12 hal_pwm_clear_fail_status

error_code_t hal_pwm_clear_fail_status(hal_pwm_handle_t *hpwm,
                                       const hal_pwm_group_t group,
                                       const hal_pwm_fail_bits_t fail_bits);

功能说明： 清除一个 PWM group 中选定的 Fail 状态。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；fail_bits必须使用 hal_pwm_fail_bits_t 定义的有效值；fail_bits只能选择IO、ADC或两者，不能为 HAL_PWM_FAIL_BIT_NONE。

2.10.13 hal_pwm_get_fail_status

error_code_t hal_pwm_get_fail_status(const hal_pwm_handle_t *hpwm,
                                     const hal_pwm_group_t group,
                                     hal_pwm_fail_bits_t *fail_bits_out);

功能说明： 读取一个 PWM group 的 Fail 状态。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；fail_bits_out不能为空。

2.10.14 hal_pwm_fail_interrupt_mask

error_code_t hal_pwm_fail_interrupt_mask(hal_pwm_handle_t *hpwm,
                                         const hal_pwm_group_t group,
                                         const hal_pwm_fail_bits_t fail_bits);

功能说明： 屏蔽一个 PWM group 中选定的 Fail 中断。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；fail_bits必须使用 hal_pwm_fail_bits_t 定义的有效值；fail_bits只能选择IO、ADC或两者，不能为 HAL_PWM_FAIL_BIT_NONE。

2.10.15 hal_pwm_fail_interrupt_unmask

error_code_t hal_pwm_fail_interrupt_unmask(hal_pwm_handle_t *hpwm,
                                           const hal_pwm_group_t group,
                                           const hal_pwm_fail_bits_t fail_bits);

功能说明： 解除一个 PWM group 中选定的 Fail 中断屏蔽。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；fail_bits必须使用 hal_pwm_fail_bits_t 定义的有效值；fail_bits只能选择IO、ADC或两者，不能为 HAL_PWM_FAIL_BIT_NONE。

2.10.16 hal_pwm_get_fail_interrupt_mask

error_code_t hal_pwm_get_fail_interrupt_mask(const hal_pwm_handle_t *hpwm,
                                             const hal_pwm_group_t group,
                                             hal_pwm_fail_bits_t *fail_bits_out);

功能说明： 读取一个 PWM group 的 Fail 中断 mask。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；fail_bits_out不能为空。

update 中断

HAL 使用实际 PWM 周期数表示 update 中断间隔，范围为 1至0x20000；硬件 IRQ_CNTn 保存 count - 1。

2.10.17 hal_pwm_clear_update_interrupt_status

error_code_t hal_pwm_clear_update_interrupt_status(hal_pwm_handle_t *hpwm, const uint32_t groups);

功能说明： 清除指定 PWM group 的 update 中断状态。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；groups只允许位0至位7且不能为0。

2.10.18 hal_pwm_is_update_interrupt_pending

error_code_t hal_pwm_is_update_interrupt_pending(const hal_pwm_handle_t *hpwm,
                                                 const hal_pwm_group_t group,
                                                 bool *pending_out);

功能说明： 查询一个 PWM group 的 update 中断 pending 状态。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；pending_out不能为空。

2.10.19 hal_pwm_update_interrupt_mask

error_code_t hal_pwm_update_interrupt_mask(hal_pwm_handle_t *hpwm, const uint32_t groups);

功能说明： 屏蔽指定 PWM group 的 update 中断。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；groups只允许位0至位7且不能为0。

2.10.20 hal_pwm_update_interrupt_unmask

error_code_t hal_pwm_update_interrupt_unmask(hal_pwm_handle_t *hpwm, const uint32_t groups);

功能说明： 解除指定 PWM group 的 update 中断屏蔽。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；groups只允许位0至位7且不能为0。

2.10.21 hal_pwm_is_update_interrupt_masked

error_code_t hal_pwm_is_update_interrupt_masked(const hal_pwm_handle_t *hpwm,
                                                const hal_pwm_group_t group,
                                                bool *masked_out);

功能说明： 查询一个 PWM group 的 update 中断 mask 状态。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；masked_out不能为空。

2.10.22 hal_pwm_set_update_irq_count

error_code_t hal_pwm_set_update_irq_count(hal_pwm_handle_t *hpwm,
                                          const hal_pwm_group_t group,
                                          const uint32_t count);

功能说明： 设置一个 PWM group 的 update 中断周期数。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；count范围为 HAL_PWM_UPDATE_IRQ_COUNT_MIN 至 HAL_PWM_UPDATE_IRQ_COUNT_MAX。

• HAL 写入硬件的值为 count - 1。

2.10.23 hal_pwm_get_update_irq_count

error_code_t hal_pwm_get_update_irq_count(const hal_pwm_handle_t *hpwm,
                                          const hal_pwm_group_t group,
                                          uint32_t *count_out);

功能说明： 读取一个 PWM group 的 update 中断周期数。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY；group必须是 HAL_PWM_GROUP_0 至 HAL_PWM_GROUP_7 中的单个选择值；count_out不能为空。

• HAL 对硬件原始字段加 1 后返回实际周期数。

callback 与 IRQ handler

PWM主中断和参数更新中断使用两个独立IRQ。HAL不负责平台IRQ注册；上层调用者应将两个handler分别注册到对应IRQ，并将同一个handle作为两个handler的 user_ctx。

2.10.24 hal_pwm_register_irq_callback

error_code_t hal_pwm_register_irq_callback(hal_pwm_handle_t *hpwm,
                                           const hal_pwm_irq_type_t type,
                                           hal_pwm_irq_callback_t callback);

功能说明： 注册或注销一种 PWM 主中断 callback。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；不要求句柄处于 HAL_PWM_STATE_READY；type必须使用 hal_pwm_irq_type_t 定义的有效值；callback可为NULL，表示清除该类型的回调。

• 该 callback 对应 IRQ_PWM；每种 hal_pwm_irq_type_t 只有一个注册位置。

• 注册只修改软件 handle，可在 RESET 或 READY 状态调用。

2.10.25 hal_pwm_register_update_irq_callback

error_code_t hal_pwm_register_update_irq_callback(hal_pwm_handle_t *hpwm,
                                                  hal_pwm_update_irq_callback_t callback);

功能说明： 注册或注销 PWM update 中断 callback。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；不要求句柄处于 HAL_PWM_STATE_READY；callback可为NULL，表示清除参数更新回调。

• 该 callback 对应独立的 IRQ_PWM_UPDATE。

• 注册只修改软件 handle，可在 RESET 或 READY 状态调用。

2.10.26 hal_pwm_irq_handler

void hal_pwm_irq_handler(uint32_t irq_id, void *user_ctx);

功能说明： 处理 PWM 主中断并按类型分发 callback。

参数表：

返回值表：

补充说明：

• 参数约束：user_ctx必须指向已绑定合法PWM实例的 hal_pwm_handle_t；irq_id当前未使用；不要求句柄处于 HAL_PWM_STATE_READY。

• 分发顺序为 IO Fail、ADC Fail、Global、ADC trigger。每种类型最多调用一次 callback。

• Fail 和 ADC trigger status 在 callback 前清除；Global status 留给恢复流程显式处理。

• 未注册 callback 时仍处理硬件状态，但跳过函数调用。

2.10.27 hal_pwm_update_irq_handler

void hal_pwm_update_irq_handler(uint32_t irq_id, void *user_ctx);

功能说明： 处理 PWM update 中断并分发 callback。

参数表：

返回值表：

补充说明：

• 参数约束：user_ctx必须指向已绑定合法PWM实例的 hal_pwm_handle_t；irq_id当前未使用；不要求句柄处于 HAL_PWM_STATE_READY。

• 接口先清除有效 update pending status，再以完整 group mask 调用一次 callback。

2.11 软复位与 dump

软复位后 handle 进入 HAL_PWM_STATE_RESET。dump 接口仅在 SDK 和 PWM 两级 debug helper 宏同时开启时可用。

2.11.1 hal_pwm_soft_reset

error_code_t hal_pwm_soft_reset(hal_pwm_handle_t *hpwm);

功能说明： 触发 PWM 模块软复位。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；句柄必须处于 HAL_PWM_STATE_READY。

• 复位请求发出后，handle 状态立即设为 HAL_PWM_STATE_RESET。

• 重新配置 PWM 前应等待硬件释放 reset request、清除 reset status，并重新调用 hal_pwm_init()。

2.11.2 hal_pwm_get_soft_reset

error_code_t hal_pwm_get_soft_reset(const hal_pwm_handle_t *hpwm, uint32_t *reset_out);

功能说明： 读取软复位控制位。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；不要求句柄处于 HAL_PWM_STATE_READY；reset_out不能为空。

• handle 处于 HAL_PWM_STATE_RESET 时仍可调用；0 表示已请求复位，1 表示硬件已释放请求。

2.11.3 hal_pwm_get_soft_reset_status

error_code_t hal_pwm_get_soft_reset_status(const hal_pwm_handle_t *hpwm, uint32_t *status_out);

功能说明： 读取软复位状态。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；不要求句柄处于 HAL_PWM_STATE_READY；status_out不能为空。

• handle 处于 HAL_PWM_STATE_RESET 时仍可调用；0 表示存在未清除的软复位状态。

2.11.4 hal_pwm_clear_soft_reset_status

error_code_t hal_pwm_clear_soft_reset_status(hal_pwm_handle_t *hpwm);

功能说明： 清除 PWM 软复位状态。

参数表：

返回值表：

补充说明：

• 参数约束：hpwm必须绑定合法PWM实例；不要求句柄处于 HAL_PWM_STATE_READY。

2.11.5 hal_pwm_regs_dump

error_code_t hal_pwm_regs_dump(const hal_pwm_handle_t *hpwm);

功能说明： 按 group 打印 PWM 配置与运行状态。

参数表：

返回值表：

补充说明：

• 参数约束：启用SDK和PWM两级调试辅助宏时，hpwm必须绑定合法PWM实例；不要求句柄处于 HAL_PWM_STATE_READY；未启用时接口返回 IM_ERR_UNSUPPORTED。

• 受 CONFIG_SDK_ENABLE_DEBUG_HELPERS 和 CONFIG_PWM_ENABLE_DEBUG_HELPERS 共同控制。

• dump 跳过 write-only trigger 寄存器，读取 status 不会清除状态。

2.11.6 hal_pwm_irq_regs_dump

error_code_t hal_pwm_irq_regs_dump(const hal_pwm_handle_t *hpwm);

功能说明： 按 group 打印 PWM 中断状态、mask 和 callback 地址。

参数表：

返回值表：

补充说明：

• 参数约束：启用SDK和PWM两级调试辅助宏时，hpwm必须绑定合法PWM实例；不要求句柄处于 HAL_PWM_STATE_READY；未启用时接口返回 IM_ERR_UNSUPPORTED。

• 受 CONFIG_SDK_ENABLE_DEBUG_HELPERS 和 CONFIG_PWM_ENABLE_DEBUG_HELPERS 共同控制。

3. 当前实现约束与行为说明

3.1 模式组合

中心对齐模式下P/N相同电平配置由硬件兜底；hal_pwm_set_wave_mode() 不自动修改死区，运行中切换模式前应先配置死区。

3.2 中断与回调

• PWM主中断和参数更新中断分别使用 hal_pwm_irq_handler() 和 hal_pwm_update_irq_handler()，对应两个独立IRQ入口。

• 主中断按IO FAIL、ADC FAIL、Global、ADC触发的顺序处理；每种类型最多调用一次callback，并通过pending位图一次传递全部相关PWM组。

• IO/ADC FAIL和ADC触发状态在callback前清除；Global状态留给恢复流程显式清除；参数更新状态在参数更新callback前清除。

• callback运行在中断上下文中，不应阻塞；callback注册、注销以及与IRQ并发访问同一handle时，由调用方负责同步。