[v1,1/2] dt-bindings: input: atmel,maxtouch: add poweroff-in-suspend property

  From: Stefan Eichenberger <stefan.eichenberger@toradex.com>

Add a new property to indicate that the device should be powered off in
suspend mode.

Signed-off-by: Stefan Eichenberger <stefan.eichenberger@toradex.com>
---
 Documentation/devicetree/bindings/input/atmel,maxtouch.yaml | 6 ++++++
 1 file changed, 6 insertions(+)
  

On 07/12/2023 12:12, Stefan Eichenberger wrote:
> diff --git a/Documentation/devicetree/bindings/input/atmel,maxtouch.yaml b/Documentation/devicetree/bindings/input/atmel,maxtouch.yaml
> index c40799355ed7..047a5101341c 100644
> --- a/Documentation/devicetree/bindings/input/atmel,maxtouch.yaml
> +++ b/Documentation/devicetree/bindings/input/atmel,maxtouch.yaml
> @@ -87,6 +87,12 @@ properties:
>        - 2 # ATMEL_MXT_WAKEUP_GPIO
>      default: 0
>  
> +  atmel,poweroff-in-suspend:
> +    description: |
> +      When this property is set, all supplies are turned off when the system is
> +      going to suspend.

You described the desired Linux feature or behavior, not the actual
hardware. The bindings are about the latter, so instead you need to
rephrase the property and its description to match actual hardware
capabilities/features/configuration etc.

Best regards,
Krzysztof
  

Hi Krzysztof,

On Thu, Dec 07, 2023 at 05:59:08PM +0100, Krzysztof Kozlowski wrote:
> On 07/12/2023 12:12, Stefan Eichenberger wrote:
> > diff --git a/Documentation/devicetree/bindings/input/atmel,maxtouch.yaml b/Documentation/devicetree/bindings/input/atmel,maxtouch.yaml
> > index c40799355ed7..047a5101341c 100644
> > --- a/Documentation/devicetree/bindings/input/atmel,maxtouch.yaml
> > +++ b/Documentation/devicetree/bindings/input/atmel,maxtouch.yaml
> > @@ -87,6 +87,12 @@ properties:
> >        - 2 # ATMEL_MXT_WAKEUP_GPIO
> >      default: 0
> >  
> > +  atmel,poweroff-in-suspend:
> > +    description: |
> > +      When this property is set, all supplies are turned off when the system is
> > +      going to suspend.
> 
> You described the desired Linux feature or behavior, not the actual
> hardware. The bindings are about the latter, so instead you need to
> rephrase the property and its description to match actual hardware
> capabilities/features/configuration etc.

Thanks a lot for the feedback. Would the following be okay as a
description?

vdda and vdd are switched off in suspend mode.

Best regards,
Stefan
  

On 08/12/2023 13:37, Stefan Eichenberger wrote:
> Hi Krzysztof,
> 
> On Thu, Dec 07, 2023 at 05:59:08PM +0100, Krzysztof Kozlowski wrote:
>> On 07/12/2023 12:12, Stefan Eichenberger wrote:
>>> diff --git a/Documentation/devicetree/bindings/input/atmel,maxtouch.yaml b/Documentation/devicetree/bindings/input/atmel,maxtouch.yaml
>>> index c40799355ed7..047a5101341c 100644
>>> --- a/Documentation/devicetree/bindings/input/atmel,maxtouch.yaml
>>> +++ b/Documentation/devicetree/bindings/input/atmel,maxtouch.yaml
>>> @@ -87,6 +87,12 @@ properties:
>>>        - 2 # ATMEL_MXT_WAKEUP_GPIO
>>>      default: 0
>>>  
>>> +  atmel,poweroff-in-suspend:
>>> +    description: |
>>> +      When this property is set, all supplies are turned off when the system is
>>> +      going to suspend.
>>
>> You described the desired Linux feature or behavior, not the actual
>> hardware. The bindings are about the latter, so instead you need to
>> rephrase the property and its description to match actual hardware
>> capabilities/features/configuration etc.
> 
> Thanks a lot for the feedback. Would the following be okay as a
> description?
> 
> vdda and vdd are switched off in suspend mode.

Are switched by who? Linux driver? Then nothing changed...

Best regards,
Krzysztof
  

On Thu, Dec 7, 2023 at 12:13 PM Stefan Eichenberger <eichest@gmail.com> wrote:

> From: Stefan Eichenberger <stefan.eichenberger@toradex.com>
>
> Add a new property to indicate that the device should be powered off in
> suspend mode.
>
> Signed-off-by: Stefan Eichenberger <stefan.eichenberger@toradex.com>
(...)
> +  atmel,poweroff-in-suspend:
> +    description: |
> +      When this property is set, all supplies are turned off when the system is
> +      going to suspend.
> +    type: boolean
   wakeup-source:
     type: boolean

As Krzysztof says it seems you are describing an operating system feature.

I can't help but wonder: shouldn't that pretty much be the default behaviour
if wakeup-source is *not* specified?

