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.

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.

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.

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

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

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

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

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

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

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.