drivers: pwm: add API for capturing pwm pulse width and period

Extend the PWM API with optional API functions for capturing PWM pulse
width and period cycles.

Fixes #26026.

Signed-off-by: Henrik Brix Andersen <hebad@vestas.com>

doc/zephyr.doxyfile.in

@@ -1979,6 +1979,7 @@ PREDEFINED             = "CONFIG_ARCH_HAS_CUSTOM_BUSY_WAIT" \
                          "CONFIG_NET_MGMT_EVENT" \
                          "CONFIG_NET_TCP" \
                          "CONFIG_NET_UDP" \
+                         "CONFIG_PWM_CAPTURE" \
                          "CONFIG_SCHED_CPU_MASK" \
                          "CONFIG_SCHED_DEADLINE" \
                          "CONFIG_SCHED_DEADLINE" \

drivers/pwm/CMakeLists.txt

@@ -22,4 +22,5 @@ zephyr_library_sources_ifdef(CONFIG_PWM_NPCX		pwm_npcx.c)
 zephyr_library_sources_ifdef(CONFIG_PWM_XLNX_AXI_TIMER	pwm_xlnx_axi_timer.c)
 
 zephyr_library_sources_ifdef(CONFIG_USERSPACE   pwm_handlers.c)
+zephyr_library_sources_ifdef(CONFIG_PWM_CAPTURE pwm_capture.c)
 zephyr_library_sources_ifdef(CONFIG_PWM_SHELL   pwm_shell.c)

drivers/pwm/Kconfig

@@ -21,6 +21,12 @@ config PWM_SHELL
 	help
 	  Enable the PWM related shell commands.
 
+config PWM_CAPTURE
+	bool "Provide API for PWM capture"
+	help
+	  This option extends the Zephyr PWM API with the ability to capture PWM
+	  period/pulse widths.
+
 source "drivers/pwm/Kconfig.pca9685"
 
 source "drivers/pwm/Kconfig.dw"

drivers/pwm/pwm_capture.c

@@ -0,0 +1,85 @@
+/*
+ * Copyright (c) 2020-2021 Vestas Wind Systems A/S
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+
+#include <zephyr.h>
+#include <drivers/pwm.h>
+#include <logging/log.h>
+
+LOG_MODULE_REGISTER(pwm_capture, CONFIG_PWM_LOG_LEVEL);
+
+struct z_pwm_pin_capture_cb_data {
+	uint32_t period;
+	uint32_t pulse;
+	struct k_sem sem;
+	int status;
+};
+
+static void z_pwm_pin_capture_cycles_callback(const struct device *dev,
+					      uint32_t pwm,
+					      uint32_t period_cycles,
+					      uint32_t pulse_cycles,
+					      int status,
+					      void *user_data)
+{
+	struct z_pwm_pin_capture_cb_data *data = user_data;
+
+	data->period = period_cycles;
+	data->pulse = pulse_cycles;
+	data->status = status;
+
+	k_sem_give(&data->sem);
+}
+
+int z_impl_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)
+{
+	struct z_pwm_pin_capture_cb_data data;
+	int err;
+
+	if ((flags & PWM_CAPTURE_MODE_MASK) == PWM_CAPTURE_MODE_CONTINUOUS) {
+		LOG_ERR("continuous capture mode only supported via callback");
+		return -ENOTSUP;
+	}
+
+	flags |= PWM_CAPTURE_MODE_SINGLE;
+	k_sem_init(&data.sem, 0, 1);
+
+	err = pwm_pin_configure_capture(dev, pwm, flags,
+					z_pwm_pin_capture_cycles_callback,
+					&data);
+	if (err) {
+		LOG_ERR("failed to configure pwm capture");
+		return err;
+	}
+
+	err = pwm_pin_enable_capture(dev, pwm);
+	if (err) {
+		LOG_ERR("failed to enable pwm capture");
+		return err;
+	}
+
+	err = k_sem_take(&data.sem, timeout);
+	if (err == -EAGAIN) {
+		(void)pwm_pin_disable_capture(dev, pwm);
+		(void)pwm_pin_configure_capture(dev, pwm, flags, NULL, NULL);
+		LOG_WRN("pwm capture timed out");
+		return err;
+	}
+
+	if (data.status == 0) {
+		if (period != NULL) {
+			*period = data.period;
+		}
+
+		if (pulse != NULL) {
+			*pulse = data.pulse;
+		}
+	}
+
+	return data.status;
+}

drivers/pwm/pwm_handlers.c

@@ -1,5 +1,6 @@
 /*
  * Copyright (c) 2017 Intel Corporation
+ * Copyright (c) 2020-2021 Vestas Wind Systems A/S
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -29,3 +30,53 @@ static inline int z_vrfy_pwm_get_cycles_per_sec(const struct device *dev,
 					     pwm, (uint64_t *)cycles);
 }
 #include <syscalls/pwm_get_cycles_per_sec_mrsh.c>
+
+#ifdef CONFIG_PWM_CAPTURE
+
+static inline int z_vrfy_pwm_pin_enable_capture(const struct device *dev,
+						uint32_t pwm)
+{
+	Z_OOPS(Z_SYSCALL_DRIVER_PWM(dev, pin_enable_capture));
+	return z_impl_pwm_pin_enable_capture((const struct device *)dev, pwm);
+}
+#include <syscalls/pwm_pin_enable_capture_mrsh.c>
+
+static inline int z_vrfy_pwm_pin_disable_capture(const struct device *dev,
+						 uint32_t pwm)
+{
+	Z_OOPS(Z_SYSCALL_DRIVER_PWM(dev, pin_disable_capture));
+	return z_impl_pwm_pin_disable_capture((const struct device *)dev, pwm);
+}
+#include <syscalls/pwm_pin_disable_capture_mrsh.c>
+
+static inline int z_vrfy_pwm_pin_capture_cycles(const struct device *dev,
+						uint32_t pwm, pwm_flags_t flags,
+						uint32_t *period_cycles,
+						uint32_t *pulse_cycles,
+						k_timeout_t timeout)
+{
+	uint32_t period;
+	uint32_t pulse;
+	int err;
+
+	Z_OOPS(Z_SYSCALL_DRIVER_PWM(dev, pin_configure_capture));
+	Z_OOPS(Z_SYSCALL_DRIVER_PWM(dev, pin_enable_capture));
+	Z_OOPS(Z_SYSCALL_DRIVER_PWM(dev, pin_disable_capture));
+
+	err = z_impl_pwm_pin_capture_cycles((const struct device *)dev, pwm,
+					    flags, &period, &pulse, timeout);
+	if (period_cycles != NULL) {
+		Z_OOPS(z_user_to_copy(period_cycles, &period,
+				      sizeof(*period_cycles)));
+	}
+
+	if (pulse_cycles != NULL) {
+		Z_OOPS(z_user_to_copy(pulse_cycles, &pulse,
+				      sizeof(*pulse_cycles)));
+	}
+
+	return err;
+}
+#include <syscalls/pwm_pin_capture_cycles_mrsh.c>
+
+#endif /* CONFIG_PWM_CAPTURE */

