PWM Interface

PWM Interface. More...

Data Structures
struct	pwm_dt_spec
	Container for PWM information specified in devicetree. More...

Macros
#define	PWM_DT_SPEC_GET_BY_NAME(node_id, name)
	Static initializer for a struct pwm_dt_spec.
#define	PWM_DT_SPEC_INST_GET_BY_NAME(inst, name)    PWM_DT_SPEC_GET_BY_NAME(DT_DRV_INST(inst), name)
	Static initializer for a struct pwm_dt_spec from a DT_DRV_COMPAT instance.
#define	PWM_DT_SPEC_GET_BY_NAME_OR(node_id, name, default_value)
	Like PWM_DT_SPEC_GET_BY_NAME(), with a fallback to a default value.
#define	PWM_DT_SPEC_INST_GET_BY_NAME_OR(inst, name, default_value)    PWM_DT_SPEC_GET_BY_NAME_OR(DT_DRV_INST(inst), name, default_value)
	Like PWM_DT_SPEC_INST_GET_BY_NAME(), with a fallback to a default value.
#define	PWM_DT_SPEC_GET_BY_IDX(node_id, idx)
	Static initializer for a struct pwm_dt_spec.
#define	PWM_DT_SPEC_INST_GET_BY_IDX(inst, idx)    PWM_DT_SPEC_GET_BY_IDX(DT_DRV_INST(inst), idx)
	Static initializer for a struct pwm_dt_spec from a DT_DRV_COMPAT instance.
#define	PWM_DT_SPEC_GET_BY_IDX_OR(node_id, idx, default_value)
	Like PWM_DT_SPEC_GET_BY_IDX(), with a fallback to a default value.
#define	PWM_DT_SPEC_INST_GET_BY_IDX_OR(inst, idx, default_value)    PWM_DT_SPEC_GET_BY_IDX_OR(DT_DRV_INST(inst), idx, default_value)
	Like PWM_DT_SPEC_INST_GET_BY_IDX(), with a fallback to a default value.
#define	PWM_DT_SPEC_GET(node_id)   PWM_DT_SPEC_GET_BY_IDX(node_id, 0)
	Equivalent to PWM_DT_SPEC_GET_BY_IDX(node_id, 0).
#define	PWM_DT_SPEC_INST_GET(inst)   PWM_DT_SPEC_GET(DT_DRV_INST(inst))
	Equivalent to PWM_DT_SPEC_INST_GET_BY_IDX(inst, 0).
#define	PWM_DT_SPEC_GET_OR(node_id, default_value)    PWM_DT_SPEC_GET_BY_IDX_OR(node_id, 0, default_value)
	Equivalent to PWM_DT_SPEC_GET_BY_IDX_OR(node_id, 0, default_value).
#define	PWM_DT_SPEC_INST_GET_OR(inst, default_value)    PWM_DT_SPEC_GET_OR(DT_DRV_INST(inst), default_value)
	Equivalent to PWM_DT_SPEC_INST_GET_BY_IDX_OR(inst, 0, default_value).

Typedefs
typedef uint16_t	pwm_flags_t
	Provides a type to hold PWM configuration flags.
typedef void(*	pwm_capture_callback_handler_t) (const struct device *dev, uint32_t channel, uint32_t period_cycles, uint32_t pulse_cycles, int status, void *user_data)
	PWM capture callback handler function signature.

Functions
int	pwm_set_cycles (const struct device *dev, uint32_t channel, uint32_t period, uint32_t pulse, pwm_flags_t flags)
	Set the period and pulse width for a single PWM output.
int	pwm_get_cycles_per_sec (const struct device *dev, uint32_t channel, uint64_t *cycles)
	Get the clock rate (cycles per second) for a single PWM output.
static int	pwm_set (const struct device *dev, uint32_t channel, uint32_t period, uint32_t pulse, pwm_flags_t flags)
	Set the period and pulse width in nanoseconds for a single PWM output.
static int	pwm_set_dt (const struct pwm_dt_spec *spec, uint32_t period, uint32_t pulse)
	Set the period and pulse width in nanoseconds from a struct pwm_dt_spec (with custom period).
static int	pwm_set_pulse_dt (const struct pwm_dt_spec *spec, uint32_t pulse)
	Set the period and pulse width in nanoseconds from a struct pwm_dt_spec.
