这是最新(主)开发分支的文档。如果您正在查找以前版本的文档，使用左侧的下拉菜单选择所需的版本。

PWM API 参考

Macros

WM_DRV_PWM_MUTEX_TIMEOUT

PWM driver’s mutex access wait timeout time, unit ms

WM_DRV_PWM_DEADTIME_CLKDIV_MAX

PWM Dead Time Maximum Prescaler Factor

WM_DRV_PWM_FREQ_MAX

Maximum PWM Output Frequency, unit Hertz (Hz)

WM_DRV_PWM_FREQ_MIN

Minimum PWM Output Frequency, unit Hertz (Hz)

WM_DRV_PWM_CAP_CACHE_MAX

Maximum number of capture cache data

Type Definitions

typedef void (*wm_drv_pwm_report_cb_t)(void *report, void *user_arg)

A user-defined callback function type for PWM capture and output reports.

备注

This function type is used as a parameter type for the `wm_drv_pwm_set_channel_capture_cb()` and `wm_drv_pwm_set_channel_output_cb()` functions. It is expected to process the report data and perform any necessary actions based on the report data.

备注

The function parameter `void *report` may be of type `wm_drv_pwm_cap_report_t` or `wm_drv_pwm_out_report_t`. At the end of the callback, the lifecycle of `report` ends and the memory will be reclaimed. Additionally, when it is capture data, the user’s callback needs to copy the content. Once the callback ends, `value` will no longer hold a meaningful value.

备注

The function does not return any value, but only processes the report data.

Param report:

[in] The pointer to the report data.

Param user_arg:

[in] The argument passed to the callback function.

Return:

None. This function only processes the report data and may release the `report` pointer when it is no longer needed.

Structures

struct wm_drv_pwm_cap_data_report_t

descript the report capture data structure

Public Members

uint16_t rval

capture data from rising edge

uint16_t fval

capture data from falling edge

struct wm_drv_pwm_cap_report_t

used to report capture data when data is ready

Public Members

uint8_t chan

the channel associated with this interrupt report

struct wm_drv_pwm_out_report_t

used to report output data when period num exhaust

Public Members

uint8_t period_num

output interrupt report the period num setting

uint8_t chan

the channel associated with this interrupt report

struct wm_drv_pwm_channel_cfg_t

PWM channel configure items of PWM driver.

Public Members

enum wm_pwm_cap_int_type int_type

which interrupt type used for capture

uint16_t clkdiv

clock divider for this channel,[0, 65535]

uint8_t period_cycle

the period cycles of divided clock, [0, 255], This variable, along with the duty_cycle, will determine the frequency of the PWM output. The formula for frequency is expressed as: freq = (pwm_clock_hz) / ((period_cycle + 1) * clkdiv), The current pwm_clock_hz is 40MHz. In practical scenarios, please refer to the RCC configuration for the PWM clock

uint8_t duty_cycle

the duty cycles of divided clock, [0, 255], This variable will determine the duty ratio of the output PWM, with the calculation formula being: duty_ratio = (duty_cycle + 1) / (period_cycle + 1)

uint8_t dead_time_clkdiv

for complement mode, clock divide value for dead time, 0: master_clock, 1: master_clock / 2, 2: master_clock / 4, 3: master_clock / 8

uint8_t dead_time_cnt

for complement mode, dead time clock cycle count, decided by dead_time_clkdiv, 0 means disable it

uint8_t period_num

for output mode, the period count to be generated before rise the interrupt, 0 means disable it

uint8_t cap_cache_cnt

the number of wm_drv_pwm_cap_report_t to cache for capture mode, this value should be less than WM_DRV_PWM_CAP_CACHE_MAX and bigger than 0

bool period_int

if enable the period output interrupt when period number reached, it takes effect when autoload is set to true

bool inverse

if inverse the output / capture ploarity

bool autoload

if atuo reload for loop output

bool output_high

if output high level for brake mode

Functions

wm_device_t *wm_drv_pwm_init(const char *name)

Initializes the PWM driver with the given name and parameters.

备注

This function initializes the PWM driver with the provided name and parameters. It also allocates memory for the driver context and initializes the necessary data structures. The function returns a pointer to the initialized PWM driver device, which can be used for subsequent operations.

参数:

name – [in] The name of the PWM driver device.

返回:

A pointer to the initialized PWM driver device on success, or NULL on failure.

int wm_drv_pwm_deinit(wm_device_t *device)

Deinitializes the PWM driver and releases all allocated resources.

备注

