RISVC_PWM USER GUIDE
REVISION HISTORY¶
| Revision No. | Description |
Date |
|---|---|---|
| 1.0 | 04/09/2025 |
1. OVERVIEW¶
The PWM (Pulse Width Modulation) module is used to generate pulse width waveforms. It can change the output current and voltage by changing the frequency and duty cycle to achieve functions such as controlling the motor speed and dimming the LCD screen. The SigmaStar PWM module also has a Group function (divided into sync, round, hold, stop), that is, every 4 or 6 channels of PWM can be bound into a group to achieve 4 or 6 channels of PWM synchronous generation or stop.
The relationship between devices and hardware groups is shown in the table below:
| 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 |
| HW PM PWM group0 | 1AH | pm channel 0 ~ 1 |
2. Key Words¶
sysdesc:
RTOS files used to describe the hardware attributes of peripherals. The attribute values contained in peripheral nodes can be used for peripheral configuration, similar to Linux device tree files.
padmux:
Pin multiplexing is used to connect the functional pins of modules to specific external pins, establishing signal connections.
Dead Time:
The PWM dead time refers to the time interval between two adjacent output signals during the PWM signal switching process. It is used to prevent power switching devices (such as MOSFET or IGBT) from being turned on at the same time during the switching process, thereby avoiding short circuits and damage.
3. Function description¶
3.1. Overview¶
-
The number of channels supporting PWM is 20, of which channels 0~17 support joining their own groups, and channels 18~19 do not support the group function. For details, see Corresponding Relationship Between Group and Channel.
-
PWM channels 12~17 support Dead Time setting and brake function with the maximum setting value of (OSCCLK / 0x3FF). For example, if OSCCLK = 12MHz, the range is 0~85250ns.
-
Support double buffer to prevent the generation of erroneous waveforms, that is, the waveform will wait for the current waveform to be fully generated before updating.
-
Support shift function, that is, the waveform can have its phase set; the phase will affect the duty cycle, with the actual duty cycle = set duty cycle - phase
-
Support sync function, that is, the PWM in the group generates waveforms at the same time, generally a group will contain 4 channels of PWM.
-
Support round function, that is, the PWM in the same group will stop after generating a specific number of pulses.
-
Support hold function, that is, the PWM in the same group will pause after completing the waveform of the current cycle, which is often used to change the setting of the waveform, and the high and low levels within the pause time can be set.
-
Support stop function, that is, the PWM in the same group will stop urgently.
3.2 Frequency and Duty Cycle¶
-
Frequency
The number of times a signal changes from high level to low level and then back to high level per second.
-
Duty cycle
The ratio between the duration of high level and the duration of low level.
-
Example description
Assuming that the OSCCLK frequency of PWM is 12M, the frequency range that can be set is: 0.0007Hz~6MHz;
Set PWM0 and PWM1 to waveforms with a frequency of 120Hz and a duty cycle of 25%, and PWM1 has a phase shift of 180° relative to PWM0, then the parameters are configured as follows:
period duty shift PWM0 120Hz 25% 0% PWM1 120Hz 75% 50% Channels 0~17 support OSCCLK(Hz): 86M, 24M, 12M, 6M, 3M, 1.5M, 750K;
Channels 18~19 support OSCCLK(Hz): 12M, 6M, 3M;
The operating frequency range is (OSCCLK/2) to (OSCCLK/2^34).Actual working frequency range is as follows:
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 The generated waveform is as follows:

3.3. Normal Precision Mode¶
If Support high precision calculation is not enabled in config, normal precision mode is used. In this mode, the unit of period of PWM is Hz, and the unit of duty cycle is percentage.
Assume that the frequency of PWM0 is set to 10000HZ and the duty cycle is 50%, then:
period = 10000
duty cycle = 50
3.4. High Precision Mode¶
When the Support high precision calculation option is enabled in config, the high precision mode is used. In this mode, the period and duty_cycle of PWM are configured in ns, so the period and duty cycle values must be calculated first.
Assuming that the PWM0 frequency is set to 10000.5HZ and the duty cycle is 49.5%, then:
period = 10^9 ÷ 10000.5 = 99995
duty cycle = 99995 * 49.5% = 49498
It can be seen that the advantage of high precision mode is that parameter settings support decimals.
3.5. GROUP Related Concept¶
3.5.1 Sync Mode¶
The sync mode can add each pwm channel to its own Group to achieve the purpose of controlling multiple PWMs at the same time. A Group has 4 pwm channels, and the corresponding relationship between Group and channel is as follows:
| 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¶
The Hold function of the group will stop after the PWM completes the waveform of the current cycle and trigger an interrupt. At this time, the configuration of each channel waveform can be changed to keep synchronization. After the modification is completed, the hold function will be turned off and the PWM will regenerate a new waveform. Each group has its own independent hold function.