include/drivers/pwm.h

@@ -1,5 +1,6 @@
 /*
  * Copyright (c) 2016 Intel Corporation.
+ * Copyright (c) 2020-2021 Vestas Wind Systems A/S
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -22,6 +23,7 @@
 #include <errno.h>
 #include <zephyr/types.h>
 #include <stddef.h>
+#include <sys/math_extras.h>
 #include <device.h>
 #include <dt-bindings/pwm/pwm.h>
 
@@ -29,6 +31,37 @@
 extern "C" {
 #endif
 
+/**
+ * @name PWM capture configuration flags
+ * @{
+ */
+
+/** @cond INTERNAL_HIDDEN */
+/* 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)
+/** @endcond */
+
+/** PWM pin capture captures period. */
+#define PWM_CAPTURE_TYPE_PERIOD		(1U << PWM_CAPTURE_TYPE_SHIFT)
+
+/** PWM pin capture captures pulse width. */
+#define PWM_CAPTURE_TYPE_PULSE		(2U << PWM_CAPTURE_TYPE_SHIFT)
+
+/** PWM pin capture captures both period and pulse width. */
+#define PWM_CAPTURE_TYPE_BOTH		(PWM_CAPTURE_TYPE_PERIOD | \
+					 PWM_CAPTURE_TYPE_PULSE)
+
+/* PWM pin capture captures a single period/pulse width. */
+#define PWM_CAPTURE_MODE_SINGLE		(0U << PWM_CAPTURE_MODE_SHIFT)
+
+/* PWM pin capture captures period/pulse width continuously. */
+#define PWM_CAPTURE_MODE_CONTINUOUS	(1U << PWM_CAPTURE_MODE_SHIFT)
+
+/** @} */
+
 /**
  * @brief Provides a type to hold PWM configuration flags.
  */
@@ -43,6 +76,59 @@ 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);
 