This function deinitializes the PWM driver and releases all allocated resources. It stops all PWM channels, deinitializes the driver context, and frees the allocated memory. The function returns 0 on success, or a negative error code on failure.

参数:

device – [in] The pointer to the PWM driver device to be deinitialized.

返回:

0 on success, or a negative error code on failure.

int wm_drv_pwm_channel_init(wm_device_t *device, wm_drv_pwm_channel_cfg_t *cfg)

Initializes the PWM channel with the given configuration.

备注

This function initializes the PWM channel with the provided configuration. It sets the mode, capture interrupt type, GPIOs, brake input GPIO, clock divider, period cycles, duty cycles, dead time clock divide value, dead time clock cycle count, period number, and output interrupt enable flag.

备注

When configuring the PWM channel in complementary or channel-synchronized mode, it is only necessary to set the primary channel. For example, to set channels ch0 and ch1 as dual-channel synchronized, only ch0 needs to be configured.

备注

When set to capture mode, it is recommended to use DMA mode for `int_type` to achieve better performance. Using interrupt mode may result in missed cases, leading to suboptimal results or slow reporting.

备注

When using capture mode, the best practice is to initialize the local device’s frequency to be ten times the target frequency of capture to obtain accurate results. For example, if the target frequency is 10 kHz, configure the period cycle to 199 and the clock divider to 2 to achieve a local frequency of 100 kHz.

备注

If the current mode is operating in full channel synchronization, setting a specific channel to another mode (break, independent, etc.) will terminate the full channel synchronization output.

参数:

  • device – [in] The pointer to the PWM driver device.

  • cfg – [in] The configuration parameters for the PWM channel.

返回:

0 on success, or a negative error code on failure.

int wm_drv_pwm_channel_deinit(wm_device_t *device, uint8_t channel)

Deinitializes the PWM channel and releases all allocated resources.

备注

This function deinitializes the PWM channel with the provided channel number. It stops the PWM channel, deinitializes the driver context, and frees the allocated memory. The function returns 0 on success, or a negative error code on failure.

参数:

  • device – [in] The pointer to the PWM driver device.

  • channel – [in] The channel number of the PWM channel to be deinitialized.

返回:

0 on success, or a negative error code on failure.

int wm_drv_pwm_channel_start(wm_device_t *device, uint8_t channel)

Starts the specified PWM channel.

备注

This function starts the specified PWM channel with the provided channel number. It enables the PWM output and sets the PWM channel to generate the specified frequency and duty cycle. The function returns 0 on success, or a negative error code on failure.

备注

In PWM brake mode, when set to output a high level upon triggering, it will take effect by default.

参数:

  • device – [in] The pointer to the PWM driver device.

  • channel – [in] The channel number of the PWM channel to be started.

返回:

0 on success, or a negative error code on failure.

int wm_drv_pwm_channel_stop(wm_device_t *device, uint8_t channel)

Deinitializes the PWM channel and releases all allocated resources.

备注

This function deinitializes the PWM channel with the provided channel number. It stops the PWM channel, deinitializes the driver context, and frees the allocated memory. The function returns 0 on success, or a negative error code on failure.

参数:

  • device – [in] The pointer to the PWM driver device.

  • channel – [in] The channel number of the PWM channel to be deinitialized.

返回:

0 on success, or a negative error code on failure.

int wm_drv_pwm_channels_start(wm_device_t *device)

Starts all specified PWM channels.

备注

This function starts all specified PWM channels. It enables the PWM output and sets the PWM channels to generate the specified frequency and duty cycle. The function returns 0 on success, or a negative error code on failure.

参数:

device – [in] The pointer to the PWM driver device.

返回:

0 on success, or a negative error code on failure.

int wm_drv_pwm_channels_stop(wm_device_t *device)

Stops all specified PWM channels.

备注

This function stops all specified PWM channels. It stops the PWM output and sets the PWM channels to generate the specified frequency and duty cycle. The function returns 0 on success, or a negative error code on failure.

参数:

device – [in] The pointer to the PWM driver device.

返回:

0 on success, or a negative error code on failure.

int wm_drv_pwm_set_channel_freq(wm_device_t *device, uint8_t channel, uint32_t freq_hz)

Sets the frequency for the specified PWM channel.

备注

This function sets the frequency for the specified PWM channel. It configures the PWM channel to generate the specified frequency , duty cycle and PWM period num. Developers can inspect the duty cycle, clock division, and period number using the provided getter functions. But if the PWM period number is changed, the range of the duty cycle may be limited to a value less than 255. The function returns 0 on success, or a negative error code on failure.