static int	pwm_cycles_to_usec (const struct device *dev, uint32_t channel, uint32_t cycles, uint64_t *usec)
	Convert from PWM cycles to microseconds.
static int	pwm_cycles_to_nsec (const struct device *dev, uint32_t channel, uint32_t cycles, uint64_t *nsec)
	Convert from PWM cycles to nanoseconds.
static int	pwm_configure_capture (const struct device *dev, uint32_t channel, pwm_flags_t flags, pwm_capture_callback_handler_t cb, void *user_data)
	Configure PWM period/pulse width capture for a single PWM input.
int	pwm_enable_capture (const struct device *dev, uint32_t channel)
	Enable PWM period/pulse width capture for a single PWM input.
int	pwm_disable_capture (const struct device *dev, uint32_t channel)
	Disable PWM period/pulse width capture for a single PWM input.
int	pwm_capture_cycles (const struct device *dev, uint32_t channel, 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.
static int	pwm_capture_usec (const struct device *dev, uint32_t channel, 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.
static int	pwm_capture_nsec (const struct device *dev, uint32_t channel, 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.
static bool	pwm_is_ready_dt (const struct pwm_dt_spec *spec)
	Validate that the PWM device is ready.

PWM capture configuration flags
#define	PWM_CAPTURE_TYPE_PERIOD   (1U << PWM_CAPTURE_TYPE_SHIFT)
	PWM pin capture captures period.
#define	PWM_CAPTURE_TYPE_PULSE   (2U << PWM_CAPTURE_TYPE_SHIFT)
	PWM pin capture captures pulse width.
#define	PWM_CAPTURE_TYPE_BOTH
	PWM pin capture captures both period and pulse width.
#define	PWM_CAPTURE_MODE_SINGLE   (0U << PWM_CAPTURE_MODE_SHIFT)
	PWM pin capture captures a single period/pulse width.
#define	PWM_CAPTURE_MODE_CONTINUOUS   (1U << PWM_CAPTURE_MODE_SHIFT)
	PWM pin capture captures period/pulse width continuously.

PWM period set helpers
The period cell in the PWM specifier needs to be provided in nanoseconds. However, in some applications it is more convenient to use another scale.
#define	PWM_NSEC(x)   (x)
	Specify PWM period in nanoseconds.
#define	PWM_USEC(x)   (PWM_NSEC(x) * 1000UL)
	Specify PWM period in microseconds.
#define	PWM_MSEC(x)   (PWM_USEC(x) * 1000UL)
	Specify PWM period in milliseconds.
#define	PWM_SEC(x)   (PWM_MSEC(x) * 1000UL)
	Specify PWM period in seconds.
#define	PWM_HZ(x)   (PWM_SEC(1UL) / (x))
	Specify PWM frequency in hertz.
#define	PWM_KHZ(x)   (PWM_HZ((x) * 1000UL))
	Specify PWM frequency in kilohertz.

PWM polarity flags
The PWM_POLARITY_* flags are used with pwm_set_cycles(), pwm_set() or pwm_configure_capture() to specify the polarity of a PWM channel. The flags are on the lower 8bits of the pwm_flags_t
#define	PWM_POLARITY_NORMAL   (0 << 0)
	PWM pin normal polarity (active-high pulse).
#define	PWM_POLARITY_INVERTED   (1 << 0)
	PWM pin inverted polarity (active-low pulse).

Detailed Description

PWM Interface.

Since

1.0

Version

1.0.0

Macro Definition Documentation

PWM_CAPTURE_MODE_CONTINUOUS

#define PWM_CAPTURE_MODE_CONTINUOUS   (1U << PWM_CAPTURE_MODE_SHIFT)

#include <include/zephyr/drivers/pwm.h>

PWM pin capture captures period/pulse width continuously.

PWM_CAPTURE_MODE_SINGLE

#define PWM_CAPTURE_MODE_SINGLE   (0U << PWM_CAPTURE_MODE_SHIFT)

#include <include/zephyr/drivers/pwm.h>

PWM pin capture captures a single period/pulse width.

PWM_CAPTURE_TYPE_BOTH

#define PWM_CAPTURE_TYPE_BOTH

#include <include/zephyr/drivers/pwm.h>

Value:

                                         (PWM_CAPTURE_TYPE_PERIOD | \
                                         PWM_CAPTURE_TYPE_PULSE)

PWM pin capture captures both period and pulse width.

PWM_CAPTURE_TYPE_PERIOD

#define PWM_CAPTURE_TYPE_PERIOD   (1U << PWM_CAPTURE_TYPE_SHIFT)

#include <include/zephyr/drivers/pwm.h>

PWM pin capture captures period.

PWM_CAPTURE_TYPE_PULSE

#define PWM_CAPTURE_TYPE_PULSE   (2U << PWM_CAPTURE_TYPE_SHIFT)

#include <include/zephyr/drivers/pwm.h>

PWM pin capture captures pulse width.

PWM_DT_SPEC_GET

#define PWM_DT_SPEC_GET

(

node_id

)

PWM_DT_SPEC_GET_BY_IDX(node_id, 0)

#include <include/zephyr/drivers/pwm.h>

Equivalent to PWM_DT_SPEC_GET_BY_IDX(node_id, 0).

Parameters

node_id

Devicetree node identifier.

Returns

Static initializer for a struct pwm_dt_spec for the property.

See also

PWM_DT_SPEC_GET_BY_IDX

PWM_DT_SPEC_INST_GET

PWM_DT_SPEC_GET_BY_IDX

#define PWM_DT_SPEC_GET_BY_IDX	(		node_id,
			idx
	)

#include <include/zephyr/drivers/pwm.h>

Value:

        {                                                                      \
                .dev = DEVICE_DT_GET(DT_PWMS_CTLR_BY_IDX(node_id, idx)),       \
                .channel = DT_PWMS_CHANNEL_BY_IDX(node_id, idx),               \
                .period = DT_PWMS_PERIOD_BY_IDX(node_id, idx),                 \
                .flags = DT_PWMS_FLAGS_BY_IDX(node_id, idx),                   \
        }

Static initializer for a struct pwm_dt_spec.

This returns a static initializer for a struct pwm_dt_spec given a devicetree node identifier and an index.

Example devicetree fragment:

n: node {
    pwms = <&pwm1 1 1000 PWM_POLARITY_NORMAL>,
           <&pwm2 3 2000 PWM_POLARITY_INVERTED>;
};

Example usage:

const struct pwm_dt_spec spec =
    PWM_DT_SPEC_GET_BY_IDX(DT_NODELABEL(n), 1);
 
// Initializes 'spec' to:
// {
//         .dev = DEVICE_DT_GET(DT_NODELABEL(pwm2)),
//         .channel = 3,
//         .period = 2000,
//         .flags = PWM_POLARITY_INVERTED,
// }

The device (dev) must still be checked for readiness, e.g. using device_is_ready(). It is an error to use this macro unless the node exists, has the 'pwms' property, and that 'pwms' property specifies a PWM controller, a channel, a period in nanoseconds and optionally flags.

Parameters

node_id	Devicetree node identifier.
idx	Logical index into 'pwms' property.

Returns

Static initializer for a struct pwm_dt_spec for the property.

See also

PWM_DT_SPEC_INST_GET_BY_IDX

PWM_DT_SPEC_GET_BY_IDX_OR

#define PWM_DT_SPEC_GET_BY_IDX_OR	(		node_id,
			idx,
			default_value
	)

#include <include/zephyr/drivers/pwm.h>

Value:

        COND_CODE_1(DT_NODE_HAS_PROP(node_id, pwms),                           \
                    (PWM_DT_SPEC_GET_BY_IDX(node_id, idx)),                    \
                    (default_value))

Like PWM_DT_SPEC_GET_BY_IDX(), with a fallback to a default value.

If the devicetree node identifier 'node_id' refers to a node with a property 'pwms', this expands to PWM_DT_SPEC_GET_BY_IDX(node_id, idx). The default_value parameter is not expanded in this case. Otherwise, this expands to default_value.

Parameters

node_id	Devicetree node identifier.
idx	Logical index into 'pwms' property.
default_value	Fallback value to expand to.

Returns

Static initializer for a struct pwm_dt_spec for the property, or default_value if the node or property do not exist.

See also

PWM_DT_SPEC_INST_GET_BY_IDX_OR

PWM_DT_SPEC_GET_BY_NAME

#define PWM_DT_SPEC_GET_BY_NAME	(		node_id,
			name
	)

