[PATCH] pwm: reword docs about pwm_apply_state()

[PATCH] pwm: reword docs about pwm_apply_state()

[Uwe Kleine-König]

The main issue is that the current documentation talks about the
non-existent function pwm_get_last_applied_state. (This was right in the
context of
https://lore.kernel.org/linux-pwm/20210406073036.26857-1-u.kleine-koenig@pengutronix.de/
but was then missed to adapt when this patch was reduced to a
documentation update.)

While at is also clarify "last applied PWM state" to "PWM state that was
passed to the last invocation of pwm_apply_state()" to better
distinguish to the last actually implemented state and reword to drop a
word repetition.

Fixes: 539ed98e2bd3 ("pwm: Clarify documentation about pwm_get_state()")
Signed-off-by: Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
---
 Documentation/driver-api/pwm.rst | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/Documentation/driver-api/pwm.rst b/Documentation/driver-api/pwm.rst
index 381f3c46cdac..a7ca4f58305a 100644
--- a/Documentation/driver-api/pwm.rst
+++ b/Documentation/driver-api/pwm.rst
@@ -55,11 +55,11 @@ several parameter at once. For example, if you see pwm_config() and
pwm_{enable,disable}() calls in the same function, this probably means you
should switch to pwm_apply_state().

The PWM user API also allows one to query the[-last applied-] PWM state [-with-]
[-pwm_get_last_applied_state().-]{+that was passed to the+}
{+last invocation of pwm_apply_state() using pwm_get_state().+} Note this is
different to what the driver has actually implemented if the request cannot be
[-implemented-]{+satisfied+} exactly with the hardware in use. There is currently no way for
consumers to get the actually implemented settings.

In addition to the PWM state, the PWM API also exposes PWM arguments, which
are the reference PWM config one should use on this PWM.

base-commit: 64d7d074acd52e1bdff621f2cb86c0aae9bcef80
-- 
2.30.2

Re: [PATCH] pwm: reword docs about pwm_apply_state()

[Randy Dunlap]

On 4/23/21 12:44 AM, Uwe Kleine-König wrote:
> The main issue is that the current documentation talks about the
> non-existent function pwm_get_last_applied_state. (This was right in the
> context of
> https://lore.kernel.org/linux-pwm/20210406073036.26857-1-u.kleine-koenig@pengutronix.de/
> but was then missed to adapt when this patch was reduced to a
> documentation update.)
> 
> While at is also clarify "last applied PWM state" to "PWM state that was
> passed to the last invocation of pwm_apply_state()" to better
> distinguish to the last actually implemented state and reword to drop a
> word repetition.
> 
> Fixes: 539ed98e2bd3 ("pwm: Clarify documentation about pwm_get_state()")
> Signed-off-by: Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
> ---
>  Documentation/driver-api/pwm.rst | 10 +++++-----
>  1 file changed, 5 insertions(+), 5 deletions(-)
> 
> diff --git a/Documentation/driver-api/pwm.rst b/Documentation/driver-api/pwm.rst
> index 381f3c46cdac..a7ca4f58305a 100644
> --- a/Documentation/driver-api/pwm.rst
> +++ b/Documentation/driver-api/pwm.rst
> @@ -55,11 +55,11 @@ several parameter at once. For example, if you see pwm_config() and
> pwm_{enable,disable}() calls in the same function, this probably means you
> should switch to pwm_apply_state().
> 
> The PWM user API also allows one to query the[-last applied-] PWM state [-with-]
> [-pwm_get_last_applied_state().-]{+that was passed to the+}
> {+last invocation of pwm_apply_state() using pwm_get_state().+} Note this is
> different to what the driver has actually implemented if the request cannot be
> [-implemented-]{+satisfied+} exactly with the hardware in use. There is currently no way for
> consumers to get the actually implemented settings.
> 
> In addition to the PWM state, the PWM API also exposes PWM arguments, which
> are the reference PWM config one should use on this PWM.
> 
> base-commit: 64d7d074acd52e1bdff621f2cb86c0aae9bcef80
> 