I.e. the property kind of describes !wakeup-source.

Yours,
Linus Walleij
  

Hi Krzysztof and Linux,

On Fri, Dec 08, 2023 at 01:54:21PM +0100, Linus Walleij wrote:
> On Thu, Dec 7, 2023 at 12:13 PM Stefan Eichenberger <eichest@gmail.com> wrote:
> 
> > From: Stefan Eichenberger <stefan.eichenberger@toradex.com>
> >
> > Add a new property to indicate that the device should be powered off in
> > suspend mode.
> >
> > Signed-off-by: Stefan Eichenberger <stefan.eichenberger@toradex.com>
> (...)
> > +  atmel,poweroff-in-suspend:
> > +    description: |
> > +      When this property is set, all supplies are turned off when the system is
> > +      going to suspend.
> > +    type: boolean
>    wakeup-source:
>      type: boolean
> 
> As Krzysztof says it seems you are describing an operating system feature.
> 
> I can't help but wonder: shouldn't that pretty much be the default behaviour
> if wakeup-source is *not* specified?
> 
> I.e. the property kind of describes !wakeup-source.

The maxtouch controller has a deep sleep mode which is currently used
without powering down vdd and vdda. However, because we have a shared
regulator which powers other peripherals that we want to shut down in
suspend we need a way to power down vdd and vdda. However, I agree this
is not really a feature of the device. The feature would basically be
the internal deep sleep mode. I didn't want to change the default
behaviour of the driver, so I added this property but maybe I could
change it to:

atmel,deep-sleep:
  description: |
     Use the maxtouch deep-sleep mode instead of powering down vdd and
     vdda.

Or to not change the default behaviour:
atmel,no-deep-sleep:
  description: |
     Do not use the maxtouch deep-sleep mode but power down vdd and vdda
     in suspend.

As I understand the datasheet even if the maxtouch is using its deep
sleep mode it does not act as a wakeup source. It is just faster in
waking up because it can keep the configuration in memory.

Regards,
Stefan
  

On Fri, Dec 8, 2023 at 2:11 PM Stefan Eichenberger <eichest@gmail.com> wrote:

> > I can't help but wonder: shouldn't that pretty much be the default behaviour
> > if wakeup-source is *not* specified?
> >
> > I.e. the property kind of describes !wakeup-source.
>
> The maxtouch controller has a deep sleep mode which is currently used
> without powering down vdd and vdda. However, because we have a shared
> regulator which powers other peripherals that we want to shut down in
> suspend we need a way to power down vdd and vdda. However, I agree this
> is not really a feature of the device. The feature would basically be
> the internal deep sleep mode.

While it is of no concern to the device tree bindings, Linux regulators
are counting meaning that you need to make all peripherals disable
their regulators and it will come down.

> I didn't want to change the default
> behaviour of the driver, so I added this property but maybe I could
> change it to:
>
> atmel,deep-sleep:
>   description: |
>      Use the maxtouch deep-sleep mode instead of powering down vdd and
>      vdda.
>
> Or to not change the default behaviour:
> atmel,no-deep-sleep:
>   description: |
>      Do not use the maxtouch deep-sleep mode but power down vdd and vdda
>      in suspend.
>
> As I understand the datasheet even if the maxtouch is using its deep
> sleep mode it does not act as a wakeup source.

Do you mean it can still work as a wakeup source in deep sleep mode?
(there is a "not" too much above ...)

> It is just faster in
> waking up because it can keep the configuration in memory.

That sounds like a good reason to have the property, because that
means that if you can control the wakeup latency and specify in the binding
how much in absolute time units it is affected.

I would define it in positive terms instead of reverse "no-deep-sleep"
though such as "atmel,fast-wakeup".

And: If you disable the regulators it will probably *not* be able to wake the
system up, right? And that is just a few lines of code in the driver such as:

go_to_sleep():
  if (!wakeup_source):
     disable_regulators()

Yours,
Linus Walleij
  

Hi Linus,

On Fri, Dec 08, 2023 at 03:23:54PM +0100, Linus Walleij wrote:
> On Fri, Dec 8, 2023 at 2:11 PM Stefan Eichenberger <eichest@gmail.com> wrote:
> 
> > > I can't help but wonder: shouldn't that pretty much be the default behaviour
> > > if wakeup-source is *not* specified?
> > >
> > > I.e. the property kind of describes !wakeup-source.
> >
> > The maxtouch controller has a deep sleep mode which is currently used
> > without powering down vdd and vdda. However, because we have a shared
> > regulator which powers other peripherals that we want to shut down in
> > suspend we need a way to power down vdd and vdda. However, I agree this
> > is not really a feature of the device. The feature would basically be
> > the internal deep sleep mode.
> 
> While it is of no concern to the device tree bindings, Linux regulators
> are counting meaning that you need to make all peripherals disable
> their regulators and it will come down.

Yes we are working on that one. This is the last driver we need to allow
disabling the regulator, afterward it should hoepfully work on our
target system.

