pwm.h

Go to the documentation of this file.

/*
 * Copyright (c) 2016 Intel Corporation.
 * Copyright (c) 2020-2021 Vestas Wind Systems A/S
 * Copyright (c) 2025 Basalte bv
 *
 * SPDX-License-Identifier: Apache-2.0
 */

 
#ifndef ZEPHYR_INCLUDE_DRIVERS_PWM_H_
#define ZEPHYR_INCLUDE_DRIVERS_PWM_H_

 
#include <errno.h>
#include <stdint.h>
 
#include <zephyr/device.h>
#include <zephyr/devicetree.h>
#include <zephyr/sys_clock.h>
#include <zephyr/sys/math_extras.h>
#include <zephyr/sys/slist.h>
#include <zephyr/toolchain.h>
 
#include <zephyr/dt-bindings/pwm/pwm.h>
 
#ifdef __cplusplus
extern "C" {
#endif


/* Bit 0 is used for PWM_POLARITY_NORMAL/PWM_POLARITY_INVERTED */
#define PWM_CAPTURE_TYPE_SHIFT          1U
#define PWM_CAPTURE_TYPE_MASK           (3U << PWM_CAPTURE_TYPE_SHIFT)
#define PWM_CAPTURE_MODE_SHIFT          3U
#define PWM_CAPTURE_MODE_MASK           (1U << PWM_CAPTURE_MODE_SHIFT)

#define PWM_CAPTURE_TYPE_PERIOD         (1U << PWM_CAPTURE_TYPE_SHIFT)

#define PWM_CAPTURE_TYPE_PULSE          (2U << PWM_CAPTURE_TYPE_SHIFT)

#define PWM_CAPTURE_TYPE_BOTH           (PWM_CAPTURE_TYPE_PERIOD | \
                                         PWM_CAPTURE_TYPE_PULSE)

#define PWM_CAPTURE_MODE_SINGLE         (0U << PWM_CAPTURE_MODE_SHIFT)

#define PWM_CAPTURE_MODE_CONTINUOUS     (1U << PWM_CAPTURE_MODE_SHIFT)


 
#define PWM_EVENT_TYPE_SHIFT            0U

#define PWM_EVENT_TYPE_PERIOD           (1U << PWM_EVENT_TYPE_SHIFT)

#define PWM_EVENT_TYPE_FAULT            (2U << PWM_EVENT_TYPE_SHIFT)

#define PWM_EVENT_TYPE_COMPARE_CAPTURE  (4U << PWM_EVENT_TYPE_SHIFT)


 
typedef uint16_t pwm_flags_t;

 
typedef uint16_t pwm_events_t;

struct pwm_dt_spec {
        const struct device *dev;
        uint32_t channel;
        uint32_t period;
        pwm_flags_t flags;
};

#define PWM_DT_SPEC_GET_BY_NAME(node_id, name)                                 \
        {                                                                      \
                .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),                 \
        }

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

#define PWM_DT_SPEC_GET_BY_NAME_OR(node_id, name, default_value)               \
        COND_CODE_1(DT_NODE_HAS_PROP(node_id, pwms),                           \
                    (PWM_DT_SPEC_GET_BY_NAME(node_id, name)),                  \
                    (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)

#define PWM_DT_SPEC_GET_BY_IDX(node_id, idx)                                   \
        {                                                                      \
                .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),                   \
        }

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

#define PWM_DT_SPEC_GET_BY_IDX_OR(node_id, idx, default_value)                 \
        COND_CODE_1(DT_NODE_HAS_PROP(node_id, pwms),                           \
                    (PWM_DT_SPEC_GET_BY_IDX(node_id, idx)),                    \
                    (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)

#define PWM_DT_SPEC_GET(node_id) PWM_DT_SPEC_GET_BY_IDX(node_id, 0)

#define PWM_DT_SPEC_INST_GET(inst) PWM_DT_SPEC_GET(DT_DRV_INST(inst))

#define PWM_DT_SPEC_GET_OR(node_id, default_value)                             \
        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)

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);
 
struct pwm_event_callback;

typedef void (*pwm_event_callback_handler_t)(const struct device *dev,
                                             struct pwm_event_callback *callback, uint32_t channel,
                                             pwm_events_t events);

struct pwm_event_callback {
        sys_snode_t node;

        pwm_event_callback_handler_t handler;

        uint32_t channel;

        pwm_events_t event_mask;
};


typedef int (*pwm_set_cycles_t)(const struct device *dev, uint32_t channel,
                                uint32_t period_cycles, uint32_t pulse_cycles,
                                pwm_flags_t flags);

typedef int (*pwm_get_cycles_per_sec_t)(const struct device *dev,
                                        uint32_t channel, uint64_t *cycles);
 
