RTOS_PWM使用参考

REVISION HISTORY¶

Revision No.	Description	Date
1.0	Initial release	04/09/2025

1. 概述¶

PWM (Pulse Width Modulation) 模块用于产生脉宽波形，可通过改变频率和占空比来改变输出的电流、电压进而实现控制电机转速、液晶屏调光等功能；SigmaStar的PWM模块同时具备Group功能(细分为sync 、round、hold、stop)，即每4个或者6个channel的PWM可绑定成一组，实现4路或6路PWM同步产生或停止。

设备和硬件组别的关系如下表所示：

PWM Group	bank addr	Channel
HW PWM group0	1119H	channel 0 ~ 3
HW PWM group1	111AH	channel 4 ~ 7
HW PWM group2	111CH	channel 8 ~ 11
HW PWM group3	112BH	channel 12 ~ 16

2. 关键字¶

sysdesc：

RTOS用于描述外设硬件属性的文件,外设节点中包含的属性值可用于外设的配置, 类似于linux的设备树文件。

padmux：

引脚复用，用于将模块功能引脚连接到具体的外部引脚上面，打通信号连接。

Dead Time：

PWM 死区时间（Dead Time）是指在PWM信号切换过程中，两个相邻的输出信号之间存在的时间间隔。它用于防止功率开关器件（如MOSFET或IGBT）在切换过程中同时导通，从而避免短路和损坏。

3. 功能描述¶

3.1. 概述¶

支持PWM的channel数量为20个，其中channel 0~17支持加入各自的Group，详见Group与channel对应关系
PWM channel 12~17支持最大设定值为(OSCCLK / 0x3FF)的Dead Time设定及刹车功能，例如OSCCLK = 12MHz，则范围是0~85250ns
支持double buffer来防止产生错误波形，即波形会等待当前波形完全生成之后更新
支持shift功能，即波形可以设置相位,相位会影响占空比,实际占空比 = 设置占空比 - 相位
支持sync功能，即Group内的PWM在同一个时刻产生波形，一般一组Group中会包含4个channel的PWM
支持round功能，即同Group内的PWM会在产生特定数量的脉冲后停止
支持hold功能，即同Group内的PWM会在完成当前周期的波形后暂停，常用于改变波形的设定，可设定暂停时间内的高低电平
支持stop功能，即同Group内的PWM会紧急停止

3.2. 频率和占空比¶

频率（frequency）

每秒钟信号从高电平到低电平再回到高电平的次数。
占空比（duty cycle）

高电平持续时间和低电平持续时间之间的比例。

举例说明

假设PWM的OSCCLK频率为12M，那么可设置的频率范围为：0.0007Hz~6MHz；

设定PWM0和PWM1为频率120Hz，占空比25%的波形，且PWM1相对于PWM0有180°的相位偏移，那么各参数配置如下：

	period	duty	shift
PWM0	120Hz	25%	0%
PWM1	120Hz	75%	50%

对于channel 0~17支持的OSCCLK(Hz)为：86M、24M、12M、6M、3M、1.5M、750K;

PWM的工作频率范围是(OSCCLK/2)到(OSCCLK/2^34)，实际工作频率范围如下:

clk-freq	PWM freq range
86MHz	0.0050Hz ~ 43MHz
24MHz	0.0013Hz ~ 12MHz
12MHz	0.0007Hz ~ 6MHz
6MHz	0.00035Hz ~ 3MHz
3MHz	0.00017Hz ~ 1.5Mhz
1.5MHz	0.000087Hz ~ 750KHz
750KHz	0.000044Hz ~ 375KHz

产生的波形如下图：

3.3. 普通精度模式¶

rtos config中不开启CONFIG_SSTAR_PWM_EXTEND，则使用普通精度模式，该模式下配置PWM的period的单位为Hz，duty cycle的单位为百分比。

假设要设置PWM0频率为10000HZ，占空比为50%，则：

period = 10000

duty cycle = 50

3.4. 高精度模式¶

rtos config中开启CONFIG_SSTAR_PWM_EXTEND选项时，则使用高精度模式，该模式下配置PWM的period和duty_cycle均使用纳秒为单位，所以要先计算周期和占空比的值。

假设要设置PWM0频率为10000.5HZ，占空比为49.5%，则：

period = 10^9 ÷ 10000.5 = 99995

duty cycle = 99995 * 49.5% = 49498

由此可见，高精度模式的优势在于参数设定支持到小数。

3.5. GROUP相关概念¶

3.5.1. Sync mode¶