参数:

  • device – [in] The pointer to the PWM driver device.

  • channel – [in] The channel number of the PWM channel to be set.

  • freq_hz – [in] The desired frequency in Hz for the specified PWM channel.

返回:

0 on success, or a negative error code on failure.

int wm_drv_pwm_get_channel_freq(wm_device_t *device, uint8_t channel, uint32_t *freq_hz)

Gets the frequency for the specified PWM channel.

备注

This function gets the frequency for the specified PWM channel. It retrieves the frequency and duty cycle configuration for the specified PWM channel. The function returns 0 on success, or a negative error code on failure.

参数:

  • device – [in] The pointer to the PWM driver device.

  • channel – [in] The channel number of the PWM channel to be queried.

  • freq_hz – [inout] The pointer to the configured frequency in Hz for the specified PWM channel.

返回:

0 on success, or a negative error code on failure.

int wm_drv_pwm_set_channel_period_clkdiv(wm_device_t *device, uint8_t channel, uint8_t period, uint16_t clkdiv)

Sets the frequency for the specified PWM channel using period and clock divider. freq = master_clock / clkdiv / (period + 1)

备注

This function sets the frequency for the specified PWM channel using period and clock divider. It configures the PWM channel to generate the specified frequency and duty cycle. The function returns 0 on success, or a negative error code on failure.

备注

Frequency setting strategy: 1. Frequency must be within [WM_DRV_PWM_FREQ_MIN(3Hz), WM_DRV_PWM_FREQ_MAX(160KHz)] range 2. First try to achieve target frequency by adjusting clkdiv while keeping current period value Frequency calculation formula: freq = master_clock / (period + 1) / clkdiv Where:

  • master_clock is PWM clock frequency (typically 40MHz)

  • period remains unchanged from current configuration

  • clkdiv is automatically calculated, range is [1, 65535] 3. If target frequency cannot be achieved by adjusting clkdiv alone, function will try to adjust both period and clkdiv to achieve target frequency 4. If it is not possible to calculate an appropriate period and clkdiv, the setting will fail

参数:

  • device – [in] The pointer to the PWM driver device.

  • channel – [in] The channel number of the PWM channel to be set.

  • period – [in] The desired period count in cycles.

  • clkdiv – [in] The desired clock divider value.

返回:

0 on success, or a negative error code on failure.

int wm_drv_pwm_get_channel_period_clkdiv(wm_device_t *device, uint8_t channel, uint8_t *period, uint16_t *clkdiv)

Gets the period and clock divider for the specified PWM channel.

备注

This function gets the frequency for the specified PWM channel using period and clock divider. It retrieves the frequency and duty cycle configuration for the specified PWM channel. The function returns 0 on success, or a negative error code on failure.

参数:

  • device – [in] The pointer to the PWM driver device.

  • channel – [in] The channel number of the PWM channel to be queried.

  • period – [inout] The pointer to the desired period count in cycles.

  • clkdiv – [inout] The pointer to the desired clock divider value.

返回:

0 on success, or a negative error code on failure.

int wm_drv_pwm_set_channel_duty(wm_device_t *device, uint8_t channel, uint8_t duty_cycle)

Sets the duty cycle for the specified PWM channel.

备注

This function sets the duty cycle for the specified PWM channel.

备注

The output duty cycle is calculated as (duty_cycle + 1) / (period + 1), if duty_cycle > period_cycle then the output is fixed at a high level. if duty_cycle = 0, the low level width is PERIOD, and the high level width is 1 PWM divided clock cycle

参数:

  • device – [in] The pointer to the PWM driver device.

  • channel – [in] The channel number of the PWM channel to be set.

  • duty_cycle – [in] The desired duty cycle value in percentage (0-255).

返回:

0 on success, or a negative error code on failure.

int wm_drv_pwm_get_channel_duty(wm_device_t *device, uint8_t channel, uint8_t *duty_cycle)

Gets the duty cycle for the specified PWM channel.

备注

This function gets the duty cycle for the specified PWM channel. It retrieves the duty cycle configuration for the specified PWM channel. The duty cycle value is in percentage (0-255). The function returns 0 on success, or a negative error code on failure.

参数:

  • device – [in] The pointer to the PWM driver device.

  • channel – [in] The channel number of the PWM channel to be queried.

  • duty_cycle – [inout] The pointer to the desired duty cycle value.

返回:

0 on success, or a negative error code on failure.

int wm_drv_pwm_set_channel_period_num(wm_device_t *device, uint8_t channel, uint8_t period_num)

Sets the period number to be generated before rise the interrupt for the specified PWM channel.

备注