#include <include/zephyr/drivers/pwm.h>

Value:

        {                                                                      \
                .dev = DEVICE_DT_GET(DT_PWMS_CTLR_BY_NAME(node_id, name)),     \
                .channel = DT_PWMS_CHANNEL_BY_NAME(node_id, name),             \
                .period = DT_PWMS_PERIOD_BY_NAME(node_id, name),               \
                .flags = DT_PWMS_FLAGS_BY_NAME(node_id, name),                 \
        }

Static initializer for a struct pwm_dt_spec.

This returns a static initializer for a struct pwm_dt_spec given a devicetree node identifier and an index.

Example devicetree fragment:

n: node {
    pwms = <&pwm1 1 1000 PWM_POLARITY_NORMAL>,
           <&pwm2 3 2000 PWM_POLARITY_INVERTED>;
    pwm-names = "alpha", "beta";
};

Example usage:

const struct pwm_dt_spec spec =
    PWM_DT_SPEC_GET_BY_NAME(DT_NODELABEL(n), alpha);
 
// Initializes 'spec' to:
// {
//         .dev = DEVICE_DT_GET(DT_NODELABEL(pwm1)),
//         .channel = 1,
//         .period = 1000,
//         .flags = PWM_POLARITY_NORMAL,
// }

The device (dev) must still be checked for readiness, e.g. using device_is_ready(). It is an error to use this macro unless the node exists, has the 'pwms' property, and that 'pwms' property specifies a PWM controller, a channel, a period in nanoseconds and optionally flags.

Parameters

node_id	Devicetree node identifier.
name	Lowercase-and-underscores name of a pwms element as defined by the node's pwm-names property.

Returns

Static initializer for a struct pwm_dt_spec for the property.

See also

PWM_DT_SPEC_INST_GET_BY_NAME

PWM_DT_SPEC_GET_BY_NAME_OR

#define PWM_DT_SPEC_GET_BY_NAME_OR	(		node_id,
			name,
			default_value
	)

#include <include/zephyr/drivers/pwm.h>

Value:

        COND_CODE_1(DT_NODE_HAS_PROP(node_id, pwms),                           \
                    (PWM_DT_SPEC_GET_BY_NAME(node_id, name)),                  \
                    (default_value))

Like PWM_DT_SPEC_GET_BY_NAME(), with a fallback to a default value.

If the devicetree node identifier 'node_id' refers to a node with a property 'pwms', this expands to PWM_DT_SPEC_GET_BY_NAME(node_id, name). The default_value parameter is not expanded in this case. Otherwise, this expands to default_value.

Parameters

node_id	Devicetree node identifier.
name	Lowercase-and-underscores name of a pwms element as defined by the node's pwm-names property
default_value	Fallback value to expand to.

Returns

Static initializer for a struct pwm_dt_spec for the property, or default_value if the node or property do not exist.

See also

PWM_DT_SPEC_INST_GET_BY_NAME_OR

PWM_DT_SPEC_GET_OR

#define PWM_DT_SPEC_GET_OR	(		node_id,
			default_value
	)		PWM_DT_SPEC_GET_BY_IDX_OR(node_id, 0, default_value)

#include <include/zephyr/drivers/pwm.h>

Equivalent to PWM_DT_SPEC_GET_BY_IDX_OR(node_id, 0, default_value).

Parameters

node_id	Devicetree node identifier.
default_value	Fallback value to expand to.

Returns

Static initializer for a struct pwm_dt_spec for the property.

See also

PWM_DT_SPEC_GET_BY_IDX_OR

PWM_DT_SPEC_INST_GET_OR

PWM_DT_SPEC_INST_GET

#define PWM_DT_SPEC_INST_GET

(

inst

)

PWM_DT_SPEC_GET(DT_DRV_INST(inst))

#include <include/zephyr/drivers/pwm.h>

Equivalent to PWM_DT_SPEC_INST_GET_BY_IDX(inst, 0).

Parameters

inst	DT_DRV_COMPAT instance number

Returns

Static initializer for a struct pwm_dt_spec for the property.

See also

PWM_DT_SPEC_INST_GET_BY_IDX

PWM_DT_SPEC_GET

PWM_DT_SPEC_INST_GET_BY_IDX

#define PWM_DT_SPEC_INST_GET_BY_IDX	(		inst,
			idx
	)		PWM_DT_SPEC_GET_BY_IDX(DT_DRV_INST(inst), idx)

#include <include/zephyr/drivers/pwm.h>

Static initializer for a struct pwm_dt_spec from a DT_DRV_COMPAT instance.

Parameters

inst	DT_DRV_COMPAT instance number
idx	Logical index into 'pwms' property.

Returns

Static initializer for a struct pwm_dt_spec for the property.

See also

PWM_DT_SPEC_GET_BY_IDX

PWM_DT_SPEC_INST_GET_BY_IDX_OR

#define PWM_DT_SPEC_INST_GET_BY_IDX_OR	(		inst,
			idx,
			default_value
	)		PWM_DT_SPEC_GET_BY_IDX_OR(DT_DRV_INST(inst), idx, default_value)

#include <include/zephyr/drivers/pwm.h>

Like PWM_DT_SPEC_INST_GET_BY_IDX(), with a fallback to a default value.

Parameters

inst	DT_DRV_COMPAT instance number
idx	Logical index into 'pwms' property.
default_value	Fallback value to expand to.

Returns

Static initializer for a struct pwm_dt_spec for the property, or default_value if the node or property do not exist.

See also

PWM_DT_SPEC_GET_BY_IDX_OR

PWM_DT_SPEC_INST_GET_BY_NAME

#define PWM_DT_SPEC_INST_GET_BY_NAME	(		inst,
			name
	)		PWM_DT_SPEC_GET_BY_NAME(DT_DRV_INST(inst), name)

#include <include/zephyr/drivers/pwm.h>

Static initializer for a struct pwm_dt_spec from a DT_DRV_COMPAT instance.

Parameters

inst	DT_DRV_COMPAT instance number
name	Lowercase-and-underscores name of a pwms element as defined by the node's pwm-names property.

Returns

Static initializer for a struct pwm_dt_spec for the property.

See also

PWM_DT_SPEC_GET_BY_NAME

PWM_DT_SPEC_INST_GET_BY_NAME_OR

#define PWM_DT_SPEC_INST_GET_BY_NAME_OR	(		inst,
			name,
			default_value
	)		PWM_DT_SPEC_GET_BY_NAME_OR(DT_DRV_INST(inst), name, default_value)

#include <include/zephyr/drivers/pwm.h>

Like PWM_DT_SPEC_INST_GET_BY_NAME(), with a fallback to a default value.

Parameters

inst	DT_DRV_COMPAT instance number
name	Lowercase-and-underscores name of a pwms element as defined by the node's pwm-names property.
default_value	Fallback value to expand to.

Returns

Static initializer for a struct pwm_dt_spec for the property, or default_value if the node or property do not exist.

See also

PWM_DT_SPEC_GET_BY_NAME_OR

PWM_DT_SPEC_INST_GET_OR

#define PWM_DT_SPEC_INST_GET_OR	(		inst,
			default_value
	)		PWM_DT_SPEC_GET_OR(DT_DRV_INST(inst), default_value)

#include <include/zephyr/drivers/pwm.h>

Equivalent to PWM_DT_SPEC_INST_GET_BY_IDX_OR(inst, 0, default_value).

Parameters

inst	DT_DRV_COMPAT instance number
default_value	Fallback value to expand to.

Returns

Static initializer for a struct pwm_dt_spec for the property.

See also

PWM_DT_SPEC_INST_GET_BY_IDX_OR

PWM_DT_SPEC_GET_OR

PWM_HZ

#define PWM_HZ

(

x

)

(PWM_SEC(1UL) / (x))

#include <include/zephyr/dt-bindings/pwm/pwm.h>

Specify PWM frequency in hertz.

PWM_KHZ

#define PWM_KHZ

(

x

)

(PWM_HZ((x) * 1000UL))

#include <include/zephyr/dt-bindings/pwm/pwm.h>

Specify PWM frequency in kilohertz.

PWM_MSEC

#define PWM_MSEC

(

x

)

(PWM_USEC(x) * 1000UL)

#include <include/zephyr/dt-bindings/pwm/pwm.h>

Specify PWM period in milliseconds.

PWM_NSEC

#define PWM_NSEC

(

x

)

(x)

#include <include/zephyr/dt-bindings/pwm/pwm.h>

Specify PWM period in nanoseconds.

PWM_POLARITY_INVERTED

#define PWM_POLARITY_INVERTED   (1 << 0)

#include <include/zephyr/dt-bindings/pwm/pwm.h>

PWM pin inverted polarity (active-low pulse).

PWM_POLARITY_NORMAL

#define PWM_POLARITY_NORMAL   (0 << 0)

#include <include/zephyr/dt-bindings/pwm/pwm.h>