#if defined(CONFIG_PWM_CAPTURE) || defined(__DOXYGEN__)
typedef int (*pwm_configure_capture_t)(const struct device *dev,
                                       uint32_t channel, pwm_flags_t flags,
                                       pwm_capture_callback_handler_t cb,
                                       void *user_data);

typedef int (*pwm_enable_capture_t)(const struct device *dev, uint32_t channel);

typedef int (*pwm_disable_capture_t)(const struct device *dev,
                                     uint32_t channel);
#endif /* CONFIG_PWM_CAPTURE */
 
#if defined(CONFIG_PWM_EVENT) || defined(__DOXYGEN__)
typedef int (*pwm_manage_event_callback_t)(const struct device *dev,
                                           struct pwm_event_callback *callback, bool set);
#endif /* CONFIG_PWM_EVENT */

__subsystem struct pwm_driver_api {
        pwm_set_cycles_t set_cycles;
        pwm_get_cycles_per_sec_t get_cycles_per_sec;
#if defined(CONFIG_PWM_CAPTURE) || defined(__DOXYGEN__)
        pwm_configure_capture_t configure_capture;
        pwm_enable_capture_t enable_capture;
        pwm_disable_capture_t disable_capture;
#endif /* CONFIG_PWM_CAPTURE */
#if defined(CONFIG_PWM_EVENT) || defined(__DOXYGEN__)
        pwm_manage_event_callback_t manage_event_callback;
#endif /* CONFIG_PWM_EVENT */
};


__syscall int pwm_set_cycles(const struct device *dev, uint32_t channel,
                             uint32_t period, uint32_t pulse,
                             pwm_flags_t flags);
 
static inline int z_impl_pwm_set_cycles(const struct device *dev,
                                        uint32_t channel, uint32_t period,
                                        uint32_t pulse, pwm_flags_t flags)
{
        if (pulse > period) {
                return -EINVAL;
        }
 
        return DEVICE_API_GET(pwm, dev)->set_cycles(dev, channel, period, pulse, flags);
}

__syscall int pwm_get_cycles_per_sec(const struct device *dev, uint32_t channel,
                                     uint64_t *cycles);
 
static inline int z_impl_pwm_get_cycles_per_sec(const struct device *dev,
                                                uint32_t channel,
                                                uint64_t *cycles)
{
        return DEVICE_API_GET(pwm, dev)->get_cycles_per_sec(dev, channel, cycles);
}

static inline int pwm_set(const struct device *dev, uint32_t channel,
                          uint32_t period, uint32_t pulse, pwm_flags_t flags)
{
        int err;
        uint64_t pulse_cycles;
        uint64_t period_cycles;
        uint64_t cycles_per_sec;
 
        err = pwm_get_cycles_per_sec(dev, channel, &cycles_per_sec);
        if (err < 0) {
                return err;
        }
 
        period_cycles = (period * cycles_per_sec) / NSEC_PER_SEC;
        if (period_cycles > UINT32_MAX) {
                return -ENOTSUP;
        }
 
        pulse_cycles = (pulse * cycles_per_sec) / NSEC_PER_SEC;
        if (pulse_cycles > UINT32_MAX) {
                return -ENOTSUP;
        }
 
        return pwm_set_cycles(dev, channel, (uint32_t)period_cycles,
                              (uint32_t)pulse_cycles, flags);
}

static inline int pwm_set_dt(const struct pwm_dt_spec *spec, uint32_t period,
                             uint32_t pulse)
{
        return pwm_set(spec->dev, spec->channel, period, pulse, spec->flags);
}

static inline int pwm_set_pulse_dt(const struct pwm_dt_spec *spec,
                                   uint32_t pulse)
{
        return pwm_set(spec->dev, spec->channel, spec->period, pulse,
                       spec->flags);
}

static inline int pwm_cycles_to_usec(const struct device *dev, uint32_t channel,
                                     uint32_t cycles, uint64_t *usec)
{
        int err;
        uint64_t temp;
        uint64_t cycles_per_sec;
 
        err = pwm_get_cycles_per_sec(dev, channel, &cycles_per_sec);
        if (err < 0) {
                return err;
        }
 
        if (u64_mul_overflow(cycles, (uint64_t)USEC_PER_SEC, &temp)) {
                return -ERANGE;
        }
 
        *usec = temp / cycles_per_sec;
 
        return 0;
}

static inline int pwm_cycles_to_nsec(const struct device *dev, uint32_t channel,
                                     uint32_t cycles, uint64_t *nsec)
{
        int err;
        uint64_t temp;
        uint64_t cycles_per_sec;
 
        err = pwm_get_cycles_per_sec(dev, channel, &cycles_per_sec);
        if (err < 0) {
                return err;
        }
 
        if (u64_mul_overflow(cycles, (uint64_t)NSEC_PER_SEC, &temp)) {
                return -ERANGE;
        }
 
        *nsec = temp / cycles_per_sec;
 
        return 0;
}
 