This function sets the period number to be generated before rise the interrupt for the specified PWM channel. It configures the PWM channel to generate the specified frequency and duty cycle, and to generate the specified period number before rising the interrupt. The function returns 0 on success, or a negative error code on failure.

备注

Dynamic setting of period_num in PWM: If currently outputting, the setting will take effect immediately. If not currently outputting, the setting will only take effect after calling start API.

参数:

  • device – [in] The pointer to the PWM driver device.

  • channel – [in] The channel number of the PWM channel to be set.

  • period_num – [in] The desired period number to be generated before rising the interrupt.

返回:

0 on success, or a negative error code on failure.

int wm_drv_pwm_get_channel_period_num(wm_device_t *device, uint8_t channel, uint8_t *period_num)

Gets the period number to be generated before rise the interrupt for the specified PWM channel.

备注

This function gets the period number to be generated before rise the interrupt for the specified PWM channel. It retrieves the period number configuration for the specified PWM channel. The function returns 0 on success, or a negative error code on failure.

参数:

  • device – [in] The pointer to the PWM driver device.

  • channel – [in] The channel number of the PWM channel to be queried.

  • period_num – [inout] The pointer to the desired period number to be generated before rising the interrupt.

返回:

0 on success, or a negative error code on failure.

int wm_drv_pwm_set_channel_period_int(wm_device_t *device, uint8_t channel, bool en)

Enable /Disable the period number interrupt for the specified PWM channel.

备注

This function sets interrupt for the period number for the specified PWM channel. It configures the PWM channel to generate the specified frequency and duty cycle, and to generate the specified period number before rising the interrupt. The function returns 0 on success, or a negative error code on failure.

备注

Dynamic setting of period_int in PWM: If currently outputting, the setting will take effect immediately. If not currently outputting, the setting will only take effect after calling start API.

参数:

  • device – [in] The pointer to the PWM driver device.

  • channel – [in] The channel number of the PWM channel to be set.

  • en – [in] if enable the interrupt.

返回:

0 on success, or a negative error code on failure.

int wm_drv_pwm_get_channel_period_int(wm_device_t *device, uint8_t channel, bool *en)

Gets the period number interrupt flag for the specified PWM channel.

备注

This function gets the period number interrupt flag for the specified PWM channel. It retrieves the period number interrupt flag configuration for the specified PWM channel. The function returns 0 on success, or a negative error code on failure.

参数:

  • device – [in] The pointer to the PWM driver device.

  • channel – [in] The channel number of the PWM channel to be queried.

  • en – [inout] The pointer to the desired period number interrupt flag.

返回:

0 on success, or a negative error code on failure.

int wm_drv_pwm_set_channel_inverse(wm_device_t *device, uint8_t channel, bool en)

Sets the inverse flag for the specified PWM channel.

备注

This function sets the inverse flag for the specified PWM channel. It configures the PWM channel to invert the output / capture polarity. The function returns 0 on success, or a negative error code on failure.

参数:

  • device – [in] The pointer to the PWM driver device.

  • channel – [in] The channel number of the PWM channel to be set.

  • en – [in] if enable the inverse flag.

返回:

0 on success, or a negative error code on failure.

int wm_drv_pwm_get_channel_inverse(wm_device_t *device, uint8_t channel, bool *en)

Gets the inverse flag for the specified PWM channel.

备注

This function gets the inverse flag for the specified PWM channel. It retrieves the inverse flag configuration for the specified PWM channel. The function returns the inverse flag for the specified PWM channel.

参数:

  • device – [in] The pointer to the PWM driver device.

  • channel – [in] The channel number of the PWM channel to be queried.

  • en – [inout] The pointer to the desired inverse flag.

返回:

0 on success, or a negative error code on failure.

int wm_drv_pwm_set_channel_brake_level(wm_device_t *device, uint8_t channel, bool en)

Sets the brake level flag for the specified PWM channel.

备注

This function sets the brake level flag for the specified PWM channel. It configures the PWM channel to enable or disable the brake level flag.

参数:

  • device – [in] The pointer to the PWM driver device.

  • channel – [in] The channel number of the PWM channel to be set.

  • en – [in] if enable the brake level flag.

返回:

0 on success, or a negative error code on failure.

int wm_drv_pwm_get_channel_brake_level(wm_device_t *device, uint8_t channel, bool *en)

Gets the brake level flag for the specified PWM channel.

备注

This function gets the brake level flag for the specified PWM channel. It retrieves the brake level flag configuration for the specified PWM channel. The function returns the brake level flag for the specified PWM channel.