3.5.3 Round Mode¶
The round function will stop after all channels in the same group complete a certain number of pulses. Each group has its own independent round function.

3.5.4 Stop Mode¶
The stop function can stop the PWM in the current group immediately (without waiting for the current cycle to complete) and maintain the level at the end. Each group has its own independent stop function.

Note: It is not recommended to set the stop time to be too long, especially when the level maintained after PWM stops is high.
3.6. Dead Time¶
Dead Time is generated based on two complementary signals. The positive signal generates a delay based on the relative rising edge of the PWM clock, and the negative signal generates a delay based on the relative falling edge of the PWM clock.


4. RTOS USAGE INTRODUCTION¶
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 Configuration¶
#make menuconfig # Feature_Name = [DRV] PWM driver support # Description = PWM driver support # Option_Selection = TRUE, FALSE CONFIG_PWM_SUPPORT = TRUE //Enable the PWM driver CONFIG_SSTAR_PWM_DDT = TRUE //Enable the dead time function CONFIG_SSTAR_PWM_EXTEND = TRUE //TRUE: High precision mode, FLASE: Low precision mode
4.3. SYSDESC Configuration¶
The file chipname_xxx.sys is used to describe the hardware attributes of peripherals. The attribute values contained in the peripheral node can be used to configure the peripherals, similar to the Linux device tree. The file is located in sc/driver/sysdriver/sysdesc/hal/chipname/pub. The following takes pwm12 as an example:
<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;
The attributes supported for configuration in the pwm driver are as follows:
| Attribute | Description | Setting value | Remark |
|---|---|---|---|
| reg_u32_u16 | Specify the pwm bank address | 0x2205600 | Modification prohibited |
| interrupts_u32 | Specify the hardware interrupt number | INT_IRQ_PWM_GROUP3 | Modification prohibited |
| camclk_u16 | Specify the clock source | CAMCLK_pwm | Modification prohibited |
| group_u32 | Select whether to join the group | Assign the corresponding group index according to Correspondence Between Group and Channel, 0xFFFF means not to join | Can be modified as needed. You can only choose to join group or spwm group |
| spwm_group_u32 | Select whether to join the spwm group | 0xFFFF | You can only choose to join group or spwm group |
| clk_level_u8 | pwm0~17 can be selected from 0~6, corresponding to 12M/6M/3M/1.5M/750K/86M/24M respectively; pwm18~19 can be selected from 0~2, corresponding to 12M/6M/3M respectively | pwm0~17 selections must be consistent; pwm18~19 selections must be consistent | |
| ddt_reg_u32 | Specify the dead time bank address | 0x2203600 | Modification prohibited |
| idle_status_u8 | Select the dead time waveform idle level state | 0: low level; 1: high level | Can be modified as needed |
| status_u8 | Select whether to enable the driver | 1: enable; 0: disable | Can be modified as needed |
4.4. PADMUX Configuration¶
CONFIG Configuration: CONFIG_PADMUX_SUPPORT=TRUE
If the chipname_xxx.sys file is configured with the attribute <padmux>, then the PADMUX setting is directly configured here:
<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;
The first column is the pin index number, which can be queried in sc/drivers/sysdriver/gpio/hal/chipname/pub/gpio.h;
The second column is the mode definition, which can be queried in sc/drivers/sysdriver/gpio/hal/chipname/pub/padmux.h;
The third column is the index name of the pin and matching mode, which can be queried in sc/drivers/sysdriver/padmux/drv/pub/drv_puse.h.
4.5 DEMO¶
The demo source code is located in sc/driver/sysdriver/pwm/drv/src/drv_pwm_test.c.
5. API 参考¶
This functional module provides the following interfaces:
| API | Function |
|---|---|
| drv_pwm_set_period | Set PWM period |
| drv_pwm_set_duty | Set PWM duty cycle |
| drv_pwm_set_shift | Set PWM phase offset |
| drv_pwm_set_polarity | Set PWM polarity |
| drv_pwm_set_chan_config | Configure properties for a specified PWM channel |
| drv_pwm_get_chan_config | Get the current properties of a PWM channel |
| drv_pwm_channel_enable | Enable PWM configuration |
| drv_pwm_set_group_config | Configure group properties |
| drv_pwm_get_group_config | Get the current group property configuration |
| drv_pwm_group_enable | Enable PWM group functionality |
| drv_pwm_stop_enable | Enable stop functionality |
| drv_pwm_round_enable | Set the number of pulses in round mode |
| drv_pwm_update_enable | Update PWM configuration |
| drv_pwm_set_deadtime | Configure dead time for a specified PWM channel |
| drv_pwm_ddt_enable | Enable dead time functionality for a specified PWM channel |
| drv_pwm_ddt_break | Enable brake functionality for dead-time waveform |
The header file is located in sc/driver/sysdriver/pwm/drv/pub/drv_pwm.h
struct pwm_ch_cfg { u64 duty; // Set duty cycle, the actual duty cycle = duty - shift u64 shift; // Set the starting phase u64 period; // Set the period u32 polarity; // Polarity setting: 0 - normal, 1 - inverted polarity u32 channel; // Specify channel }; struct pwm_gp_cfg { u64 duty; u64 shift; u8 polar; u32 group; u64 period; };
5.1. drv_pwm_set_period¶
-
Function
Set PWM period
-
Declaration
int drv_pwm_set_period(u32 channel, u64 period, u8 sync)
-
Parameters
Parameter Name Description channel Select the PWM channel period PWM period, in ns for high precision mode, in Hz for low precision mode sync 0 indicates that the configuration takes effect after this interface call, 1 indicates that it does not take effect until drv_pwm_update_enable interface is called -
Return Value
Return Value Description 0 Success Negative Failure
5.2. drv_pwm_set_duty¶
-
Function
Set PWM duty cycle
-
Declaration
drv_pwm_set_duty(u32 channel, u64 duty, u8 sync)
-
Parameters
Parameter Name Description channel Selected PWM channel duty PWM duty, in ns for high precision mode, in Hz for low precision mode sync 0 indicates that the configuration takes effect after this interface call, 1 indicates that it does not take effect until drv_pwm_update_enable interface is called -
Return Value
Return Value Description 0 Success Negative Failure
5.3. drv_pwm_set_shift¶
-
Function
Set PWM phase offset
-
Declaration
int drv_pwm_set_shift(u32 channel, u64 shift, u8 sync)
-
Parameters
Parameter Name Description channel Selected PWM channel shift PWM shift, in ns for high precision mode, in Hz for low precision mode sync 0 indicates that the configuration takes effect after this interface call, 1 indicates that it does not take effect until drv_pwm_update_enable interface is called -
Return Value
Return Value Description 0 Success Negative Failure
5.4. drv_pwm_set_polarity¶
-
Function
Set PWM polarity
-
Declaration
int drv_pwm_set_polarity(u32 channel, u64 polar, u8 sync)
-
Parameters
Parameter Name Description channel Selected PWM channel polar pwm polarity,0:normal,1:invert sync 0 indicates that the configuration takes effect after this interface call, 1 indicates that it does not take effect until drv_pwm_update_enable interface is called -
Return Value
Return Value Description 0 Success Negative Failure
5.5. drv_pwm_set_chan_config¶
-
Function
Configure properties for a specified PWM channel
-
Declaration
int drv_pwm_set_chan_config(struct pwm_ch_cfg * pwm_ch)
-
Parameters
Parameter Name Description pwm_ch Used for configuring the PWM channel, period, duty cycle, phase offset, and polarity information. -
Return Value
Return Value Description 0 Success Negative Failure
5.6. drv_pwm_get_chan_config¶
-
Function
Get the current properties of a PWM channel
-
Declaration
int drv_pwm_get_chan_config(struct pwm_ch_cfg * pwm_ch)
-
Parameters
Parameter Name Description pwm_ch Used for getting the PWM channel, period, duty cycle, phase offset, and polarity information. -
Return Value
Return Value Description 0 Success Negative Failure
5.7. drv_pwm_channel_enable¶
-
Function
Enable PWM configuration
-
Declaration
int drv_pwm_channel_enable(u32 channel, u8 enable)
-
Parameters
Parameter Name Description channel Selected PWM channel enable 1:enable,0:disable -
Return Value
Return Value Description 0 Success Negative Failure
5.8. drv_pwm_set_group_config¶
-
Function
Configure group properties
-
Declaration
int drv_pwm_set_group_config(struct pwm_gp_cfg *pwm_gp)
-
Parameters
Parameter Name Description pwm_gp Used for configuring the PWM group's channel, period, duty cycle, phase offset, and polarity information. The configuration takes effect after calling the drv_pwm_update_enable interface -
Return Value
Return Value Description 0 Success Negative Failure
5.9. drv_pwm_get_group_config¶
-
Function
Get the current group property configuration
-
Declaration
int drv_pwm_get_group_config(struct pwm_gp_cfg *pwm_gp)
-
Parameters
Parameter Name Description pwm_gp Used for getting the PWM group's channel, period, duty cycle, phase offset, and polarity information -
Return Value
Return Value Description 0 Success Negative Failure
5.10. drv_pwm_group_enable¶
-
Function
Enable PWM group functionality
-
Declaration
int drv_pwm_group_enable(u32 group, u8 enable)
-
Parameters
Parameter Name Description group Select the PWM group to enable the waveform enable 1:enable,0:disable -
Return Value
Return Value Description 0 Success Negative Failure
5.11. drv_pwm_stop_enable¶
-
Function
Enable stop functionality
-
Declaration
int drv_pwm_stop_enable(u32 group, u8 stop_en)
-
Parameters
Parameter Name Description group Select the PWM group to enable the stop function stop_en 1: enable, waveform stops; 0: disable, waveform resumes -
Return Value
Return Value Description 0 Success Negative Failure
5.12. drv_pwm_round_enable¶
-
Function
Set the number of pulses in round mode
-
Declaration
int drv_pwm_round_enable(u32 group, u32 round_num)
-
Parameters
Parameter Name Description group Select the PWM group to enable the round mode round_num Specify the number of cycles for the output PWM waveform -
Return Value
Return Value Description 0 Success Negative Failure
5.13. drv_pwm_update_enable¶
-
Function
Update PWM configuration
-
Declaration
int drv_pwm_update_enable(u32 group)
-
Parameters
Parameter Name Description group Select the PWM group for which to update the parameters. -
Return Value
Return Value Description 0 Success Negative Failure
5.14. drv_pwm_set_deadtime¶
-
Function
Configure dead time for a specified PWM channel
-
Declaration
int drv_pwm_set_deadtime(u32 channel, u64 p_ddt, u64 n_ddt)
-
Parameters
Parameter Name Description channel Select the PWM channel for which to configure the dead time. p_ddt Specify the dead time for the positive waveform of the PWM channel, in ns n_ddt Specify the dead time for the negative waveform of the PWM channel, in ns -
Return Value
Return Value Description 0 Success Negative Failure
5.15. drv_pwm_ddt_enable¶
-
Function
Enable dead time functionality for a specified PWM channel
-
Declaration
int drv_pwm_ddt_enable(u32 channel, u8 enable)
-
Parameters
Parameter Name Description channel Select the PWM channel for which to configure the dead time enable 1:enable,0:disable -
Return Value
Return Value Description 0 Success Negative Failure
5.16. drv_pwm_ddt_break¶
-
Function
Enable brake functionality for dead-time waveform
-
Declaration
int drv_pwm_ddt_break(u32 channel, u8 break_pol, u8 enable)
-
Parameters
Parameter Name Description channel Select the PWM channel for which to configure the dead time break_pol Specify the PIN, using PAD_GPIOA_13 as an example, 0: when PAD_GPIOA_13 is grounded, the dead-time waveform stops; 1: when PAD_GPIOA_13 is connected to high level, the dead-time waveform stops enable 1:enable,0:disable -
Return Value
Return Value Description 0 Success Negative Failure
6. FAQ¶
6.1 PWM Interfaces Do Not Exist¶
-
Check whether the
statusof the DTS PWM node isok. -
Check whether the config is configured, see Config Configuration for details.
6.2 No PWM Waveform Is Generated after Configuration¶
Step 1: First confirm whether the measured pin is correct: open the corresponding schematic to confirm, if there is no error, proceed to the next step.
Step 2: Confirm whether the corresponding PWM mode is effective. There are two main reasons for pin multiplexing failure:
Reason 1: The pin is not set to PWM mode. For details on the setting method, see PADMUX Configuration.
Reason 2: A padmux mode with a higher priority than PWM mode is enabled. You can turn on the padmux readback mechanism CONFIG: CONFIG_MSYS_PADMUX during compilation. Its function is to confirm whether the padmux used has been successfully set. After turning it on, enter the following command in user space to check:
Step 3: Check whether the relevant parameters are set successfully.