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

CONFIG_PWM_CAPTURE must be selected to enable PWM capture support.

Param dev

Pointer to the device structure for the driver instance.

Param pwm

PWM pin.

Param period_cycles

Captured PWM period width (in clock cycles). HW specific.

Param pulse_cycles

Captured PWM pulse width (in clock cycles). HW specific.

Param status

Status for the PWM capture (0 if no error, negative errno otherwise. See pwm_pin_capture_cycles() return value descriptions for details).

Param 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).

Return values

  • 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

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

Return values

  • -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

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.

Return values

  • 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

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.

Return values

  • 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

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.

Return values

  • 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.

Return values

  • 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).

Return values

  • 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).

Return values

  • 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.

Return values

  • 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.

Return values

  • 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

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.

Return values

  • 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

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.

Return values

  • 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.