This is the documentation for the latest (main) development branch of Zephyr. If you are looking for the documentation of previous releases, use the drop-down menu on the left and select the desired version.

PWM¶

Overview¶

API Reference¶

group pwm_interface

PWM Interface.

PWM capture configuration flags

PWM_CAPTURE_TYPE_PERIOD¶: PWM pin capture captures period.

PWM_CAPTURE_TYPE_PULSE¶: PWM pin capture captures pulse width.

PWM_CAPTURE_TYPE_BOTH¶: PWM pin capture captures both period and pulse width.

PWM_CAPTURE_MODE_SINGLE¶: PWM pin capture captures a single period/pulse width.

PWM_CAPTURE_MODE_CONTINUOUS¶: PWM pin capture captures period/pulse width continuously.

Typedefs

typedef uint8_t pwm_flags_t¶: Provides a type to hold PWM configuration flags.

typedef int (*pwm_pin_set_t)(const struct device *dev, uint32_t pwm, uint32_t period_cycles, uint32_t pulse_cycles, pwm_flags_t flags)¶: Callback API upon setting the pin See pwm_pin_set_cycles() for argument description.

typedef void (*pwm_capture_callback_handler_t)(const struct device *dev, uint32_t pwm, uint32_t period_cycles, uint32_t pulse_cycles, int status, void *user_data)¶

PWM capture callback handler function signature.

Note

The callback handler will be called in interrupt context.

Note

:kconfig:`CONFIG_PWM_CAPTURE` must be selected to enable PWM capture support.

Parameters

dev – Pointer to the device structure for the driver instance.
pwm – PWM pin.
period_cycles – Captured PWM period width (in clock cycles). HW specific.
pulse_cycles – Captured PWM pulse width (in clock cycles). HW specific.
status – Status for the PWM capture (0 if no error, negative errno otherwise. See pwm_pin_capture_cycles() return value descriptions for details).
user_data – User data passed to pwm_pin_configure_capture()

typedef int (*pwm_pin_configure_capture_t)(const struct device *dev, uint32_t pwm, pwm_flags_t flags, pwm_capture_callback_handler_t cb, void *user_data)¶: Callback API upon configuring PWM pin capture See pwm_pin_configure_capture() for argument description.

typedef int (*pwm_pin_enable_capture_t)(const struct device *dev, uint32_t pwm)¶: Callback API upon enabling PWM pin capture See pwm_pin_enable_capture() for argument description.

typedef int (*pwm_pin_disable_capture_t)(const struct device *dev, uint32_t pwm)¶: Callback API upon disabling PWM pin capture See pwm_pin_disable_capture() for argument description.

typedef int (*pwm_get_cycles_per_sec_t)(const struct device *dev, uint32_t pwm, uint64_t *cycles)¶: Callback API upon getting cycles per second See pwm_get_cycles_per_sec() for argument description.

Functions

int pwm_pin_set_cycles(const struct device *dev, uint32_t pwm, uint32_t period, uint32_t pulse, pwm_flags_t flags)¶

Set the period and pulse width for a single PWM output.

The PWM period and pulse width will synchronously be set to the new values without glitches in the PWM signal, but the call will not block for the change to take effect.

Passing 0 as pulse will cause the pin to be driven to a constant inactive level. Passing a non-zero pulse equal to period will cause the pin to be driven to a constant active level.

Note

Not all PWM controllers support synchronous, glitch-free updates of the PWM period and pulse width. Depending on the hardware, changing the PWM period and/or pulse width may cause a glitch in the generated PWM signal.

Note

Some multi-channel PWM controllers share the PWM period across all channels. Depending on the hardware, changing the PWM period for one channel may affect the PWM period for the other channels of the same PWM controller.

Parameters

dev – Pointer to the device structure for the driver instance.
pwm – PWM pin.
period – Period (in clock cycle) set to the PWM. HW specific.
pulse – Pulse width (in clock cycle) set to the PWM. HW specific.
flags – Flags for pin configuration (polarity).

Returns

0 – If successful.
Negative – errno code if failure.