Looks like the patch got horribly word wrapped. ?

thanks.
-- 
~Randy

Re: [PATCH] pwm: reword docs about pwm_apply_state()

[Uwe Kleine-König]

[-- Attachment #1: Type: text/plain, Size: 4008 bytes --]

On Fri, Apr 23, 2021 at 08:08:48AM -0700, Randy Dunlap wrote:
> On 4/23/21 12:44 AM, Uwe Kleine-König wrote:
> > The main issue is that the current documentation talks about the
> > non-existent function pwm_get_last_applied_state. (This was right in the
> > context of
> > https://lore.kernel.org/linux-pwm/20210406073036.26857-1-u.kleine-koenig@pengutronix.de/
> > but was then missed to adapt when this patch was reduced to a
> > documentation update.)
> > 
> > While at is also clarify "last applied PWM state" to "PWM state that was
> > passed to the last invocation of pwm_apply_state()" to better
> > distinguish to the last actually implemented state and reword to drop a
> > word repetition.
> > 
> > Fixes: 539ed98e2bd3 ("pwm: Clarify documentation about pwm_get_state()")
> > Signed-off-by: Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
> > ---
> >  Documentation/driver-api/pwm.rst | 10 +++++-----
> >  1 file changed, 5 insertions(+), 5 deletions(-)
> > 
> > diff --git a/Documentation/driver-api/pwm.rst b/Documentation/driver-api/pwm.rst
> > index 381f3c46cdac..a7ca4f58305a 100644
> > --- a/Documentation/driver-api/pwm.rst
> > +++ b/Documentation/driver-api/pwm.rst
> > @@ -55,11 +55,11 @@ several parameter at once. For example, if you see pwm_config() and
> > pwm_{enable,disable}() calls in the same function, this probably means you
> > should switch to pwm_apply_state().
> > 
> > The PWM user API also allows one to query the[-last applied-] PWM state [-with-]
> > [-pwm_get_last_applied_state().-]{+that was passed to the+}
> > {+last invocation of pwm_apply_state() using pwm_get_state().+} Note this is
> > different to what the driver has actually implemented if the request cannot be
> > [-implemented-]{+satisfied+} exactly with the hardware in use. There is currently no way for
> > consumers to get the actually implemented settings.
> > 
> > In addition to the PWM state, the PWM API also exposes PWM arguments, which
> > are the reference PWM config one should use on this PWM.
> > 
> > base-commit: 64d7d074acd52e1bdff621f2cb86c0aae9bcef80
> > 
> 
> Looks like the patch got horribly word wrapped. ?

No, this was created using git format-patch --word-diff, which for
continuous text is much better parsable (for a human at least).

The same chang in the more usual form looks as follows:

diff --git a/Documentation/driver-api/pwm.rst b/Documentation/driver-api/pwm.rst
index 381f3c46cdac..a7ca4f58305a 100644
--- a/Documentation/driver-api/pwm.rst
+++ b/Documentation/driver-api/pwm.rst
@@ -55,11 +55,11 @@ several parameter at once. For example, if you see pwm_config() and
 pwm_{enable,disable}() calls in the same function, this probably means you
 should switch to pwm_apply_state().
 
-The PWM user API also allows one to query the last applied PWM state with
-pwm_get_last_applied_state(). Note this is different to what the driver has
-actually implemented if the request cannot be implemented exactly with the
-hardware in use. There is currently no way for consumers to get the actually
-implemented settings.
+The PWM user API also allows one to query the PWM state that was passed to the
+last invocation of pwm_apply_state() using pwm_get_state(). Note this is
+different to what the driver has actually implemented if the request cannot be
+satisfied exactly with the hardware in use. There is currently no way for
+consumers to get the actually implemented settings.
 
 In addition to the PWM state, the PWM API also exposes PWM arguments, which
 are the reference PWM config one should use on this PWM.

With that it's hardly possible to identify what I actually changed.

I just noticed that the patch is not only incompatible for you but also
git-am cannot apply it, so I will have to resend. :-\

Best regards
Uwe

-- 
Pengutronix e.K.                           | Uwe Kleine-König            |
Industrial Linux Solutions                 | https://www.pengutronix.de/ |

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

Re: [PATCH] pwm: reword docs about pwm_apply_state()

[Randy Dunlap]

On 4/23/21 9:29 AM, Uwe Kleine-König wrote:
> On Fri, Apr 23, 2021 at 08:08:48AM -0700, Randy Dunlap wrote:
>> On 4/23/21 12:44 AM, Uwe Kleine-König wrote:
>>> The main issue is that the current documentation talks about the
>>> non-existent function pwm_get_last_applied_state. (This was right in the
>>> context of
>>> https://lore.kernel.org/linux-pwm/20210406073036.26857-1-u.kleine-koenig@pengutronix.de/
>>> but was then missed to adapt when this patch was reduced to a
>>> documentation update.)
>>>
>>> While at is also clarify "last applied PWM state" to "PWM state that was
>>> passed to the last invocation of pwm_apply_state()" to better
>>> distinguish to the last actually implemented state and reword to drop a
>>> word repetition.
>>>
>>> Fixes: 539ed98e2bd3 ("pwm: Clarify documentation about pwm_get_state()")
>>> Signed-off-by: Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
>>> ---
>>>  Documentation/driver-api/pwm.rst | 10 +++++-----
>>>  1 file changed, 5 insertions(+), 5 deletions(-)
>>>
>>> diff --git a/Documentation/driver-api/pwm.rst b/Documentation/driver-api/pwm.rst
>>> index 381f3c46cdac..a7ca4f58305a 100644
>>> --- a/Documentation/driver-api/pwm.rst
>>> +++ b/Documentation/driver-api/pwm.rst
>>> @@ -55,11 +55,11 @@ several parameter at once. For example, if you see pwm_config() and
>>> pwm_{enable,disable}() calls in the same function, this probably means you
>>> should switch to pwm_apply_state().
>>>
>>> The PWM user API also allows one to query the[-last applied-] PWM state [-with-]
>>> [-pwm_get_last_applied_state().-]{+that was passed to the+}
>>> {+last invocation of pwm_apply_state() using pwm_get_state().+} Note this is
>>> different to what the driver has actually implemented if the request cannot be
>>> [-implemented-]{+satisfied+} exactly with the hardware in use. There is currently no way for
>>> consumers to get the actually implemented settings.
>>>
>>> In addition to the PWM state, the PWM API also exposes PWM arguments, which
>>> are the reference PWM config one should use on this PWM.
>>>
>>> base-commit: 64d7d074acd52e1bdff621f2cb86c0aae9bcef80
>>>
>>
>> Looks like the patch got horribly word wrapped. ?
> 
> No, this was created using git format-patch --word-diff, which for
> continuous text is much better parsable (for a human at least).

My bad, I'm not familiar with that option.
But yes, now that I see what it does, it is easier to review the changes.

> The same chang in the more usual form looks as follows:
> 
> diff --git a/Documentation/driver-api/pwm.rst b/Documentation/driver-api/pwm.rst
> index 381f3c46cdac..a7ca4f58305a 100644
> --- a/Documentation/driver-api/pwm.rst
> +++ b/Documentation/driver-api/pwm.rst
> @@ -55,11 +55,11 @@ several parameter at once. For example, if you see pwm_config() and
>  pwm_{enable,disable}() calls in the same function, this probably means you
>  should switch to pwm_apply_state().
>  
> -The PWM user API also allows one to query the last applied PWM state with
> -pwm_get_last_applied_state(). Note this is different to what the driver has
> -actually implemented if the request cannot be implemented exactly with the
> -hardware in use. There is currently no way for consumers to get the actually
> -implemented settings.
> +The PWM user API also allows one to query the PWM state that was passed to the
> +last invocation of pwm_apply_state() using pwm_get_state(). Note this is
> +different to what the driver has actually implemented if the request cannot be
> +satisfied exactly with the hardware in use. There is currently no way for
> +consumers to get the actually implemented settings.
>  
>  In addition to the PWM state, the PWM API also exposes PWM arguments, which
>  are the reference PWM config one should use on this PWM.
> 
> With that it's hardly possible to identify what I actually changed.
> 
> I just noticed that the patch is not only incompatible for you but also
> git-am cannot apply it, so I will have to resend. :-\

oops.

thanks.
-- 
~Randy

[PATCH v2] pwm: reword docs about pwm_apply_state()

[Uwe Kleine-König]

The main issue is that the current documentation talks about the
non-existent function pwm_get_last_applied_state. (This was right in the
context of
https://lore.kernel.org/linux-pwm/20210406073036.26857-1-u.kleine-koenig@pengutronix.de/
but was then missed to adapt when this patch was reduced to a
documentation update.)

While at is also clarify "last applied PWM state" to "PWM state that was
passed to the last invocation of pwm_apply_state()" to better
distinguish to the last actually implemented state and reword to drop a
word repetition.

Fixes: 539ed98e2bd3 ("pwm: Clarify documentation about pwm_get_state()")
Signed-off-by: Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
---
Hello,

the only change compared to v1 is that I didn't use --word-diff to
create the patch. I just found out that git am cannot apply patches
created with --word-diff.

Best regards
Uwe

 Documentation/driver-api/pwm.rst | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/Documentation/driver-api/pwm.rst b/Documentation/driver-api/pwm.rst
index 381f3c46cdac..a7ca4f58305a 100644
--- a/Documentation/driver-api/pwm.rst
+++ b/Documentation/driver-api/pwm.rst
@@ -55,11 +55,11 @@ several parameter at once. For example, if you see pwm_config() and
 pwm_{enable,disable}() calls in the same function, this probably means you
 should switch to pwm_apply_state().
 
-The PWM user API also allows one to query the last applied PWM state with
-pwm_get_last_applied_state(). Note this is different to what the driver has
-actually implemented if the request cannot be implemented exactly with the
-hardware in use. There is currently no way for consumers to get the actually
-implemented settings.
+The PWM user API also allows one to query the PWM state that was passed to the
+last invocation of pwm_apply_state() using pwm_get_state(). Note this is
+different to what the driver has actually implemented if the request cannot be
+satisfied exactly with the hardware in use. There is currently no way for
+consumers to get the actually implemented settings.
 
 In addition to the PWM state, the PWM API also exposes PWM arguments, which
 are the reference PWM config one should use on this PWM.

base-commit: 64d7d074acd52e1bdff621f2cb86c0aae9bcef80
-- 
2.30.2

Re: [PATCH v2] pwm: reword docs about pwm_apply_state()

[Thierry Reding]

[-- Attachment #1: Type: text/plain, Size: 1156 bytes --]

On Fri, Apr 23, 2021 at 06:32:26PM +0200, Uwe Kleine-König wrote:
> The main issue is that the current documentation talks about the
> non-existent function pwm_get_last_applied_state. (This was right in the
> context of
> https://lore.kernel.org/linux-pwm/20210406073036.26857-1-u.kleine-koenig@pengutronix.de/
> but was then missed to adapt when this patch was reduced to a
> documentation update.)
> 
> While at is also clarify "last applied PWM state" to "PWM state that was
> passed to the last invocation of pwm_apply_state()" to better
> distinguish to the last actually implemented state and reword to drop a
> word repetition.
> 
> Fixes: 539ed98e2bd3 ("pwm: Clarify documentation about pwm_get_state()")
> Signed-off-by: Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
> ---
> Hello,
> 
> the only change compared to v1 is that I didn't use --word-diff to
> create the patch. I just found out that git am cannot apply patches
> created with --word-diff.
> 
> Best regards
> Uwe
> 
>  Documentation/driver-api/pwm.rst | 10 +++++-----
>  1 file changed, 5 insertions(+), 5 deletions(-)

Applied, thanks.

Thierry

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]