[RCC,1/6] pwm: Add different PWM output types support

From: Fenglin Wu <fenglinw@codeaurora.org>

Normally, PWM channel has fixed output until software request to change
its settings. There are some PWM devices which their outputs could be
changed autonomously according to a predefined pattern programmed in
hardware. Add pwm_output_type enum type to identify these two different
PWM types and add relevant helper functions to set and get PWM output
types and pattern.

Signed-off-by: Fenglin Wu <fenglinw@codeaurora.org>
[konradybcio@gmail.com: Fast-forward from kernel 4.14 to 5.8]
Signed-off-by: Konrad Dybcio <konradybcio@gmail.com>
Signed-off-by: Martin Botka <martin.botka1@gmail.com>
---
 drivers/pwm/core.c  | 26 +++++++++++++++++
 drivers/pwm/sysfs.c | 50 ++++++++++++++++++++++++++++++++
 include/linux/pwm.h | 69 +++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 145 insertions(+)

Hello,

On Fri, Jul 24, 2020 at 11:36:51PM +0200, Martin Botka wrote:
> From: Fenglin Wu <fenglinw@codeaurora.org>
> 
> Normally, PWM channel has fixed output until software request to change

"fixed" in the sense of "periodic", not "constant", right?

> its settings. There are some PWM devices which their outputs could be
> changed autonomously according to a predefined pattern programmed in
> hardware. Add pwm_output_type enum type to identify these two different
> PWM types and add relevant helper functions to set and get PWM output
> types and pattern.

You write "some devices". Which do you have in mind?

> [...]
> diff --git a/drivers/pwm/sysfs.c b/drivers/pwm/sysfs.c
> index 2389b8669846..4ee1e81db0bc 100644
> --- a/drivers/pwm/sysfs.c
> +++ b/drivers/pwm/sysfs.c

adapting the sysfs stuff should be done in a separate step.

> @@ -215,11 +215,60 @@ static ssize_t capture_show(struct device *child,
>  	return sprintf(buf, "%u %u\n", result.period, result.duty_cycle);
>  }
>  
> +static ssize_t output_type_show(struct device *child,
> +							struct device_attribute *attr,
> +							char *buf)
> +{
> +	const struct pwm_device *pwm = child_to_pwm_device(child);
> +	const char *output_type = "unknown";
> +	struct pwm_state state;
> +
> +	pwm_get_state(pwm, &state);
> +	switch (state.output_type) {
> +	case PWM_OUTPUT_FIXED:
> +		output_type = "fixed";
> +		break;
> +	case PWM_OUTPUT_MODULATED:
> +		output_type = "modulated";
> +		break;
> +	default:
> +		break;
> +	}
> +
> +	return snprintf(buf, PAGE_SIZE, "%s\n", output_type);
> +}
> +
> +static ssize_t output_type_store(struct device *child,
> +								struct device_attribute *attr,
> +								const char *buf, size_t size)

Indention is broken here. Please align to the opening (.

> +{
> +	struct pwm_export *export = child_to_pwm_export(child);
> +	struct pwm_device *pwm = export->pwm;
> +	struct pwm_state state;
> +	int ret = -EINVAL;
> +
> +	mutex_lock(&export->lock);
> +	pwm_get_state(pwm, &state);
> +	if (sysfs_streq(buf, "fixed"))
> +		state.output_type = PWM_OUTPUT_FIXED;
> +	else if (sysfs_streq(buf, "modulated"))
> +		state.output_type = PWM_OUTPUT_MODULATED;
> +	else
> +		goto unlock;
> +
> +	ret = pwm_apply_state(pwm, &state);
> +unlock:
> +	mutex_unlock(&export->lock);
> +
> +	return ret ? : size;
> +}
> +
>  static DEVICE_ATTR_RW(period);
>  static DEVICE_ATTR_RW(duty_cycle);
>  static DEVICE_ATTR_RW(enable);
>  static DEVICE_ATTR_RW(polarity);
>  static DEVICE_ATTR_RO(capture);
> +static DEVICE_ATTR_RW(output_type);
>  
>  static struct attribute *pwm_attrs[] = {
>  	&dev_attr_period.attr,
> @@ -227,6 +276,7 @@ static struct attribute *pwm_attrs[] = {
>  	&dev_attr_enable.attr,
>  	&dev_attr_polarity.attr,
>  	&dev_attr_capture.attr,
> +	&dev_attr_output_type.attr,
>  	NULL
>  };
>  ATTRIBUTE_GROUPS(pwm);
> diff --git a/include/linux/pwm.h b/include/linux/pwm.h
> index 2635b2a55090..10a102efadc4 100644
> --- a/include/linux/pwm.h
> +++ b/include/linux/pwm.h
> @@ -48,6 +48,29 @@ enum {
>  	PWMF_EXPORTED = 1 << 1,
>  };
>  
> +/*
> + * enum pwm_output_type - output type of the PWM signal
> + * @PWM_OUTPUT_FIXED: PWM output is fixed until a change request
> + * @PWM_OUTPUT_MODULATED: PWM output is modulated in hardware
> + * autonomously with a predefined pattern
> + */
> +enum pwm_output_type {
> +	PWM_OUTPUT_FIXED = 1 << 0,
> +	PWM_OUTPUT_MODULATED = 1 << 1,
> +};
> +
> +/*
> + * struct pwm_output_pattern - PWM duty pattern for MODULATED duty type
> + * @duty_pattern: PWM duty cycles in the pattern for duty modulation
> + * @num_entries: number of entries in the pattern
> + * @cycles_per_duty: number of PWM period cycles an entry stays at
> + */
> +struct pwm_output_pattern {
> +	unsigned int *duty_pattern;
> +	unsigned int num_entries;
> +	unsigned int cycles_per_duty;
> +};

I don't understand the semantics here. (i.e. how does a given
pwm_output_pattern map to the intended wave form?)

> +
>  /*
>   * struct pwm_state - state of a PWM channel
>   * @period: PWM period (in nanoseconds)
> @@ -59,6 +82,8 @@ struct pwm_state {
>  	unsigned int period;
>  	unsigned int duty_cycle;
>  	enum pwm_polarity polarity;
> +	enum pwm_output_type output_type;
> +	struct pwm_output_pattern *output_pattern;
>  	bool enabled;
>  };
>  
> @@ -146,6 +171,26 @@ static inline enum pwm_polarity pwm_get_polarity(const struct pwm_device *pwm)
>  	return state.polarity;
>  }
>  
> +static inline enum pwm_output_type pwm_get_output_type(
> +				const struct pwm_device *pwm)
> +{
> +	struct pwm_state state;
> +
> +	pwm_get_state(pwm, &state);
> +
> +	return state.output_type;
> +}
> +
> +static inline struct pwm_output_pattern *pwm_get_output_pattern(
> +				struct pwm_device *pwm)
> +{
> +	struct pwm_state state;
> +
> +	pwm_get_state(pwm, &state);
> +
> +	return pwm->state.output_pattern ?: NULL;

Who is the owner of the data behind this pointer? Is it expected to be
valid only until the next call to change the output? What happens if the
caller modifies the data returned?

> +}
> +
>  static inline void pwm_get_args(const struct pwm_device *pwm,
>  				struct pwm_args *args)
>  {
> @@ -254,6 +299,9 @@ pwm_set_relative_duty_cycle(struct pwm_state *state, unsigned int duty_cycle,
>   * @set_polarity: configure the polarity of this PWM
>   * @enable: enable PWM output toggling
>   * @disable: disable PWM output toggling
> + * @get_output_type_supported: get the supported output type
> + * @set_output_type: set PWM output type
> + * @set_output_pattern: set the pattern for the modulated output
>   */
>  struct pwm_ops {
>  	int (*request)(struct pwm_chip *chip, struct pwm_device *pwm);
> @@ -273,6 +321,13 @@ struct pwm_ops {
>  			    enum pwm_polarity polarity);
>  	int (*enable)(struct pwm_chip *chip, struct pwm_device *pwm);
>  	void (*disable)(struct pwm_chip *chip, struct pwm_device *pwm);
> +	int (*get_output_type_supported)(struct pwm_chip *chip,
> +			    struct pwm_device *pwm);
> +	int (*set_output_type)(struct pwm_chip *chip, struct pwm_device *pwm,
> +			    enum pwm_output_type output_type);
> +	int (*set_output_pattern)(struct pwm_chip *chip,
> +			    struct pwm_device *pwm,
> +			    struct pwm_output_pattern *output_pattern);

This doesn't match the atomic approach that we're following since the
introduction of .apply. Please don't add new non-atomic callbacks.

>  };
>  
>  /**
> @@ -318,6 +373,20 @@ void pwm_free(struct pwm_device *pwm);
>  int pwm_apply_state(struct pwm_device *pwm, const struct pwm_state *state);
>  int pwm_adjust_config(struct pwm_device *pwm);
>  
> +/*
> + * pwm_output_type_support()
> + * @pwm: PWM device
> + *
> + * Returns:  output types supported by the PWM device
> + */
> +static inline int pwm_get_output_type_supported(struct pwm_device *pwm)
> +{
> +	if (pwm->chip->ops->get_output_type_supported != NULL)
> +		return pwm->chip->ops->get_output_type_supported(pwm->chip, pwm);
> +	else
> +		return PWM_OUTPUT_FIXED;
> +}

I don't like this "advertising" for specific functions. I'd prefer to
handle this in .apply(), fix all drivers to return -ESOMETHING when the
request cannot be fulfilled.

Having said that I wonder if this output pattern is a common enough
property to add support for it in the PWM framework.

If the only usage is to drive a LED this might maybe better be a
dedicated LED driver? (Though I'm not sure this is a good idea either.)

Best regards
Uwe

Mo 27. 7. 2020 at 22:10 Uwe Kleine-König <u.kleine-koenig@pengutronix.de> wrote:
>
> Hello,
>
> On Fri, Jul 24, 2020 at 11:36:51PM +0200, Martin Botka wrote:
> > From: Fenglin Wu <fenglinw@codeaurora.org>
> >
> > Normally, PWM channel has fixed output until software request to change
>
> "fixed" in the sense of "periodic", not "constant", right?

Correct.

>
> > its settings. There are some PWM devices which their outputs could be
> > changed autonomously according to a predefined pattern programmed in
> > hardware. Add pwm_output_type enum type to identify these two different
> > PWM types and add relevant helper functions to set and get PWM output
> > types and pattern.
>
> You write "some devices". Which do you have in mind?

As can be seen this commit is not authored by me so the commit message
is from the original author.
So i don't know what the original author meant here.
I can only guess that s/he meant all the PWM chips made by Qcom or
other companies that also have hardware based support for patterns.

>
> > [...]
> > diff --git a/drivers/pwm/sysfs.c b/drivers/pwm/sysfs.c
> > index 2389b8669846..4ee1e81db0bc 100644
> > --- a/drivers/pwm/sysfs.c
> > +++ b/drivers/pwm/sysfs.c
>
> adapting the sysfs stuff should be done in a separate step.

By that you mean in separate commit right ?

>
> > @@ -215,11 +215,60 @@ static ssize_t capture_show(struct device *child,
> >       return sprintf(buf, "%u %u\n", result.period, result.duty_cycle);
> >  }
> >
> > +static ssize_t output_type_show(struct device *child,
> > +                                                     struct device_attribute *attr,
> > +                                                     char *buf)
> > +{
> > +     const struct pwm_device *pwm = child_to_pwm_device(child);
> > +     const char *output_type = "unknown";
> > +     struct pwm_state state;
> > +
> > +     pwm_get_state(pwm, &state);
> > +     switch (state.output_type) {
> > +     case PWM_OUTPUT_FIXED:
> > +             output_type = "fixed";
> > +             break;
> > +     case PWM_OUTPUT_MODULATED:
> > +             output_type = "modulated";
> > +             break;
> > +     default:
> > +             break;
> > +     }
> > +
> > +     return snprintf(buf, PAGE_SIZE, "%s\n", output_type);
> > +}
> > +
> > +static ssize_t output_type_store(struct device *child,
> > +                                                             struct device_attribute *attr,
> > +                                                             const char *buf, size_t size)
>
> Indention is broken here. Please align to the opening (.

OK. Will do.

>
> > +{
> > +     struct pwm_export *export = child_to_pwm_export(child);
> > +     struct pwm_device *pwm = export->pwm;
> > +     struct pwm_state state;
> > +     int ret = -EINVAL;
> > +
> > +     mutex_lock(&export->lock);
> > +     pwm_get_state(pwm, &state);
> > +     if (sysfs_streq(buf, "fixed"))
> > +             state.output_type = PWM_OUTPUT_FIXED;
> > +     else if (sysfs_streq(buf, "modulated"))
> > +             state.output_type = PWM_OUTPUT_MODULATED;
> > +     else
> > +             goto unlock;
> > +
> > +     ret = pwm_apply_state(pwm, &state);
> > +unlock:
> > +     mutex_unlock(&export->lock);
> > +
> > +     return ret ? : size;
> > +}
> > +
> >  static DEVICE_ATTR_RW(period);
> >  static DEVICE_ATTR_RW(duty_cycle);
> >  static DEVICE_ATTR_RW(enable);
> >  static DEVICE_ATTR_RW(polarity);
> >  static DEVICE_ATTR_RO(capture);
> > +static DEVICE_ATTR_RW(output_type);
> >
> >  static struct attribute *pwm_attrs[] = {
> >       &dev_attr_period.attr,
> > @@ -227,6 +276,7 @@ static struct attribute *pwm_attrs[] = {
> >       &dev_attr_enable.attr,
> >       &dev_attr_polarity.attr,
> >       &dev_attr_capture.attr,
> > +     &dev_attr_output_type.attr,
> >       NULL
> >  };
> >  ATTRIBUTE_GROUPS(pwm);
> > diff --git a/include/linux/pwm.h b/include/linux/pwm.h
> > index 2635b2a55090..10a102efadc4 100644
> > --- a/include/linux/pwm.h
> > +++ b/include/linux/pwm.h
> > @@ -48,6 +48,29 @@ enum {
> >       PWMF_EXPORTED = 1 << 1,
> >  };
> >
> > +/*
> > + * enum pwm_output_type - output type of the PWM signal
> > + * @PWM_OUTPUT_FIXED: PWM output is fixed until a change request
> > + * @PWM_OUTPUT_MODULATED: PWM output is modulated in hardware
> > + * autonomously with a predefined pattern
> > + */
> > +enum pwm_output_type {
> > +     PWM_OUTPUT_FIXED = 1 << 0,
> > +     PWM_OUTPUT_MODULATED = 1 << 1,
> > +};
> > +
> > +/*
> > + * struct pwm_output_pattern - PWM duty pattern for MODULATED duty type
> > + * @duty_pattern: PWM duty cycles in the pattern for duty modulation
> > + * @num_entries: number of entries in the pattern
> > + * @cycles_per_duty: number of PWM period cycles an entry stays at
> > + */
> > +struct pwm_output_pattern {
> > +     unsigned int *duty_pattern;
> > +     unsigned int num_entries;
> > +     unsigned int cycles_per_duty;
> > +};
>
> I don't understand the semantics here. (i.e. how does a given
> pwm_output_pattern map to the intended wave form?)

I did not understand that part either.
It's not uncommon for Qcom to have some stuff hidden like this in
other drivers that we have in downstream (Tho they mainly hide that in
pre-compiled binary blobs).
Here it's either the missing PBS driver from downstream that i want to
send later in separate series.
Or that it's fully done in hardware. Unlikely but you never know with Qcom.


>
> > +
> >  /*
> >   * struct pwm_state - state of a PWM channel
> >   * @period: PWM period (in nanoseconds)
> > @@ -59,6 +82,8 @@ struct pwm_state {
> >       unsigned int period;
> >       unsigned int duty_cycle;
> >       enum pwm_polarity polarity;
> > +     enum pwm_output_type output_type;
> > +     struct pwm_output_pattern *output_pattern;
> >       bool enabled;
> >  };
> >
> > @@ -146,6 +171,26 @@ static inline enum pwm_polarity pwm_get_polarity(const struct pwm_device *pwm)
> >       return state.polarity;
> >  }
> >
> > +static inline enum pwm_output_type pwm_get_output_type(
> > +                             const struct pwm_device *pwm)
> > +{
> > +     struct pwm_state state;
> > +
> > +     pwm_get_state(pwm, &state);
> > +
> > +     return state.output_type;
> > +}
> > +
> > +static inline struct pwm_output_pattern *pwm_get_output_pattern(
> > +                             struct pwm_device *pwm)
> > +{
> > +     struct pwm_state state;
> > +
> > +     pwm_get_state(pwm, &state);
> > +
> > +     return pwm->state.output_pattern ?: NULL;
>
> Who is the owner of the data behind this pointer? Is it expected to be
> valid only until the next call to change the output? What happens if the
> caller modifies the data returned?
>
> > +}
> > +
> >  static inline void pwm_get_args(const struct pwm_device *pwm,
> >                               struct pwm_args *args)
> >  {
> > @@ -254,6 +299,9 @@ pwm_set_relative_duty_cycle(struct pwm_state *state, unsigned int duty_cycle,
> >   * @set_polarity: configure the polarity of this PWM
> >   * @enable: enable PWM output toggling
> >   * @disable: disable PWM output toggling
> > + * @get_output_type_supported: get the supported output type
> > + * @set_output_type: set PWM output type
> > + * @set_output_pattern: set the pattern for the modulated output
> >   */
> >  struct pwm_ops {
> >       int (*request)(struct pwm_chip *chip, struct pwm_device *pwm);
> > @@ -273,6 +321,13 @@ struct pwm_ops {
> >                           enum pwm_polarity polarity);
> >       int (*enable)(struct pwm_chip *chip, struct pwm_device *pwm);
> >       void (*disable)(struct pwm_chip *chip, struct pwm_device *pwm);
> > +     int (*get_output_type_supported)(struct pwm_chip *chip,
> > +                         struct pwm_device *pwm);
> > +     int (*set_output_type)(struct pwm_chip *chip, struct pwm_device *pwm,
> > +                         enum pwm_output_type output_type);
> > +     int (*set_output_pattern)(struct pwm_chip *chip,
> > +                         struct pwm_device *pwm,
> > +                         struct pwm_output_pattern *output_pattern);
>
> This doesn't match the atomic approach that we're following since the
> introduction of .apply. Please don't add new non-atomic callbacks.
>
> >  };
> >
> >  /**
> > @@ -318,6 +373,20 @@ void pwm_free(struct pwm_device *pwm);
> >  int pwm_apply_state(struct pwm_device *pwm, const struct pwm_state *state);
> >  int pwm_adjust_config(struct pwm_device *pwm);
> >
> > +/*
> > + * pwm_output_type_support()
> > + * @pwm: PWM device
> > + *
> > + * Returns:  output types supported by the PWM device
> > + */
> > +static inline int pwm_get_output_type_supported(struct pwm_device *pwm)
> > +{
> > +     if (pwm->chip->ops->get_output_type_supported != NULL)
> > +             return pwm->chip->ops->get_output_type_supported(pwm->chip, pwm);
> > +     else
> > +             return PWM_OUTPUT_FIXED;
> > +}
>
> I don't like this "advertising" for specific functions. I'd prefer to
> handle this in .apply(), fix all drivers to return -ESOMETHING when the
> request cannot be fulfilled.

I will have to disagree on this one. As the functions are called in
multiple places it would just make mess in the driver.
As the driver is even now not exactly the definition of clean driver i
would not like to make it even more messy.

>
> Having said that I wonder if this output pattern is a common enough
> property to add support for it in the PWM framework.
>

I have gotten an email from Guru Das Srinagesh regarding this exact
issue you are pointing to. Yes the output pattern will be dropped in
V2.

Best Regards,
Martin

On Fri, Jul 24, 2020 at 11:36:51PM +0200, Martin Botka wrote:
> From: Fenglin Wu <fenglinw@codeaurora.org>
> 
> Normally, PWM channel has fixed output until software request to change
> its settings. There are some PWM devices which their outputs could be
> changed autonomously according to a predefined pattern programmed in
> hardware. Add pwm_output_type enum type to identify these two different
> PWM types and add relevant helper functions to set and get PWM output
> types and pattern.
> 
> Signed-off-by: Fenglin Wu <fenglinw@codeaurora.org>
> [konradybcio@gmail.com: Fast-forward from kernel 4.14 to 5.8]
> Signed-off-by: Konrad Dybcio <konradybcio@gmail.com>
> Signed-off-by: Martin Botka <martin.botka1@gmail.com>

Hello,

Re-sending my reply as somehow the cc-fields got dropped when I posted
earlier.

This was the feedback received from the maintainers when I posted this
patch last year [1]. Accordingly, we updated the patch to drop
"output_pattern" altogether and made "output_type" read-only [2] -
haven't attempted upstreaming this version yet.

[1]: https://lore.kernel.org/lkml/20190916140146.GC7488@ulmo/
[2]: https://android-review.googlesource.com/c/kernel/common/+/1170135

Thank you.

Guru Das.

Hello Martin,

On Mon, Jul 27, 2020 at 10:56:31PM +0200, Martin Botka wrote:
> Mo 27. 7. 2020 at 22:10 Uwe Kleine-König <u.kleine-koenig@pengutronix.de> wrote:
> > On Fri, Jul 24, 2020 at 11:36:51PM +0200, Martin Botka wrote:
> > > +/*
> > > + * pwm_output_type_support()
> > > + * @pwm: PWM device
> > > + *
> > > + * Returns:  output types supported by the PWM device
> > > + */
> > > +static inline int pwm_get_output_type_supported(struct pwm_device *pwm)
> > > +{
> > > +     if (pwm->chip->ops->get_output_type_supported != NULL)
> > > +             return pwm->chip->ops->get_output_type_supported(pwm->chip, pwm);
> > > +     else
> > > +             return PWM_OUTPUT_FIXED;
> > > +}
> >
> > I don't like this "advertising" for specific functions. I'd prefer to
> > handle this in .apply(), fix all drivers to return -ESOMETHING when the
> > request cannot be fulfilled.
> 
> I will have to disagree on this one. As the functions are called in
> multiple places it would just make mess in the driver.

Note this is something where (I think) I don't agree with Thierry
either. This popped up just yesterday, see

	https://www.spinics.net/lists/linux-pwm/msg13290.html

For sure I want at most one such function per driver, so if we really
want to go this path and introduce a capability indicator, this should
be named differently and have a different prototype.

> As the driver is even now not exactly the definition of clean driver i
> would not like to make it even more messy.

> > Having said that I wonder if this output pattern is a common enough
> > property to add support for it in the PWM framework.
> >
> 
> I have gotten an email from Guru Das Srinagesh regarding this exact
> issue you are pointing to. Yes the output pattern will be dropped in
> V2.

That's good.

Best regards
Uwe