+/**
+ * @typedef pwm_capture_callback_handler_t
+ * @brief PWM capture callback handler function signature
+ *
+ * @note The callback handler will be called in interrupt context.
+ *
+ * @note @option{CONFIG_PWM_CAPTURE} must be selected for this function to be
+ * available.
+ *
+ * @param dev Pointer to the device structure for the driver instance.
+ * @param pwm PWM pin.
+
+ * @param period_cycles Captured PWM period width (in clock cycles). HW
+ *                      specific.
+ * @param pulse_cycles Captured PWM pulse width (in clock cycles). HW specific.
+ * @param status Status for the PWM capture (0 if no error, negative errno
+ *               otherwise. See @a pwm_pin_capture_cycles() return value
+ *               descriptions for details).
+ * @param user_data User data passed to @a pwm_pin_configure_capture()
+ */
+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);
+
+/**
+ * @typedef pwm_pin_configure_capture_t
+ * @brief Callback API upon configuring PWM pin capture
+ * See @a pwm_pin_configure_capture() for argument description
+ */
+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);
+/**
+ * @typedef pwm_pin_enable_capture_t
+ * @brief Callback API upon enabling PWM pin capture
+ * See @a pwm_pin_enable_capture() for argument description
+ */
+typedef int (*pwm_pin_enable_capture_t)(const struct device *dev,
+					uint32_t pwm);
+
+/**
+ * @typedef pwm_pin_disable_capture_t
+ * @brief Callback API upon disabling PWM pin capture
+ * See @a @a pwm_pin_disable_capture() for argument description
+ */
+typedef int (*pwm_pin_disable_capture_t)(const struct device *dev,
+					 uint32_t pwm);
+
 /**
  * @typedef pwm_get_cycles_per_sec_t
  * @brief Callback API upon getting cycles per second
@@ -55,6 +141,11 @@ typedef int (*pwm_get_cycles_per_sec_t)(const struct device *dev,
 /** @brief PWM driver API definition. */
 __subsystem struct pwm_driver_api {
 	pwm_pin_set_t pin_set;
+#ifdef CONFIG_PWM_CAPTURE
+	pwm_pin_configure_capture_t pin_configure_capture;
+	pwm_pin_enable_capture_t pin_enable_capture;
+	pwm_pin_disable_capture_t pin_disable_capture;
+#endif /* CONFIG_PWM_CAPTURE */
 	pwm_get_cycles_per_sec_t get_cycles_per_sec;
 };
 
@@ -89,6 +180,150 @@ static inline int z_impl_pwm_pin_set_cycles(const struct device *dev,
 	return api->pin_set(dev, pwm, period, pulse, flags);
 }
 