static inline int pwm_pin_configure_capture(const struct device *dev, uint32_t pwm, pwm_flags_t flags, pwm_capture_callback_handler_t cb, void *user_data)¶

Configure PWM period/pulse width capture for a single PWM input.

After configuring PWM capture using this function, the capture can be enabled/disabled using pwm_pin_enable_capture() and pwm_pin_disable_capture().

Note

This API function cannot be invoked from user space due to the use of a function callback. In user space, one of the simpler API functions (pwm_pin_capture_cycles(), pwm_pin_capture_usec(), or pwm_pin_capture_nsec()) can be used instead.

Note

:kconfig:`CONFIG_PWM_CAPTURE` must be selected for this function to be available.

Parameters

dev – Pointer to the device structure for the driver instance.
pwm – PWM pin.
flags – PWM capture flags
cb – Application callback handler function to be called upon capture
user_data – User data to pass to the application callback handler function

Returns

-EINVAL – if invalid function parameters were given
-ENOSYS – if PWM capture is not supported or the given flags are not supported
-EIO – if IO error occurred while configuring
-EBUSY – if PWM capture is already in progress

int pwm_pin_enable_capture(const struct device *dev, uint32_t pwm)¶

Enable PWM period/pulse width capture for a single PWM input.

The PWM pin must be configured using pwm_pin_configure_capture() prior to calling this function.

Note

:kconfig:`CONFIG_PWM_CAPTURE` must be selected for this function to be available.

Parameters

dev – Pointer to the device structure for the driver instance.
pwm – PWM pin.

Returns

0 – If successful.
-EINVAL – if invalid function parameters were given
-ENOSYS – if PWM capture is not supported
-EIO – if IO error occurred while enabling PWM capture
-EBUSY – if PWM capture is already in progress

int pwm_pin_disable_capture(const struct device *dev, uint32_t pwm)¶

Disable PWM period/pulse width capture for a single PWM input.

Note

:kconfig:`CONFIG_PWM_CAPTURE` must be selected for this function to be available.

Parameters

dev – Pointer to the device structure for the driver instance.
pwm – PWM pin.

Returns

0 – If successful.
-EINVAL – if invalid function parameters were given
-ENOSYS – if PWM capture is not supported
-EIO – if IO error occurred while disabling PWM capture

int pwm_pin_capture_cycles(const struct device *dev, uint32_t pwm, pwm_flags_t flags, uint32_t *period, uint32_t *pulse, k_timeout_t timeout)¶

Capture a single PWM period/pulse width in clock cycles for a single PWM input.

This API function wraps calls to pwm_pin_configure_capture(), pwm_pin_enable_capture(), and pwm_pin_disable_capture() and passes the capture result to the caller. The function is blocking until either the PWM capture is completed or a timeout occurs.

Note

:kconfig:`CONFIG_PWM_CAPTURE` must be selected for this function to be available.

Parameters

dev – Pointer to the device structure for the driver instance.
pwm – PWM pin.
flags – PWM capture flags.
period – Pointer to the memory to store the captured PWM period width (in clock cycles). HW specific.
pulse – Pointer to the memory to store the captured PWM pulse width (in clock cycles). HW specific.
timeout – Waiting period for the capture to complete.

Returns

0 – If successful.
-EBUSY – PWM capture already in progress.
-EAGAIN – Waiting period timed out.
-EIO – IO error while capturing.
-ERANGE – If result is too large.

int pwm_get_cycles_per_sec(const struct device *dev, uint32_t pwm, uint64_t *cycles)¶

Get the clock rate (cycles per second) for a single PWM output.

Parameters

dev – Pointer to the device structure for the driver instance.
pwm – PWM pin.
cycles – Pointer to the memory to store clock rate (cycles per sec). HW specific.

Returns

0 – If successful.
Negative – errno code if failure.

static inline int pwm_pin_set_usec(const struct device *dev, uint32_t pwm, uint32_t period, uint32_t pulse, pwm_flags_t flags)¶

Set the period and pulse width for a single PWM output.