参数:

  • device – [in] The pointer to the PWM driver device.

  • channel – [in] The channel number of the PWM channel to be queried.

  • en – [inout] The pointer to the desired brake level flag.

返回:

0 on success, or a negative error code on failure.

int wm_drv_pwm_set_channel_deadtime(wm_device_t *device, uint8_t channel, uint8_t cnt, uint8_t clkdiv)

Sets the deadtime for the specified PWM channel.

备注

This function sets the deadtime for the specified PWM channel. It configures the PWM channel to generate the specified frequency and duty cycle, and to set the specified deadtime count and clock divider value. The function returns 0 on success, or a negative error code on failure.

参数:

  • device – [in] The pointer to the PWM driver device.

  • channel – [in] The channel number of the PWM channel to be set.

  • cnt – [in] The desired deadtime count in cycles.

  • clkdiv – [in] The desired clock divider value.

返回:

0 on success, or a negative error code on failure.

int wm_drv_pwm_get_channel_deadtime(wm_device_t *device, uint8_t channel, uint8_t *cnt, uint8_t *clkdiv)

Gets the deadtime for the specified PWM channel.

备注

This function gets the deadtime for the specified PWM channel. It retrieves the deadtime configuration for the specified PWM channel, including the deadtime count in cycles and the clock divider value. The function returns 0 on success, or a negative error code on failure.

参数:

  • device – [in] The pointer to the PWM driver device.

  • channel – [in] The channel number of the PWM channel to be queried.

  • cnt – [inout] The pointer to the desired deadtime count in cycles.

  • clkdiv – [inout] The pointer to the desired clock divider value.

返回:

0 on success, or a negative error code on failure.

int wm_drv_pwm_set_channel_autoreload(wm_device_t *dev, uint8_t channel, bool en)

Sets the auto reload flag for the specified PWM channel.

备注

This function sets the auto reload flag for the specified PWM channel. It configures the PWM channel to enable or disable the auto reload flag. The function returns 0 on success, or a negative error code on failure.

参数:

  • dev – [in] The pointer to the PWM driver device.

  • channel – [in] The channel number of the PWM channel to be set.

  • en – [in] if enable the auto reload flag.

返回:

0 on success, or a negative error code on failure.

int wm_drv_pwm_get_channel_autoreload(wm_device_t *device, uint8_t channel, bool *en)

Gets the auto reload flag for the specified PWM channel.

备注

This function gets the auto reload flag for the specified PWM channel. It retrieves the auto reload flag configuration for the specified PWM channel. The function returns the auto reload flag for the specified PWM channel.

参数:

  • device – [in] The pointer to the PWM driver device.

  • channel – [in] The channel number of the PWM channel to be queried.

  • en – [inout] The auto reload flag for the specified PWM channel.

返回:

0 on success, or a negative error code on failure.

int wm_drv_pwm_set_channel_output_cb(wm_device_t *device, uint8_t channel, wm_drv_pwm_report_cb_t cb, void *arg)

Sets the output report callback function for the specified PWM channel.

备注

This function sets the output report callback function for the specified PWM channel. It configures the PWM channel to call the specified output report callback function when the period number is exhausted. The function returns 0 on success, or a negative error code on failure.

参数:

  • device – [in] The pointer to the PWM driver device.

  • channel – [in] The channel number of the PWM channel to be set.

  • cb – [in] The output report callback function.

  • arg – [in] The argument to be passed to the output report callback function.

返回:

0 on success, or a negative error code on failure.

int wm_drv_pwm_set_channel_capture_cb(wm_device_t *device, uint8_t channel, wm_drv_pwm_report_cb_t cb, void *arg)

Sets the capture report callback function for the specified PWM channel.

备注

This function sets the capture report callback function for the specified PWM channel. It configures the PWM channel to call the specified capture report callback function when capture data is ready. The function returns 0 on success, or a negative error code on failure.

参数:

  • device – [in] The pointer to the PWM driver device.

  • channel – [in] The channel number of the PWM channel to be set.

  • cb – [in] The capture report callback function.

  • arg – [in] The argument to be passed to the capture report callback function.

返回:

0 on success, or a negative error code on failure.

void wm_drv_pwm_show_cfg_regs(wm_device_t *device)

Displays the configuration registers of the specified PWM channel.

备注

This function displays the configuration registers of the specified PWM channel. It retrieves the configuration registers for the specified PWM channel, including the clock divider, period cycles, duty cycles, dead time clock divide value, dead time clock cycle count, period number, and output interrupt enable flag. The function does not return any value, but only displays the configuration registers.

参数:

device – [in] The pointer to the PWM driver device.

返回:

None. This function only displays the configuration registers.