+/**
+ * @brief 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 @a pwm_pin_enable_capture() and @a
+ * 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 (@a
+ * pwm_pin_capture_cycles(), @a pwm_pin_capture_usec(), or @a
+ * pwm_pin_capture_nsec()) can be used instead.
+ *
+ * @note @option{CONFIG_PWM_CAPTURE} must be selected for this function to be
+ * available.
+ *
+ * @param dev Pointer to the device structure for the driver instance.
+ * @param pwm PWM pin.
+ * @param flags PWM capture flags
+ * @param cb Application callback handler function to be called upon capture
+ * @param user_data User data to pass to the application callback handler
+ *                  function
+ *
+ * @retval -EINVAL if invalid function parameters were given
+ * @retval -ENOTSUP if PWM capture is not supported or the given flags are not
+ *                  supported
+ * @retval -EIO if IO error occurred while configuring
+ * @retval -EBUSY if PWM capture is already in progress
+ */
+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);
+
+#ifdef CONFIG_PWM_CAPTURE
+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)
+{
+	const struct pwm_driver_api *api = (struct pwm_driver_api *)dev->api;
+
+	if (!api->pin_configure_capture) {
+		return -ENOTSUP;
+	}
+
+	return api->pin_configure_capture(dev, pwm, flags, cb, user_data);
+}
+#endif /* CONFIG_PWM_CAPTURE */
+
+/**
+ * @brief Enable PWM period/pulse width capture for a single PWM input.
+ *
+ * The PWM pin must be configured using @a pwm_pin_configure_capture() prior to
+ * calling this function.
+ *
+ * @note @option{CONFIG_PWM_CAPTURE} must be selected for this function to be
+ * available.
+ *
+ * @param dev Pointer to the device structure for the driver instance.
+ * @param pwm PWM pin.
+ *
+ * @retval 0 If successful.
+ * @retval Negative errno code if failure.
+ */
+__syscall int pwm_pin_enable_capture(const struct device *dev, uint32_t pwm);
+
+#ifdef CONFIG_PWM_CAPTURE
+static inline int z_impl_pwm_pin_enable_capture(const struct device *dev,
+						uint32_t pwm)
+{
+	const struct pwm_driver_api *api = (struct pwm_driver_api *)dev->api;
+
+	if (!api->pin_enable_capture) {
+		return -ENOTSUP;
+	}
+
+	return api->pin_enable_capture(dev, pwm);
+}
+#endif /* CONFIG_PWM_CAPTURE */
+
+/**
+ * @brief Disable PWM period/pulse width capture for a single PWM input.
+ *
+ *
+ * @note @option{CONFIG_PWM_CAPTURE} must be selected for this function to be
+ * available.
+ *
+ * @param dev Pointer to the device structure for the driver instance.
+ * @param pwm PWM pin.
+ *
+ * @retval 0 If successful.
+ * @retval Negative errno code if failure.
+ */
+__syscall int pwm_pin_disable_capture(const struct device *dev, uint32_t pwm);
+
+#ifdef CONFIG_PWM_CAPTURE
+static inline int z_impl_pwm_pin_disable_capture(const struct device *dev,
+						 uint32_t pwm)
+{
+	const struct pwm_driver_api *api = (struct pwm_driver_api *)dev->api;
+
+	if (!api->pin_disable_capture) {
+		return -ENOTSUP;
+	}
+
+	return api->pin_disable_capture(dev, pwm);
+}
+#endif /* CONFIG_PWM_CAPTURE */
+
+/**
+ * @brief Capture a single PWM period/pulse width in clock cycles for a single
+ *        PWM input.
+ *
+ * This API function wraps calls to @a pwm_pin_configure_capture(), @a
+ * pwm_pin_enable_capture(), and @a pwm_pin_disable_capture() and passes the
+ * capture results to the caller. The function is blocking until either the PWM
+ * capture is completed or a timeout occurs.
+ *
+ * @note @option{CONFIG_PWM_CAPTURE} must be selected for this function to be
+ * available.
+ *
+ * @param dev Pointer to the device structure for the driver instance.
+ * @param pwm PWM pin.
+ * @param flags PWM capture flags.
+ * @param period Pointer to the memory to store the captured PWM period width
+ *               (in clock cycles). HW specific.
+ * @param pulse Pointer to the memory to store the captured PWM pulse width (in
+ *              clock cycles). HW specific.
+ * @param timeout Waiting period for the capture to complete.
+ *
+ * @retval 0 If successful.
+ * @retval -EBUSY PWM capture already in progress.
+ * @retval -EAGAIN Waiting period timed out.
+ * @retval -EIO IO error while capturing.
+ * @retval -ERANGE If result is too large.
+ */
+__syscall 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);
+
 /**
  * @brief Get the clock rate (cycles per second) for a single PWM output.
  *
@@ -100,7 +335,6 @@ static inline int z_impl_pwm_pin_set_cycles(const struct device *dev,
  * @retval 0 If successful.
  * @retval Negative errno code if failure.
  */
-
 __syscall int pwm_get_cycles_per_sec(const struct device *dev, uint32_t pwm,
 				     uint64_t *cycles);
 
@@ -186,6 +420,180 @@ static inline int pwm_pin_set_nsec(const struct device *dev, uint32_t pwm,
 				  (uint32_t)pulse_cycles, flags);
 }
 