> 
> > I didn't want to change the default
> > behaviour of the driver, so I added this property but maybe I could
> > change it to:
> >
> > atmel,deep-sleep:
> >   description: |
> >      Use the maxtouch deep-sleep mode instead of powering down vdd and
> >      vdda.
> >
> > Or to not change the default behaviour:
> > atmel,no-deep-sleep:
> >   description: |
> >      Do not use the maxtouch deep-sleep mode but power down vdd and vdda
> >      in suspend.
> >
> > As I understand the datasheet even if the maxtouch is using its deep
> > sleep mode it does not act as a wakeup source.
> 
> Do you mean it can still work as a wakeup source in deep sleep mode?
> (there is a "not" too much above ...)

Sorry for the confusion. As it is configured now, it can not work as
wakeup source in deep sleep mode. Touch is completely disabled.

> > It is just faster in
> > waking up because it can keep the configuration in memory.
> 
> That sounds like a good reason to have the property, because that
> means that if you can control the wakeup latency and specify in the binding
> how much in absolute time units it is affected.
> 
> I would define it in positive terms instead of reverse "no-deep-sleep"
> though such as "atmel,fast-wakeup".
> 
> And: If you disable the regulators it will probably *not* be able to wake the
> system up, right? And that is just a few lines of code in the driver such as:
> 
> go_to_sleep():
>   if (!wakeup_source):
>      disable_regulators()

So to not change the default behaviour I would have to name it:
atmel,slow-wakeup
or maybe even full wakeup because it does a wakeup from the disabled
state?
atmel,full-wakeup

Exactly, the added code looks more or less exactly as you wrote. And on
resume it does the opposite + configure it:

resume():
  if (!wakeup_source):
     enable_regulators()
     configure_maxtouch()

Regards,
Stefan
  

Hi Linus, Krzysztof,

On Fri, Dec 08, 2023 at 01:54:21PM +0100, Linus Walleij wrote:
> On Thu, Dec 7, 2023 at 12:13 PM Stefan Eichenberger <eichest@gmail.com> wrote:
> 
> > From: Stefan Eichenberger <stefan.eichenberger@toradex.com>
> >
> > Add a new property to indicate that the device should be powered off in
> > suspend mode.
> >
> > Signed-off-by: Stefan Eichenberger <stefan.eichenberger@toradex.com>
> (...)
> > +  atmel,poweroff-in-suspend:
> > +    description: |
> > +      When this property is set, all supplies are turned off when the system is
> > +      going to suspend.
> > +    type: boolean
>    wakeup-source:
>      type: boolean
> 
> As Krzysztof says it seems you are describing an operating system feature.

It appears to be an OS feature, but I would argue that it is also a
property of a board. It is tempting to say that if DTS defines supplies
for the controller we should use them to power off the controller in
suspend, otherwise we should use the deep sleep functionality of the
controller. But a mere presence of regulators does not indicate if they
can actually be powered off in suspend (i.e. if controllers shares power
rails with another device that can be a wakeup source), so we need to
have additional hints on how OS should behave on a given device.

On top of that we have regulator framework supplying dummy regulators...

Thanks.
  

On Fri, Dec 08, 2023 at 11:37:47PM +0000, Dmitry Torokhov wrote:
> Hi Linus, Krzysztof,
> 
> On Fri, Dec 08, 2023 at 01:54:21PM +0100, Linus Walleij wrote:
> > On Thu, Dec 7, 2023 at 12:13 PM Stefan Eichenberger <eichest@gmail.com> wrote:
> > 
> > > From: Stefan Eichenberger <stefan.eichenberger@toradex.com>
> > >
> > > Add a new property to indicate that the device should be powered off in
> > > suspend mode.
> > >
> > > Signed-off-by: Stefan Eichenberger <stefan.eichenberger@toradex.com>
> > (...)
> > > +  atmel,poweroff-in-suspend:
> > > +    description: |
> > > +      When this property is set, all supplies are turned off when the system is
> > > +      going to suspend.
> > > +    type: boolean
> >    wakeup-source:
> >      type: boolean
> > 
> > As Krzysztof says it seems you are describing an operating system feature.
> 
> It appears to be an OS feature, but I would argue that it is also a
> property of a board. It is tempting to say that if DTS defines supplies
> for the controller we should use them to power off the controller in
> suspend, otherwise we should use the deep sleep functionality of the
> controller. But a mere presence of regulators does not indicate if they
> can actually be powered off in suspend (i.e. if controllers shares power
> rails with another device that can be a wakeup source), so we need to
> have additional hints on how OS should behave on a given device.
> 
> On top of that we have regulator framework supplying dummy regulators...

Simply rephrasing the property might be sufficient? The current one
sounds making policy decisions with the "should be". Reframing the
commit message and property description etc in terms of what aspect of
the hardware the ability to turn off all supplies in suspend comes from
would make it more acceptable. Pretty much answering the question "why
can't we try and turn off all supplies on all systems with this device"
should get things rolling.

Cheers,
Conor.