PWM pin normal polarity (active-high pulse).

PWM_SEC

#define PWM_SEC

(

x

)

(PWM_MSEC(x) * 1000UL)

#include <include/zephyr/dt-bindings/pwm/pwm.h>

Specify PWM period in seconds.

PWM_USEC

#define PWM_USEC

(

x

)

(PWM_NSEC(x) * 1000UL)

#include <include/zephyr/dt-bindings/pwm/pwm.h>

Specify PWM period in microseconds.

Typedef Documentation

pwm_capture_callback_handler_t

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

#include <include/zephyr/drivers/pwm.h>

PWM capture callback handler function signature.

Note

The callback handler will be called in interrupt context.

CONFIG_PWM_CAPTURE 

must be selected to enable PWM capture support.

Parameters

[in]	dev	PWM device instance.
	channel	PWM channel.
	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_capture_cycles() return value descriptions for details).
	user_data	User data passed to pwm_configure_capture()

pwm_flags_t

typedef uint16_t pwm_flags_t

#include <include/zephyr/drivers/pwm.h>

Provides a type to hold PWM configuration flags.

The lower 8 bits are used for standard flags. The upper 8 bits are reserved for SoC specific flags.

See also

PWM_CAPTURE_FLAGS.

Function Documentation

pwm_capture_cycles()

int pwm_capture_cycles	(	const struct device *	dev,
		uint32_t	channel,
		pwm_flags_t	flags,
		uint32_t *	period,
		uint32_t *	pulse,
		k_timeout_t	timeout
	)

#include <include/zephyr/drivers/pwm.h>

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

This API function wraps calls to pwm_configure_capture(), pwm_enable_capture(), and pwm_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

[in]	dev	PWM device instance.
	channel	PWM channel.
	flags	PWM capture flags.
[out]	period	Pointer to the memory to store the captured PWM period width (in clock cycles). HW specific.
[out]	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.

pwm_capture_nsec()

static int pwm_capture_nsec ( const struct device *  dev, uint32_t  channel, pwm_flags_t  flags, uint64_t *  period, uint64_t *  pulse, k_timeout_t  timeout  )

inlinestatic

#include <include/zephyr/drivers/pwm.h>

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

This API function wraps calls to pwm_capture_cycles() and pwm_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

[in]	dev	PWM device instance.
	channel	PWM channel.
	flags	PWM capture flags.
[out]	period	Pointer to the memory to store the captured PWM period width (in nsec).
[out]	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.
-errno	Other negative errno code on failure.

pwm_capture_usec()

static int pwm_capture_usec ( const struct device *  dev, uint32_t  channel, pwm_flags_t  flags, uint64_t *  period, uint64_t *  pulse, k_timeout_t  timeout  )

inlinestatic

#include <include/zephyr/drivers/pwm.h>

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

This API function wraps calls to pwm_capture_cycles() and pwm_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

[in]	dev	PWM device instance.
	channel	PWM channel.
	flags	PWM capture flags.
[out]	period	Pointer to the memory to store the captured PWM period width (in usec).
[out]	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.
-errno	Other negative errno code on failure.

pwm_configure_capture()

static int pwm_configure_capture ( const struct device *  dev, uint32_t  channel, pwm_flags_t  flags, pwm_capture_callback_handler_t  cb, void *  user_data  )

inlinestatic

#include <include/zephyr/drivers/pwm.h>

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_enable_capture() and pwm_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_capture_cycles(), pwm_capture_usec(), or pwm_capture_nsec()) can be used instead.

CONFIG_PWM_CAPTURE 

must be selected for this function to be available.

Parameters

[in]	dev	PWM device instance.
	channel	PWM channel.
	flags	PWM capture flags
[in]	cb	Application callback handler function to be called upon capture
[in]	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

pwm_cycles_to_nsec()

static int pwm_cycles_to_nsec ( const struct device *  dev, uint32_t  channel, uint32_t  cycles, uint64_t *  nsec  )

inlinestatic

#include <include/zephyr/drivers/pwm.h>

Convert from PWM cycles to nanoseconds.

Parameters

[in]	dev	PWM device instance.
	channel	PWM channel.
	cycles	Cycles to be converted.
[out]	nsec	Pointer to the memory to store the calculated nsec.

Return values

0	If successful.
-ERANGE	If result is too large.
-errno	Other negative errno code on failure.

pwm_cycles_to_usec()

