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-zeropulse
equal toperiod
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.
- Returns 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
- Returns -ENOSYS
if PWM capture is not supported or the given flags are not supported
- Returns -EIO
if IO error occurred while configuring
- Returns -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.
- Returns -EINVAL
if invalid function parameters were given
- Returns -ENOSYS
if PWM capture is not supported
- Returns -EIO
if IO error occurred while enabling PWM capture
- Returns -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.
- Returns -EINVAL
if invalid function parameters were given
- Returns -ENOSYS
if PWM capture is not supported
- Returns -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.
- Returns -EBUSY
PWM capture already in progress.
- Returns -EAGAIN
Waiting period timed out.
- Returns -EIO
IO error while capturing.
- Returns -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.
- Returns 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.
- Returns 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.
- Returns 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.
- Returns -EIO
If cycles per second cannot be determined.
- Returns -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.
- Returns -EIO
If cycles per second cannot be determined.
- Returns -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.
- Returns -EBUSY
PWM capture already in progress.
- Returns -EAGAIN
Waiting period timed out.
- Returns -EIO
IO error while capturing.
- Returns -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.
- Returns -EBUSY
PWM capture already in progress.
- Returns -EAGAIN
Waiting period timed out.
- Returns -EIO
IO error while capturing.
- Returns -ERANGE
If result is too large.
-
struct
pwm_driver_api
¶ - #include <pwm.h>
PWM driver API definition.
-