Re: [RFC PATCH v2 2/6] dt-bindings: pwm: document the PWM no-flag

[Oleksandr Suvorov]

On Tue, Apr 7, 2020 at 2:19 PM Uwe Kleine-KÃnig
<u.kleine-koenig@xxxxxxxxxxxxxx> wrote:
>
> On Tue, Apr 07, 2020 at 01:51:42PM +0300, Oleksandr Suvorov wrote:
> > On Tue, Apr 7, 2020 at 9:17 AM Uwe Kleine-KÃnig
> > <u.kleine-koenig@xxxxxxxxxxxxxx> wrote:
> > >
> > > On Sun, Apr 05, 2020 at 10:22:42PM +0300, Oleksandr Suvorov wrote:
> > > > Add the description of PWM_NOFLAGS flag property.
> > > >
> > > > Signed-off-by: Oleksandr Suvorov <oleksandr.suvorov@xxxxxxxxxxx>
> > >
> > > As I already wrote in reply to the v1 series I'd prefer a name for 0
> > > that explicitly handles normal polarity.
> >
> > Uwe, AFAIU, there is no flag that forces normal polarity, the normal polarity
> > is the default state if there is no flag to invert the polarity is set.
>
> Yes, that's the status quo.
>
> > '0' value in the bit flags cell really means there are no flags set
> > for the PWM instance.
>
> For me the relevance of giving 0 a name is mostly for human consumption.
> Currently there is only a single flag encoded in the number in question.
> But as soon as we add another, say PWM_AUTOSTART we have the following
> possible settings:
>
>         PWM_NOFLAGS
>         PWM_POLARITY_INVERTED
>         PWM_AUTOSTART
>         PWM_POLARITY_INVERTED | PWM_AUTOSTART
>
> Then for the first two a reader doesn't see if autostart is not in use
> because the dt author doesn't know this feature (e.g. because autostart
> is too new) or if they don't want autostart at all.
>
> If however we had PWM_POLARITY_NORMAL and PWM_NO_AUTOSTART to complement
> PWM_POLARITY_INVERTED and PWM_AUTOSTART

So using this approach, in theory, we'll have several flags that all
just equals to 0 (0 << 0, 0 << 1, 0 << 2 ...).
What if just describe default states for each flag in the DT documentation?

> every flag's setting could be explicit and if there is a device tree that only has
>
>         PWM_POLARITY_NORMAL
>
> it would be obvious that nobody thought enough about autostarting to
> explicitly mention it.

If you insist on the flag complement model, I have another suggestion.
As the normal polarity is the default state, can we use PWM_NO_POLARITY_INVERTED
instead of PWM_POLARITY_NORMAL?
It gives us 2 benefits:
1. The name will not interfere with enum PWM_POLARITY_NORMAL in <linux/pmw.h>
2. Each flag complement will be made with the same scheme:
PWM_flagA -> PWM_NO_flagA...

> Best regards
> Uwe
>
> --
> Pengutronix e.K.                           | Uwe Kleine-KÃnig            |
> Industrial Linux Solutions                 | https://www.pengutronix.de/ |

--
Best regards
Oleksandr Suvorov

Toradex AG
Ebenaustrasse 10 | 6048 Horw | Switzerland | T: +41 41 500 48 00