static int pwm_cycles_to_usec ( const struct device *  dev, uint32_t  channel, uint32_t  cycles, uint64_t *  usec  )

inlinestatic

#include <include/zephyr/drivers/pwm.h>

Convert from PWM cycles to microseconds.

Parameters

[in]	dev	PWM device instance.
	channel	PWM channel.
	cycles	Cycles to be converted.
[out]	usec	Pointer to the memory to store calculated usec.

Return values

0	If successful.
-ERANGE	If result is too large.
-errno	Other negative errno code on failure.

pwm_disable_capture()

int pwm_disable_capture	(	const struct device *	dev,
		uint32_t	channel
	)

#include <include/zephyr/drivers/pwm.h>

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

[in]	dev	PWM device instance.
	channel	PWM channel.

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

pwm_enable_capture()

int pwm_enable_capture	(	const struct device *	dev,
		uint32_t	channel
	)

#include <include/zephyr/drivers/pwm.h>

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

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

Note

CONFIG_PWM_CAPTURE 

must be selected for this function to be available.

Parameters

[in]	dev	PWM device instance.
	channel	PWM channel.

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

pwm_get_cycles_per_sec()

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

#include <include/zephyr/drivers/pwm.h>

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

Parameters

[in]	dev	PWM device instance.
	channel	PWM channel.
[out]	cycles	Pointer to the memory to store clock rate (cycles per sec). HW specific.

Return values

0	If successful.
-errno	Negative errno code on failure.

pwm_is_ready_dt()

static bool pwm_is_ready_dt ( const struct pwm_dt_spec *  spec )

inlinestatic

#include <include/zephyr/drivers/pwm.h>

Validate that the PWM device is ready.

Parameters

spec	PWM specification from devicetree

Return values

true	If the PWM device is ready for use
false	If the PWM device is not ready for use

pwm_set()

static int pwm_set ( const struct device *  dev, uint32_t  channel, uint32_t  period, uint32_t  pulse, pwm_flags_t  flags  )

inlinestatic

#include <include/zephyr/drivers/pwm.h>

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

Note

Utility macros such as PWM_MSEC() can be used to convert from other scales or units to nanoseconds, the units used by this function.

Parameters

[in]	dev	PWM device instance.
	channel	PWM channel.
	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.
-ENOTSUP	If requested period or pulse cycles are not supported.
-errno	Other negative errno code on failure.

pwm_set_cycles()

int pwm_set_cycles	(	const struct device *	dev,
		uint32_t	channel,
		uint32_t	period,
		uint32_t	pulse,
		pwm_flags_t	flags
	)

#include <include/zephyr/drivers/pwm.h>

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.

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.

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.

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

[in]	dev	PWM device instance.
	channel	PWM channel.
	period	Period (in clock cycles) set to the PWM. HW specific.
	pulse	Pulse width (in clock cycles) set to the PWM. HW specific.
	flags	Flags for pin configuration.

Return values

0	If successful.
-EINVAL	If pulse > period.
-errno	Negative errno code on failure.

pwm_set_dt()

static int pwm_set_dt ( const struct pwm_dt_spec *  spec, uint32_t  period, uint32_t  pulse  )

inlinestatic

#include <include/zephyr/drivers/pwm.h>

Set the period and pulse width in nanoseconds from a struct pwm_dt_spec (with custom period).

This is equivalent to:

pwm_set(spec->dev, spec->channel, period, pulse, spec->flags)

The period specified in spec is ignored. This API call can be used when the period specified in Devicetree needs to be changed at runtime.

Parameters

[in]	spec	PWM specification from devicetree.
	period	Period (in nanoseconds) set to the PWM.
	pulse	Pulse width (in nanoseconds) set to the PWM.

Returns

A value from pwm_set().

See also

pwm_set_pulse_dt()

pwm_set_pulse_dt()

static int pwm_set_pulse_dt ( const struct pwm_dt_spec *  spec, uint32_t  pulse  )

inlinestatic

#include <include/zephyr/drivers/pwm.h>

Set the period and pulse width in nanoseconds from a struct pwm_dt_spec.

This is equivalent to:

pwm_set(spec->dev, spec->channel, spec->period, pulse, spec->flags)

Parameters

[in]	spec	PWM specification from devicetree.
	pulse	Pulse width (in nanoseconds) set to the PWM.

Returns

A value from pwm_set().

See also

pwm_set_pulse_dt()