sync mode可以将每个pwm channel加入到各自的Group群组中，完成同时对多个PWM进行控制的目的，一个Group有4个pwm channel，且Group与channel对应关系如下：

Group	Group Member
Group0	PWM0、PWM1、PWM2、PWM3
Group1	PWM4、PWM5、PWM6、PWM7
Group2	PWM8、PWM9、PWM10、PWM11
Group3	PWM12、PWM13、PWM14、PWM15、PWM16、PWM17

3.5.2. Hold mode¶

Group的Hold功能会在pwm完成当前周期的波形后停止，并触发中断，此时可以改变各channel波形的配置以保持同步，完成修改后会关闭hold 功能，pwm就会重新产生新的波形，每组group都有自己独立的hold功能。

3.5.3. Round mode¶

round功能会在同group内的所有channel完成一定数量的脉冲后停止，每组group都有自己独立的round功能。

3.5.4. Stop mode¶

stop功能可以让当前group中的PWM立即停止（不会等当前周期完成）并维持结束时的电平，每组group都有自己独立的stop功能。

注意：stop 时间不建议太长，尤其是pwm停止后维持的电平为高电平时。

3.6. 死区时间¶

基于两路互补信号产生Dead Time，正向信号基于PWM clock的相对上升沿产生delay，反向信号基于PWM clock的相对下降沿产生delay

4. RTOS用法介绍¶

4.1 DRIVER PATH¶

sc/driver/sysdriver/pwm/drv/pub/drv_pwm.h
sc/driver/sysdriver/pwm/drv/src/drv_pwm.c
sc/driver/sysdriver/pwm/drv/src/drv_pwm_test.c
sc/driver/sysdriver/pwm/hal/chipname/src/hal_pwm.c
sc/driver/sysdriver/pwm/hal/chipname/inc/hal_pwm.h
sc/driver/sysdriver/pwm/hal/chipname/inc/hal_pwm_cfg.h

4.2. CONFIG配置¶

#make menuconfig

# Feature_Name = [DRV] PWM driver support
# Description = PWM driver support
# Option_Selection = TRUE, FALSE
CONFIG_PWM_SUPPORT = TRUE       //使能PWM驱动
CONFIG_SSTAR_PWM_DDT = TRUE     //使能dead time功能
CONFIG_SSTAR_PWM_EXTEND = TRUE  //TRUE：高精度模式，FLASE：低精度模式

4.3 SYSDESC配置¶

chipname_xxx.sys文件是用于描述外设硬件属性的文件，外设节点中包含的属性值可用于外设的配置，类似Linux的设备树，该文件位于sc/driver/sysdriver/sysdesc/hal/chipname/pub, 下文以pwm12举例:

<pwm12>
    [reg_u32_u16] 0x1F205600 0x40;
    [interrupts_u32] INT_IRQ_PWM_GROUP3;
    [camclk_u16] CAMCLK_pwm;
    [group_u32] 3;
    [spwm_group_u32] 0xFFFF;
    [clk_level_u8] 0;
    [ddt_reg_u32] 0x1F203600;
    [idle_status_u8] 0, 0;
    [padmux_u16] PINMUX_FOR_UNKNOWN_MODE;
    [status_u8] 1;

pwm驱动中支持配置的属性如下表：

属性	描述	设定值	备注
reg_u32_u16	指定pwm bank地址	0x2205600	禁止修改
interrupts_u32	指定硬件中断号	INT_IRQ_PWM_GROUP3	禁止修改
camclk_u16	指定时钟源	CAMCLK_pwm	禁止修改
group_u32	选择是否加入group	按照Group与channel对应关系赋值相应的group index，0xFFFF表示不加入	可根据需要修改，加入group或加入spwm group只能二选一
spwm_group_u32	选择是否加入spwm group	0xFFFF	加入group或加入spwm group只能二选一
clk_level_u8	选择时钟源	pwm0_17可选06分别对应12M/6M/3M/1.5M/750K/86M/ 24M	pwm0~17选择必须一致
ddt_reg_u32	指定dead time bank地址	0x2203600	禁止修改
idle_status_u8	选择dead time波形idle时的电平状态	0-低电平；1-高电平	可根据需要修改
status_u8	选择是否使能驱动	1:enable；0:disable	可根据需要修改

4.4 PADMUX配置¶

CONFIG配置：CONFIG_PADMUX_SUPPORT=TRUE

如果chipname_xxx.sys文件配置了属性<padmux>，那么PADMUX的设定直接在此配置：

<padmux>
    [schematic_u32_u32_u32]
              PAD_GPIOC_00   PINMUX_FOR_PWM0_MODE_1    MDRV_PUSE_PWM0，
              PAD_GPIOC_01   PINMUX_FOR_PWM1_MODE_1    MDRV_PUSE_PWM1，
              PAD_GPIOC_02   PINMUX_FOR_PWM2_MODE_1    MDRV_PUSE_PWM2，
              PAD_GPIOC_03   PINMUX_FOR_PWM3_MODE_1    MDRV_PUSE_PWM3，
              PAD_GPIOC_04   PINMUX_FOR_PWM4_MODE_1    MDRV_PUSE_PWM4，
              PAD_GPIOC_05   PINMUX_FOR_PWM5_MODE_1    MDRV_PUSE_PWM5，
              PAD_GPIOC_06   PINMUX_FOR_PWM6_MODE_1    MDRV_PUSE_PWM6，
              PAD_GPIOC_07   PINMUX_FOR_PWM7_MODE_1    MDRV_PUSE_PWM7，
              PAD_GPIOC_08   PINMUX_FOR_PWM8_MODE_1    MDRV_PUSE_PWM8，
              PAD_OUTP_CH0   PINMUX_FOR_PWM9_MODE_1    MDRV_PUSE_PWM9，
              PAD_GPIOA_00   PINMUX_FOR_PWM10_MODE_2   MDRV_PUSE_PWM10，
              PAD_GPIOA_01   PINMUX_FOR_PWM11_MODE_2   MDRV_PUSE_PWM11，
              PAD_GPIOA_02   PINMUX_FOR_PWM12_MODE_2   MDRV_PUSE_PWM12，
              PAD_GPIOA_03   PINMUX_FOR_PWM13_MODE_2   MDRV_PUSE_PWM13，
              PAD_GPIOA_04   PINMUX_FOR_PWM14_MODE_2   MDRV_PUSE_PWM14，
              PAD_GPIOA_05   PINMUX_FOR_PWM15_MODE_2   MDRV_PUSE_PWM15，
              PAD_GPIOA_06   PINMUX_FOR_PWM16_MODE_2   MDRV_PUSE_PWM16，
              PAD_GPIOA_07   PINMUX_FOR_PWM17_MODE_2   MDRV_PUSE_PWM17，

              //dead time
              PAD_GPIOE_17 PINMUX_FOR_PWM_COMP0_MODE_1 MDRV_PUSE_PWMOUT0_P，
              PAD_GPIOE_18 PINMUX_FOR_PWM_COMP0_MODE_1 MDRV_PUSE_PWMOUT0_N，
              PAD_GPIOE_23 PINMUX_FOR_PWM_COMP1_MODE_1 MDRV_PUSE_PWMOUT1_P，
              PAD_GPIOE_24 PINMUX_FOR_PWM_COMP1_MODE_1 MDRV_PUSE_PWMOUT1_N，
              PAD_GPIOA_00 PINMUX_FOR_PWM_COMP2_MODE_1 MDRV_PUSE_PWMOUT2_P，
              PAD_GPIOA_01 PINMUX_FOR_PWM_COMP2_MODE_1 MDRV_PUSE_PWMOUT2_N，
              PAD_GPIOA_08 PINMUX_FOR_PWM_COMP3_MODE_2 MDRV_PUSE_PWMOUT3_P，
              PAD_GPIOA_09 PINMUX_FOR_PWM_COMP3_MODE_2 MDRV_PUSE_PWMOUT3_N，
              PAD_EMMC_RST PINMUX_FOR_PWM_COMP4_MODE_1 MDRV_PUSE_PWMOUT4_P，
              PAD_EMMC_CLK PINMUX_FOR_PWM_COMP4_MODE_1 MDRV_PUSE_PWMOUT4_N，
              PAD_EMMC_D0  PINMUX_FOR_PWM_COMP5_MODE_1 MDRV_PUSE_PWMOUT5_P，
              PAD_EMMC_D5  PINMUX_FOR_PWM_COMP5_MODE_1 MDRV_PUSE_PWMOUT5_N，

              //break
              PAD_GPIOA_12 PINMUX_FOR_PWM_INT_MODE_1 MDRV_PUSE_PWMADC_INT，
              PAD_GPIOA_13 PINMUX_FOR_PWM_INT_MODE_1 MDRV_PUSE_PWMOUT_INT;
    [status_u8] 1;

第一列为引脚索引号，可以在sc/drivers/sysdriver/gpio/hal/chipname/pub/gpio.h中查询；

第二列为模式定义，可以在sc/drivers/sysdriver/gpio/hal/chipname/pub/padmux.h中查询；

第三列为引脚及搭配模式的索引名称，可以在sc/drivers/sysdriver/padmux/drv/pub/drv_puse.h中查询

4.5 DEMO¶

demo源码位于sc/driver/sysdriver/pwm/drv/src/drv_pwm_test.c

5. API 参考¶

该功能模块提供以下接口

API名	功能
drv_pwm_set_period	设置pwm周期
drv_pwm_set_duty	设置pwm占空比
drv_pwm_set_shift	设置pwm相位偏移
drv_pwm_set_polarity	设置pwm极性
drv_pwm_set_chan_config	配置pwm指定通道的属性
drv_pwm_get_chan_config	获取当前pwm通道的属性
drv_pwm_channel_enable	使能pwm配置
drv_pwm_set_group_config	配置group属性
drv_pwm_get_group_config	获取当前group的属性配置
drv_pwm_group_enable	使能pwm group功能
drv_pwm_stop_enable	使能stop功能
drv_pwm_round_enable	设置round mode的脉冲数量
drv_pwm_update_enable	更新pwm配置
drv_pwm_set_deadtime	配置pwm指定通道的dead time
drv_pwm_ddt_enable	使能pwm指定通道的dead time功能
drv_pwm_ddt_break	使能死区波形的刹车功能

头文件位于sc/driver/sysdriver/pwm/drv/pub/drv_pwm.h

struct pwm_ch_cfg
{
    u64 duty;     //设定占空比，实际占空比=duty-shift
    u64 shift;    //设定起始相位
    u64 period;   //设定周期
    u32 polarity; //极性设置：0-正常，1-极性取反
    u32 channel;  //指定channel
};

struct pwm_gp_cfg
{
    u64 duty;
    u64 shift;
    u8  polar;
    u32 group;
    u64 period;
};

5.1. drv_pwm_set_period¶

功能

设置pwm周期

语法

int drv_pwm_set_period(u32 channel, u64 period, u8 sync)

参数

参数名称	描述
channel	选择pwm的通道
period	pwm周期，高精度模式以ns为单位，低精度模式以Hz为单位
sync	0表示配置在此次接口调用后生效，1表示此次接口调用后不生效，生效需要调用drv_pwm_update_enable接口

返回值

返回值 描述

0 成功

负数失败

5.2. drv_pwm_set_duty¶

功能

设置pwm占空比

语法

drv_pwm_set_duty(u32 channel, u64 duty, u8 sync)

参数

参数名称	描述
channel	选择pwm的通道
duty	pwm占空比，高精度模式以ns为单位，低精度模式以Hz为单位
sync	0表示配置在此次接口调用后生效，1表示此次接口调用后不生效，生效需要调用drv_pwm_update_enable接口

返回值

返回值 描述

0 成功

负数失败

5.3. drv_pwm_set_shift¶

功能

设置pwm相位偏移

语法

int drv_pwm_set_shift(u32 channel, u64 shift, u8 sync)

参数

参数名称	描述
channel	选择pwm的通道
shift	pwm相位偏移，高精度模式以ns为单位，低精度模式以Hz为单位
sync	0表示配置在此次接口调用后生效，1表示此次接口调用后不生效，生效需要调用drv_pwm_update_enable接口

返回值

返回值 描述

0 成功

负数失败

5.4. drv_pwm_set_polarity¶

功能

设置pwm极性

语法

int drv_pwm_set_polarity(u32 channel, u64 polar, u8 sync)

参数

参数名称	描述
channel	选择pwm的通道
polar	pwm极性，0：normal，1：invert
sync	0表示配置在此次接口调用后生效，1表示此次接口调用后不生效，生效需要调用drv_pwm_update_enable接口

返回值

返回值 描述

0 成功

负数失败

5.5. drv_pwm_set_chan_config¶

功能

配置pwm指定通道的属性

语法

int drv_pwm_set_chan_config(struct pwm_ch_cfg * pwm_ch)

参数

参数名称描述

pwm_ch 用于配置pwm的通道、周期、占空比、相位偏移和极性信息
返回值

返回值 描述

0 成功

负数失败

5.6. drv_pwm_get_chan_config¶

功能

获取当前pwm通道的属性

语法

int drv_pwm_get_chan_config(struct pwm_ch_cfg * pwm_ch)

参数

参数名称描述

pwm_ch 用于获取pwm的通道、周期、占空比、相位偏移和极性信息
返回值

返回值 描述

0 成功

负数失败

5.7. drv_pwm_channel_enable¶

功能

使能pwm配置

语法

int drv_pwm_channel_enable(u32 channel, u8 enable)

参数

参数名称描述

channel 选择pwm的通道

enable 1：enable，0：disable
返回值

返回值 描述

0 成功

负数失败

5.8. drv_pwm_set_group_config¶

功能

配置group属性

语法

int drv_pwm_set_group_config(struct pwm_gp_cfg *pwm_gp)

参数

参数名称描述

pwm_gp 用于配置pwm group的通道、周期、占空比、相位偏移和极性信息，生效需要调用drv_pwm_update_enable接口
返回值

返回值 描述

0 成功

负数失败

5.9. drv_pwm_get_group_config¶

功能

获取当前group的属性配置

语法

int drv_pwm_get_group_config(struct pwm_gp_cfg *pwm_gp)

参数

参数名称描述

pwm_gp 用于获取pwm group的通道、周期、占空比、相位偏移和极性信息
返回值

返回值 描述

0 成功

负数失败

5.10. drv_pwm_group_enable¶

功能

使能pwm group功能

语法

int drv_pwm_group_enable(u32 group, u8 enable)

参数

参数名称描述

group 选择要使能pwm波形的group

enable 1：enable，0：disable
返回值

返回值 描述

0 成功

负数失败

5.11. drv_pwm_stop_enable¶

功能

使能stop功能

语法

int drv_pwm_stop_enable(u32 group, u8 stop_en)

参数

参数名称描述

group 选择要使能停止功能的group

stop_en 1：enable，波形停止；0：disable，波形恢复
返回值

返回值 描述

0 成功

负数失败

5.12. drv_pwm_round_enable¶

功能

设置round mode的脉冲数量

语法

int drv_pwm_round_enable(u32 group, u32 round_num)

参数

参数名称描述

group 选择使能round mode的group

round_num 指定输出PWM波形的周期数
返回值

返回值 描述

0 成功

负数失败

5.13. drv_pwm_update_enable¶

功能

更新pwm配置
语法
```
int drv_pwm_update_enable(u32 group)
```
参数

参数名称描述

group 选择要进行参数更新的group
返回值

返回值 描述

0 成功

负数失败

5.14. drv_pwm_set_deadtime¶

功能

配置pwm指定通道的dead time

语法

int drv_pwm_set_deadtime(u32 channel, u64 p_ddt, u64 n_ddt)

参数

参数名称	描述
channel	选择要配置dead time的pwm通道
p_ddt	指定pwm通道正向波形的死区时间，以ns为单位
n_ddt	指定pwm通道反向波形的死区时间，以ns为单位

返回值

返回值 描述

0 成功

负数失败

5.15. drv_pwm_ddt_enable¶

功能

使能pwm指定通道的dead time功能

语法

int drv_pwm_ddt_enable(u32 channel, u8 enable)

参数

参数名称描述

channel 选择要配置dead time的pwm通道

enable 1：enable，0：disable
返回值

返回值 描述

0 成功

负数失败

5.16. drv_pwm_ddt_break¶

功能

使能死区波形的刹车功能

语法

int drv_pwm_ddt_break(u32 channel, u8 break_pol, u8 enable)

参数

参数名称	描述
channel	选择要配置dead time的pwm通道
break_pol	指定PIN脚，以PAD_GPIOA_13为例，0：PAD_GPIOA_13接地后，死区波形停止；1：PAD_GPIOA_13接高电平后，死区波形停止
enable	1：enable，0：disable

返回值

返回值 描述

0 成功

负数失败

6 FAQ¶

6.1 PWM各接口不存在¶

检查 sysdesc PWM节点的status是否为ok
检查config是否配置，详见SYSDESC配置

6.2 配置后PWM无波形产生¶

Step1: 首先确认测量的引脚是否正确：打开对应的原理图确认即可，如果没有错误的话，则进行下一步。

Step2: 确认对应的PWM mode是否生效，引脚复用失败主要有两个原因：

原因一：该引脚没有设置为PWM mode，设置方法详见PADMUX配置

原因二：有优先级比PWM mode更高级别的padmux mode被开启，

Step3:检查相关参数是否设置成功

参数名称	描述
group	选择要使能pwm波形的group
enable	1：enable，0：disable

参数名称	描述
group	选择要使能停止功能的group
stop_en	1：enable，波形停止；0：disable，波形恢复

参数名称	描述
group	选择使能round mode的group
round_num	指定输出PWM波形的周期数

返回值	描述
0	成功
负数	失败

返回值	描述
0	成功
负数	失败

返回值	描述
0	成功
负数	失败

返回值	描述
0	成功
负数	失败