Parameters

dev – Pointer to the device structure for the driver instance.
pwm – PWM pin.
period – Period (in microseconds) set to the PWM.
pulse – Pulse width (in microseconds) set to the PWM.
flags – Flags for pin configuration (polarity).

Returns

0 – If successful.
Negative – errno code if failure.

static inline int pwm_pin_set_nsec(const struct device *dev, uint32_t pwm, uint32_t period, uint32_t pulse, pwm_flags_t flags)¶

Set the period and pulse width for a single PWM output.

Parameters

dev – Pointer to the device structure for the driver instance.
pwm – PWM pin.
period – Period (in nanoseconds) set to the PWM.
pulse – Pulse width (in nanoseconds) set to the PWM.
flags – Flags for pin configuration (polarity).

Returns

0 – If successful.
Negative – errno code if failure.

static inline int pwm_pin_cycles_to_usec(const struct device *dev, uint32_t pwm, uint32_t cycles, uint64_t *usec)¶

Convert from PWM cycles to microseconds.

Parameters

dev – Pointer to the device structure for the driver instance.
pwm – PWM pin.
cycles – Cycles to be converted.
usec – Pointer to the memory to store calculated usec.

Returns

0 – If successful.
-EIO – If cycles per second cannot be determined.
-ERANGE – If result is too large.

static inline int pwm_pin_cycles_to_nsec(const struct device *dev, uint32_t pwm, uint32_t cycles, uint64_t *nsec)¶

Convert from PWM cycles to nanoseconds.

Parameters

dev – Pointer to the device structure for the driver instance.
pwm – PWM pin.
cycles – Cycles to be converted.
nsec – Pointer to the memory to store the calculated nsec.

Returns

0 – If successful.
-EIO – If cycles per second cannot be determined.
-ERANGE – If result is too large.

static inline int pwm_pin_capture_usec(const struct device *dev, uint32_t pwm, pwm_flags_t flags, uint64_t *period, uint64_t *pulse, k_timeout_t timeout)¶

Capture a single PWM period/pulse width in microseconds for a single PWM input.

This API function wraps calls to pwm_pin_capture_cycles() and pwm_pin_cycles_to_usec() and passes the capture result to the caller. The function is blocking until either the PWM capture is completed or a timeout occurs.

Note

:kconfig:`CONFIG_PWM_CAPTURE` must be selected for this function to be available.

Parameters

dev – Pointer to the device structure for the driver instance.
pwm – PWM pin.
flags – PWM capture flags.
period – Pointer to the memory to store the captured PWM period width (in usec).
pulse – Pointer to the memory to store the captured PWM pulse width (in usec).
timeout – Waiting period for the capture to complete.

Returns

0 – If successful.
-EBUSY – PWM capture already in progress.
-EAGAIN – Waiting period timed out.
-EIO – IO error while capturing.
-ERANGE – If result is too large.

static inline int pwm_pin_capture_nsec(const struct device *dev, uint32_t pwm, pwm_flags_t flags, uint64_t *period, uint64_t *pulse, k_timeout_t timeout)¶

Capture a single PWM period/pulse width in nanoseconds for a single PWM input.

This API function wraps calls to pwm_pin_capture_cycles() and pwm_pin_cycles_to_nsec() and passes the capture result to the caller. The function is blocking until either the PWM capture is completed or a timeout occurs.

Note

:kconfig:`CONFIG_PWM_CAPTURE` must be selected for this function to be available.

Parameters

dev – Pointer to the device structure for the driver instance.
pwm – PWM pin.
flags – PWM capture flags.
period – Pointer to the memory to store the captured PWM period width (in nsec).
pulse – Pointer to the memory to store the captured PWM pulse width (in nsec).
timeout – Waiting period for the capture to complete.

Returns

0 – If successful.
-EBUSY – PWM capture already in progress.
-EAGAIN – Waiting period timed out.
-EIO – IO error while capturing.
-ERANGE – If result is too large.

struct pwm_driver_api¶: #include <pwm.h>

PWM driver API definition.