+/**
+ * @brief Convert from PWM cycles to microseconds.
+ *
+ * @param dev Pointer to the device structure for the driver instance.
+ * @param pwm PWM pin.
+ * @param cycles Cycles to be converted.
+ * @param usec Pointer to the memory to store calculated usec.
+ *
+ * @retval 0 If successful.
+ * @retval -EIO If cycles per second cannot be determined.
+ * @retval -ERANGE If result is too large.
+ */
+static inline int pwm_pin_cycles_to_usec(const struct device *dev, uint32_t pwm,
+					 uint32_t cycles, uint64_t *usec)
+{
+	uint64_t cycles_per_sec;
+	uint64_t temp;
+
+	if (pwm_get_cycles_per_sec(dev, pwm, &cycles_per_sec) != 0) {
+		return -EIO;
+	}
+
+	if (u64_mul_overflow(cycles, (uint64_t)USEC_PER_SEC, &temp)) {
+		return -ERANGE;
+	}
+
+	*usec = temp / cycles_per_sec;
+
+	return 0;
+}
+
+/**
+ * @brief Convert from PWM cycles to nanoseconds.
+ *
+ * @param dev Pointer to the device structure for the driver instance.
+ * @param pwm PWM pin.
+ * @param cycles Cycles to be converted.
+ * @param nsec Pointer to the memory to store the calculated nsec.
+ *
+ * @retval 0 If successful.
+ * @retval -EIO If cycles per second cannot be determined.
+ * @retval -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)
+{
+	uint64_t cycles_per_sec;
+	uint64_t temp;
+
+	if (pwm_get_cycles_per_sec(dev, pwm, &cycles_per_sec) != 0) {
+		return -EIO;
+	}
+
+	if (u64_mul_overflow(cycles, (uint64_t)NSEC_PER_SEC, &temp)) {
+		return -ERANGE;
+	}
+
+	*nsec = temp / cycles_per_sec;
+
+	return 0;
+}
+
+/**
+ * @brief Capture a single PWM period/pulse width in microseconds for a single
+ *        PWM input.
+ *
+ * This API function wraps calls to @a pwm_pin_capture_cycles() and @a
+ * pwm_pin_cycles_to_usec() and passes the capture results to the caller. The
+ * function is blocking until either the PWM capture is completed or a timeout
+ * occurs.
+ *
+ * @note @option{CONFIG_PWM_CAPTURE} must be selected for this function to be
+ * available.
+ *
+ * @param dev Pointer to the device structure for the driver instance.
+ * @param pwm PWM pin.
+ * @param flags PWM capture flags.
+ * @param period Pointer to the memory to store the captured PWM period width
+ *               (in usec).
+ * @param pulse Pointer to the memory to store the captured PWM pulse width (in
+ *              usec).
+ * @param timeout Waiting period for the capture to complete.
+ *
+ * @retval 0 If successful.
+ * @retval -EBUSY PWM capture already in progress.
+ * @retval -EAGAIN Waiting period timed out.
+ * @retval -EIO IO error while capturing.
+ * @retval -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)
+{
+	uint32_t period_cycles;
+	uint32_t pulse_cycles;
+	int err;
+
+	err = pwm_pin_capture_cycles(dev, pwm, flags, &period_cycles,
+				     &pulse_cycles, timeout);
+	if (err) {
+		return err;
+	}
+
+	err = pwm_pin_cycles_to_usec(dev, pwm, period_cycles, period);
+	if (err) {
+		return err;
+	}
+
+	err = pwm_pin_cycles_to_usec(dev, pwm, pulse_cycles, pulse);
+	if (err) {
+		return err;
+	}
+
+	return 0;
+}
+
+/**
+ * @brief Capture a single PWM period/pulse width in nanoseconds for a single
+ *        PWM input.
+ *
+ * This API function wraps calls to @a pwm_pin_capture_cycles() and @a
+ * pwm_pin_cycles_to_nsec() and passes the capture results to the caller. The
+ * function is blocking until either the PWM capture is completed or a timeout
+ * occurs.
+ *
+ * @note @option{CONFIG_PWM_CAPTURE} must be selected for this function to be
+ * available.
+ *
+ * @param dev Pointer to the device structure for the driver instance.
+ * @param pwm PWM pin.
+ * @param flags PWM capture flags.
+ * @param period Pointer to the memory to store the captured PWM period width
+ *               (in nsec).
+ * @param pulse Pointer to the memory to store the captured PWM pulse width (in
+ *              nsec).
+ * @param timeout Waiting period for the capture to complete.
+ *
+ * @retval 0 If successful.
+ * @retval -EBUSY PWM capture already in progress.
+ * @retval -EAGAIN Waiting period timed out.
+ * @retval -EIO IO error while capturing.
+ * @retval -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)
+{
+	uint32_t period_cycles;
+	uint32_t pulse_cycles;
+	int err;
+
+	err = pwm_pin_capture_cycles(dev, pwm, flags, &period_cycles,
+				     &pulse_cycles, timeout);
+	if (err) {
+		return err;
+	}
+
+	err = pwm_pin_cycles_to_nsec(dev, pwm, period_cycles, period);
+	if (err) {
+		return err;
+	}
+
+	err = pwm_pin_cycles_to_nsec(dev, pwm, pulse_cycles, pulse);
+	if (err) {
+		return err;
+	}
+
+	return 0;
+}
+
 #ifdef __cplusplus
 }
 #endif

include/dt-bindings/pwm/pwm.h

@@ -9,8 +9,8 @@
 /**
  * @name PWM polarity flags
  * The `PWM_POLARITY_*` flags are used with pwm_pin_set_cycles(),
- * pwm_pin_set_usec(), or pwm_pin_set_nsec() to specify the polarity
+ * pwm_pin_set_usec(), pwm_pin_set_nsec() or pwm_pin_configure_capture() to
- * of a PWM pin.
+ * specify the polarity of a PWM pin.
  * @{
  */
 /** PWM pin normal polarity (active-high pulse). */