#if defined(CONFIG_PWM_CAPTURE) || defined(__DOXYGEN__)
static inline int pwm_configure_capture(const struct device *dev,
                                        uint32_t channel, pwm_flags_t flags,
                                        pwm_capture_callback_handler_t cb,
                                        void *user_data)
{
        const struct pwm_driver_api *api = DEVICE_API_GET(pwm, dev);
 
        if (api->configure_capture == NULL) {
                return -ENOSYS;
        }
 
        return api->configure_capture(dev, channel, flags, cb,
                                              user_data);
}
#endif /* CONFIG_PWM_CAPTURE */

__syscall int pwm_enable_capture(const struct device *dev, uint32_t channel);
 
#ifdef CONFIG_PWM_CAPTURE
static inline int z_impl_pwm_enable_capture(const struct device *dev,
                                            uint32_t channel)
{
        const struct pwm_driver_api *api = DEVICE_API_GET(pwm, dev);
 
        if (api->enable_capture == NULL) {
                return -ENOSYS;
        }
 
        return api->enable_capture(dev, channel);
}
#endif /* CONFIG_PWM_CAPTURE */

__syscall int pwm_disable_capture(const struct device *dev, uint32_t channel);
 
#ifdef CONFIG_PWM_CAPTURE
static inline int z_impl_pwm_disable_capture(const struct device *dev,
                                             uint32_t channel)
{
        const struct pwm_driver_api *api = DEVICE_API_GET(pwm, dev);
 
        if (api->disable_capture == NULL) {
                return -ENOSYS;
        }
 
        return api->disable_capture(dev, channel);
}
#endif /* CONFIG_PWM_CAPTURE */

__syscall 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);

static inline 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)
{
        int err;
        uint32_t pulse_cycles;
        uint32_t period_cycles;
 
        err = pwm_capture_cycles(dev, channel, flags, &period_cycles,
                                 &pulse_cycles, timeout);
        if (err < 0) {
                return err;
        }
 
        err = pwm_cycles_to_usec(dev, channel, period_cycles, period);
        if (err < 0) {
                return err;
        }
 
        err = pwm_cycles_to_usec(dev, channel, pulse_cycles, pulse);
        if (err < 0) {
                return err;
        }
 
        return 0;
}

static inline 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)
{
        int err;
        uint32_t pulse_cycles;
        uint32_t period_cycles;
 
        err = pwm_capture_cycles(dev, channel, flags, &period_cycles,
                                 &pulse_cycles, timeout);
        if (err < 0) {
                return err;
        }
 
        err = pwm_cycles_to_nsec(dev, channel, period_cycles, period);
        if (err < 0) {
                return err;
        }
 
        err = pwm_cycles_to_nsec(dev, channel, pulse_cycles, pulse);
        if (err < 0) {
                return err;
        }
 
        return 0;
}
 
#if defined(CONFIG_PWM_EVENT) || defined(__DOXYGEN__)
static inline void pwm_init_event_callback(struct pwm_event_callback *callback,
                                           pwm_event_callback_handler_t handler, uint32_t channel,
                                           pwm_events_t event_mask)
{
        __ASSERT_NO_MSG(callback != NULL);
        __ASSERT_NO_MSG(handler != NULL);
 
        callback->handler = handler;
        callback->channel = channel;
        callback->event_mask = event_mask;
}

static inline int pwm_add_event_callback(const struct device *dev,
                                         struct pwm_event_callback *callback)
{
        const struct pwm_driver_api *api = DEVICE_API_GET(pwm, dev);
 
        if (api->manage_event_callback == NULL) {
                return -ENOSYS;
        }
 
        return api->manage_event_callback(dev, callback, true);
}

static inline int pwm_remove_event_callback(const struct device *dev,
                                            struct pwm_event_callback *callback)
{
        const struct pwm_driver_api *api = DEVICE_API_GET(pwm, dev);
 
        if (api->manage_event_callback == NULL) {
                return -ENOSYS;
        }
 
        return api->manage_event_callback(dev, callback, false);
}
#endif /* defined(CONFIG_PWM_EVENT) || defined(__DOXYGEN__) */

static inline bool pwm_is_ready_dt(const struct pwm_dt_spec *spec)
{
        return device_is_ready(spec->dev);
}
 
#ifdef __cplusplus
}
#endif

 
#include <zephyr/syscalls/pwm.h>
 
#endif /* ZEPHYR_INCLUDE_DRIVERS_PWM_H_ */