Linux Documentation
 help / color / mirror / Atom feed
From: Jonathan Cameron <jic23@kernel.org>
To: Nicolae-Daniel Deaconescu <Nicolae-daniel.Deaconescu@analog.com>
Cc: "Uwe Kleine-König" <ukleinek@kernel.org>,
	"Conor Dooley" <conor+dt@kernel.org>,
	"Krzysztof Kozlowski" <krzk+dt@kernel.org>,
	"Rob Herring" <robh@kernel.org>,
	"David Lechner" <dlechner@baylibre.com>,
	"Nuno Sá" <nuno.sa@analog.com>,
	"Andy Shevchenko" <andy@kernel.org>,
	"Michael Hennerich" <michael.hennerich@analog.com>,
	"Trevor Gamblin" <tgamblin@baylibre.com>,
	"Joshua Crofts" <crofts@kernel.org>,
	"Sergiu Cuciurean" <sergiu.cuciurean@analog.com>,
	linux-iio@vger.kernel.org, devicetree@vger.kernel.org,
	linux-pwm@vger.kernel.org, linux-doc@vger.kernel.org,
	linux-kernel@vger.kernel.org
Subject: Re: [PATCH v4 1/6] pwm: core: add pwm_get_waveform_step_might_sleep()
Date: Sat, 21 Nov 2026 23:35:43 +0000	[thread overview]
Message-ID: <20261121233543.55426e1e@jic23-hlaptop> (raw)
In-Reply-To: <20261119112437.197306-2-Nicolae-daniel.Deaconescu@analog.com>

On Thu, 19 Nov 2026 13:24:15 +0200
Nicolae-Daniel Deaconescu <Nicolae-daniel.Deaconescu@analog.com> wrote:

> A consumer that must meet minimum times, or place an edge relative to the
> cycles of a clock a PWM gates, can't do that with the waveform API alone:
> rounding goes down, and the margin a minimum needs is the PWM step, known
> only to the provider.
> 
> Let the provider report the rate of the clock its timing derives from and
> the clock cycles per step. A consumer then works in whole steps and rounds
> up when converting to nanoseconds, instead of reading the rate from a clock
> it gets on its own, which breaks if the PWM divides its clock.
> 
> Signed-off-by: Nicolae-Daniel Deaconescu <Nicolae-daniel.Deaconescu@analog.com>
> ---
>  drivers/pwm/core.c  | 69 +++++++++++++++++++++++++++++++++++++++++++++
>  include/linux/pwm.h | 34 ++++++++++++++++++++++
>  2 files changed, 103 insertions(+)
> 
> diff --git a/drivers/pwm/core.c b/drivers/pwm/core.c
> index 2a050ff4608b..a63b8f65a43d 100644
> --- a/drivers/pwm/core.c
> +++ b/drivers/pwm/core.c
> @@ -14,6 +14,7 @@
>  #include <linux/of.h>
>  #include <linux/pwm.h>
>  #include <linux/list.h>
> +#include <linux/math64.h>
>  #include <linux/mutex.h>
>  #include <linux/err.h>
>  #include <linux/slab.h>
> @@ -325,6 +326,68 @@ int pwm_get_waveform_might_sleep(struct pwm_device *pwm, struct pwm_waveform *wf
>  }
>  EXPORT_SYMBOL_GPL(pwm_get_waveform_might_sleep);
>  
> +/**
> + * pwm_get_waveform_step_might_sleep - Query the granularity of the waveforms
> + * Cannot be used in atomic context.

Odd to have that second bit here in the kernel-doc. Particularly as you have
a Context entry below saying the same thing below and a name of _might_sleep.

> + * @pwm: PWM device
> + * @step: output parameter
> + *
> + * Stores in @step the clock rate the timing of @pwm is derived from and how
> + * many cycles of that clock one step lasts. Period, duty length and duty

Can this be a cross reference to the docs in for the structure?
Nice to not duplicate stuff where possible.

> + * offset are multiples of that step, so a waveform that is asked for in whole
> + * steps, and is within the range of the hardware, is not changed by rounding.
> + * Compute the length of n steps in nanoseconds as
> + * n * @step->clk_cycles_per_step * NSEC_PER_SEC / @step->clk_rate_Hz and round

I'd tweak the wrap to just have the formula on a line on its own.

> + * it up, because pwm_round_waveform_might_sleep() and
> + * pwm_set_waveform_might_sleep() round down. The product can exceed 64 bits, so
> + * compute it with mul_u64_u64_div_u64_roundup().

I don't understand this. I was thinking it was an implementation detail that
should not be in these docs anyway, but I can't immediately spot it at all.
So rewrite or drop.


> + *
> + * The values can change when a clock changes its rate, so they are only valid
> + * as long as the provider's input clocks are not reconfigured.
> + *
> + * Context: May sleep.
> + * Returns: 0 on success, -EOPNOTSUPP if the provider doesn't report it or a
> + * negative errno.
> + */
> +int pwm_get_waveform_step_might_sleep(struct pwm_device *pwm,
> +				      struct pwm_waveform_step *step)
> +{
> +	struct pwm_chip *chip = pwm->chip;
> +	const struct pwm_ops *ops = chip->ops;
> +	int ret;
> +
> +	might_sleep();
> +
> +	if (!pwmchip_supports_waveform(chip) || !ops->get_waveform_step)
> +		return -EOPNOTSUPP;
> +
> +	guard(pwmchip)(chip);
> +
> +	if (!chip->operational)
> +		return -ENODEV;
> +
> +	if (IS_ENABLED(CONFIG_PWM_DEBUG) && chip->atomic) {
> +		/*
> +		 * Catch any drivers that have been marked as atomic but
> +		 * that will sleep anyway.

Wrap comments to 80 chars unless it helps readability to not do so.

> +		 */
> +		non_block_start();
> +		ret = ops->get_waveform_step(chip, pwm, step);
> +		non_block_end();
> +	} else {
> +		ret = ops->get_waveform_step(chip, pwm, step);
> +	}
> +	if (ret)
> +		return ret;
> +
> +	if (!step->clk_rate_Hz ||
> +	    step->clk_rate_Hz > mul_u32_u32(step->clk_cycles_per_step, NSEC_PER_SEC))
> +		return -EINVAL;
> +
> +	return 0;
> +}
> +EXPORT_SYMBOL_GPL(pwm_get_waveform_step_might_sleep);
> +
>  /* Called with the pwmchip lock held */
>  static int __pwm_set_waveform(struct pwm_device *pwm,
>  			      const struct pwm_waveform *wf,
> @@ -1710,6 +1773,12 @@ static bool pwm_ops_check(const struct pwm_chip *chip)
>  		if (!ops->apply)
>  			return false;
>  
> +		if (ops->get_waveform_step) {
> +			dev_warn(pwmchip_parent(chip),
> +				 ".get_waveform_step() needs .write_waveform()\n");
> +			return false;
> +		}
> +
>  		if (IS_ENABLED(CONFIG_PWM_DEBUG) && !ops->get_state)
>  			dev_warn(pwmchip_parent(chip),
>  				 "Please implement the .get_state() callback\n");
> diff --git a/include/linux/pwm.h b/include/linux/pwm.h
> index b11ae91723f8..c52f4c9153c2 100644
> --- a/include/linux/pwm.h
> +++ b/include/linux/pwm.h
> @@ -76,6 +76,34 @@ struct pwm_waveform {
>  	u64 duty_offset_ns;
>  };
>  
> +/**
> + * struct pwm_waveform_step - granularity of the waveforms a PWM can generate
> + * @clk_rate_Hz: rate of the clock the PWM's timing is derived from
> + * @clk_cycles_per_step: number of those clock cycles one step lasts
> + *
> + * The period, the duty length and the duty offset of a waveform are multiples
> + * of one step, which lasts @clk_cycles_per_step / @clk_rate_Hz seconds. A PWM
> + * that divides its input clock in hardware has @clk_cycles_per_step > 1. A
> + * waveform that is asked for in whole steps, and is within the range of the
> + * hardware, is not changed by rounding.
> + *
> + * The step is the same for every waveform and for the period, the duty length
> + * and the duty offset, so a provider whose granularity depends on the
> + * requested period (for example through a prescaler) can't describe itself
> + * with it. One step also has to last at least 1 ns, otherwise rounding a
> + * length in nanoseconds up can add a whole step.
> + *
> + * A consumer that needs a minimum time, or that has to place an edge relative
> + * to the cycles of the clock a PWM channel gates, can use this to ask for
> + * the next possible value instead of one that is rounded down, and to compute
> + * the frequency a rounded period results in without the error of the
> + * nanosecond resolution of struct pwm_waveform.
> + */
> +struct pwm_waveform_step {
> +	unsigned long clk_rate_Hz;
> +	unsigned int clk_cycles_per_step;
> +};

For this to go through IIO (or an immutable branch if needed) I'll obviously
need PWM tags.

Thanks,

Jonathan


  reply	other threads:[~2026-11-21 23:35 UTC|newest]

Thread overview: 10+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2026-11-19 11:24 [PATCH v4 0/6] iio: adc: ad7625: add LTC2387 and ADAQ2387x support Nicolae-Daniel Deaconescu
2026-11-19 11:24 ` [PATCH v4 1/6] pwm: core: add pwm_get_waveform_step_might_sleep() Nicolae-Daniel Deaconescu
2026-11-21 23:35   ` Jonathan Cameron [this message]
2026-11-19 11:24 ` [PATCH v4 2/6] pwm: axi-pwmgen: report the waveform step Nicolae-Daniel Deaconescu
2026-11-19 11:24 ` [PATCH v4 3/6] iio: adc: ad7625: fix sampling frequency handling Nicolae-Daniel Deaconescu
2026-11-19 11:24 ` [PATCH v4 4/6] iio: adc: ad7625: move initial mode setup Nicolae-Daniel Deaconescu
2026-11-21 23:40   ` Jonathan Cameron
2026-11-19 11:24 ` [PATCH v4 5/6] dt-bindings: iio: adc: add adi,ltc2387 Nicolae-Daniel Deaconescu
2026-11-19 11:24 ` [PATCH v4 6/6] iio: adc: ad7625: add LTC2387 and ADAQ2387x support Nicolae-Daniel Deaconescu
2026-11-21 23:48   ` Jonathan Cameron

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20261121233543.55426e1e@jic23-hlaptop \
    --to=jic23@kernel.org \
    --cc=Nicolae-daniel.Deaconescu@analog.com \
    --cc=andy@kernel.org \
    --cc=conor+dt@kernel.org \
    --cc=crofts@kernel.org \
    --cc=devicetree@vger.kernel.org \
    --cc=dlechner@baylibre.com \
    --cc=krzk+dt@kernel.org \
    --cc=linux-doc@vger.kernel.org \
    --cc=linux-iio@vger.kernel.org \
    --cc=linux-kernel@vger.kernel.org \
    --cc=linux-pwm@vger.kernel.org \
    --cc=michael.hennerich@analog.com \
    --cc=nuno.sa@analog.com \
    --cc=robh@kernel.org \
    --cc=sergiu.cuciurean@analog.com \
    --cc=tgamblin@baylibre.com \
    --cc=ukleinek@kernel.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox