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

Return Value

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 Value

-EINVAL: if invalid function parameters were given
-ENOTSUP: 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 Value

0: If successful.
-EINVAL: if invalid function parameters were given
-ENOTSUP: 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 Value

0: If successful.
-EINVAL: if invalid function parameters were given
-ENOTSUP: 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 Value

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 Value

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 Value

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 Value

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 Value

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 Value

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 Value

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 Value

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.