drivers: pwm: extend API to support events

Extend the PWM API to support events, as some
controllers allow interrupts if e.g., a pwm period
has ended or a fault occured.

Signed-off-by: Jaro Van Landschoot <jaro.vanlandschoot@basalte.be>

Author: javlands

drivers/pwm/Kconfig

@@ -32,6 +32,13 @@ config PWM_CAPTURE
 	  This option extends the Zephyr PWM API with the ability to capture PWM
 	  period/pulse widths.
 
+config PWM_EVENT
+	bool "Provide API for PWM event [EXPERIMENTAL]"
+	select EXPERIMENTAL
+	help
+	  This option extends the Zephyr PWM API with the ability to configure
+	  and receive PWM events.
+
 # zephyr-keep-sorted-start
 source "drivers/pwm/Kconfig.ambiq_timer"
 source "drivers/pwm/Kconfig.b91"

include/zephyr/drivers/pwm.h

@@ -1,6 +1,7 @@
 /*
  * 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
  */
@@ -35,6 +36,7 @@
 #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>
@@ -75,6 +77,27 @@ extern "C" {
 
 /** @} */
 
+/**
+ * @name PWM event types
+ * @anchor PWM_EVENT_TYPES
+ * @{
+ */
+
+#define PWM_EVENT_TYPE_SHIFT		0U
+
+/** Configure the event to trigger at the end of each PWM period */
+#define PWM_EVENT_TYPE_PERIOD		(1U << PWM_EVENT_TYPE_SHIFT)
+
+/** Configure the event to trigger at a fault. These can be used to
+ * react to error events that caused a change of behaviour of the PWM
+ * peripheral (often disabling the output). These error events can have
+ * an internal (e.g., oscillator malfunction) or external (e.g., pio)
+ * source
+ */
+#define PWM_EVENT_TYPE_FAULT		(2U << PWM_EVENT_TYPE_SHIFT)
+
+/** @} */
+
 /**
  * @brief Provides a type to hold PWM configuration flags.
  *
@@ -86,6 +109,14 @@ extern "C" {
 
 typedef uint16_t pwm_flags_t;
 
+/**
+ * @brief Provides a type to hold PWM events.
+ *
+ * @see @ref PWM_EVENT_TYPES.
+ */
+
+typedef uint16_t pwm_events_t;
+
 /**
  * @brief Container for PWM information specified in devicetree.
  *
@@ -400,6 +431,52 @@ typedef void (*pwm_capture_callback_handler_t)(const struct device *dev,
 					       uint32_t pulse_cycles,
 					       int status, void *user_data);
 
+struct pwm_event_callback;
+
+/**
+ * @brief PWM event callback handler function signature.
+ *
+ * @note The callback handler can be called in an interrupt context.
+ *
+ * @note @kconfig{CONFIG_PWM_EVENT} must be selected to enable PWM event
+ * support.
+ *
+ * @param[in] dev PWM device instance.
+ * @param callback Original struct gpio_callback owning this handler.
+ * @param channel PWM channel.
+ * @param events Event mask. See @ref PWM_EVENT_TYPES.
+ *
+ */
+typedef void (*pwm_event_callback_handler_t)(const struct device *dev,
+					     struct pwm_event_callback *callback, uint32_t channel,
+					     pwm_events_t events);
+
+/**
+ * @brief PWM event callback structure
+ *
+ * Used to register an event callback in the driver instance callback list.
+ * As many callbacks as needed can be added as long as each of them
+ * are unique pointers of struct pwm_event_callback.
+ * Beware such structure should not be allocated on stack.
+ *
+ * Note: to help setting it, see pwm_init_event_callback().
+ *
+ */
+struct pwm_event_callback {
+	/** @cond INTERNAL_HIDDEN */
+	sys_snode_t node;
+	/** @endcond */
+
+	/** Actual callback function being called when relevant. */
+	pwm_event_callback_handler_t handler;
+
+	/** Channel the callback is interested in. */
+	uint32_t channel;
+
+	/** A mask of events the callback is interested in. */
+	pwm_events_t event_mask;
+};
+
 /** @cond INTERNAL_HIDDEN */
 /**
  * @brief PWM driver API call to configure PWM pin period and pulse width.
@@ -440,6 +517,16 @@ typedef int (*pwm_disable_capture_t)(const struct device *dev,
 				     uint32_t channel);
 #endif /* CONFIG_PWM_CAPTURE */
 
+#ifdef CONFIG_PWM_EVENT
+
+/**
+ * @brief PWM driver API to manage callbacks for events.
+ * @see pwm_set_event_callback() and pwm_remove_event_callback() for argument description.
+ */
+typedef int (*pwm_manage_event_callback_t)(const struct device *dev,
+					   struct pwm_event_callback *callback, bool set);
+#endif /* CONFIG_PWM_EVENT */
+
 /** @brief PWM driver API definition. */
 __subsystem struct pwm_driver_api {
 	pwm_set_cycles_t set_cycles;
@@ -449,6 +536,9 @@ __subsystem struct pwm_driver_api {
 	pwm_enable_capture_t enable_capture;
 	pwm_disable_capture_t disable_capture;
 #endif /* CONFIG_PWM_CAPTURE */
+#ifdef CONFIG_PWM_EVENT
+	pwm_manage_event_callback_t manage_event_callback;
+#endif /* CONFIG_PWM_EVENT */
 };
 /** @endcond */
 
@@ -933,6 +1023,74 @@ static inline int pwm_capture_nsec(const struct device *dev, uint32_t channel,
 	return 0;
 }
 
+#if defined(CONFIG_PWM_EVENT) || defined(__DOXYGEN__)
+/**
+ * @brief Helper to initialize a struct pwm_event_callback properly.
+ *
+ * @param callback A valid application's callback structure pointer.
+ * @param handler A valid handler function pointer.
+ * @param channel Relevant channel for the handler.
+ * @param event_mask A bit mask of relevant events for the handler.
+ */
+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;
+}
+
+/**
+ * @brief Add an application event callback.
+ *
+ * @note As many callbacks as needed can be added on a PWM device instance.
+ *
+ * @param[in] dev PWM device instance.
+ * @param callback A valid applications callback structure pointer.
+ *
+ * @retval 0 on success.
+ * @retval -ENOSYS if driver does not manage event callbacks.
+ * @retval negative errno on failure.
+ */
+static inline int pwm_add_event_callback(const struct device *dev,
+					 struct pwm_event_callback *callback)
+{
+	const struct pwm_driver_api *api = (const struct pwm_driver_api *)dev->api;
+
+	if (api->manage_event_callback == NULL) {
+		return -ENOSYS;
+	}
+
+	return api->manage_event_callback(dev, callback, true);
+}
+
+/**
+ * @brief Remove an application event callback.
+ *
+ * @param[in] dev PWM device instance.
+ * @param callback A valid applications callback structure pointer.
+ *
+ * @retval 0 on success.
+ * @retval -ENOSYS if driver does not manage event callbacks.
+ * @retval negative errno on failure.
+ */
+static inline int pwm_remove_event_callback(const struct device *dev,
+					    struct pwm_event_callback *callback)
+{
+	const struct pwm_driver_api *api = (const struct pwm_driver_api *)dev->api;
+
+	if (api->manage_event_callback == NULL) {
+		return -ENOSYS;
+	}
+
+	return api->manage_event_callback(dev, callback, false);
+}
+#endif /* defined(CONFIG_PWM_EVENT) || defined(__DOXYGEN__) */
+
 /**
  * @brief Validate that the PWM device is ready.
  *

include/zephyr/drivers/pwm/pwm_utils.h

@@ -0,0 +1,82 @@
+/*
+ * Copyright (c) 2025 Basalte bv
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#ifndef ZEPHYR_INCLUDE_DRIVERS_PWM_PWM_UTILS_H_
+#define ZEPHYR_INCLUDE_DRIVERS_PWM_PWM_UTILS_H_
+
+#include <stdbool.h>
+#include <stdint.h>
+#include <errno.h>
+
+#include <zephyr/devicetree.h>
+#include <zephyr/drivers/pwm.h>
+#include <zephyr/sys/__assert.h>
+#include <zephyr/sys/slist.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief Generic function to insert or remove a callback from a callback list.
+ *
+ * @param callbacks A pointer to the original list of callbacks (can be NULL).
+ * @param callback A pointer of the callback to insert or remove from the list.
+ * @param set A boolean indicating insertion or removal of the callback.
+ *
+ * @retval 0 on success.
+ * @retval negate errno on failure.
+ */
+static inline int pwm_manage_event_callback(sys_slist_t *callbacks,
+					    struct pwm_event_callback *callback, bool set)
+{
+	__ASSERT_NO_MSG(callback != NULL);
+	__ASSERT_NO_MSG(callback->handler != NULL);
+
+	if (!sys_slist_is_empty(callbacks)) {
+		if (!sys_slist_find_and_remove(callbacks, &callback->node)) {
+			if (!set) {
+				return -EINVAL;
+			}
+		}
+	} else if (!set) {
+		return -EINVAL;
+	}
+
+	if (set) {
+		sys_slist_prepend(callbacks, &callback->node);
+	}
+
+	return 0;
+}
+
+/**
+ * @brief Generic function to go through and fire callback from a callback lists.
+ *
+ * @param list A pointer on the pwm event callback list.
+ * @param dev A pointer on the pwm driver instance.
+ * @param channel The channel that fired the interrupt.
+ * @param events The event that fired the interrupt.
+ */
+static inline void pwm_fire_event_callbacks(sys_slist_t *list, const struct device *dev,
+					    uint32_t channel, pwm_events_t events)
+{
+	struct pwm_event_callback *cb, *tmp;
+
+	SYS_SLIST_FOR_EACH_CONTAINER_SAFE(list, cb, tmp, node) {
+		if (cb->channel == channel) {
+			__ASSERT_NO_MSG(cb->handler != NULL);
+
+			cb->handler(dev, cb, channel, events);
+		}
+	}
+}
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* ZEPHYR_INCLUDE_DRIVERS_PWM_PWM_UTILS_H_ */