[v2,1/3] dt-bindings: adc-joystick: add adc-joystick,polled option

From: Chris Morgan <macromorgan@hotmail.com>

Add documentation for adc-joystick,polled. New device-tree properties
have been added.

- adc-joystick,polled: A boolean value noting the joystick device
		       should be polled rather than use a triggered
		       buffer.

Signed-off-by: Maya Matuszczyk <maccraft123mc@gmail.com>
Signed-off-by: Chris Morgan <macromorgan@hotmail.com>
---
 .../devicetree/bindings/input/adc-joystick.yaml          | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

On 01/06/2022 22:49, Chris Morgan wrote:
> From: Chris Morgan <macromorgan@hotmail.com>
> 
> Add documentation for adc-joystick,polled. New device-tree properties
> have been added.
> 
> - adc-joystick,polled: A boolean value noting the joystick device
> 		       should be polled rather than use a triggered
> 		       buffer.
> 
> Signed-off-by: Maya Matuszczyk <maccraft123mc@gmail.com>
> Signed-off-by: Chris Morgan <macromorgan@hotmail.com>
> ---
>  .../devicetree/bindings/input/adc-joystick.yaml          | 9 ++++++++-
>  1 file changed, 8 insertions(+), 1 deletion(-)
> 
> diff --git a/Documentation/devicetree/bindings/input/adc-joystick.yaml b/Documentation/devicetree/bindings/input/adc-joystick.yaml
> index 2ee04e03bc22..4f49a1a5772e 100644
> --- a/Documentation/devicetree/bindings/input/adc-joystick.yaml
> +++ b/Documentation/devicetree/bindings/input/adc-joystick.yaml
> @@ -12,12 +12,19 @@ maintainers:
>  
>  description: >
>    Bindings for joystick devices connected to ADC controllers supporting
> -  the Industrial I/O subsystem.
> +  the Industrial I/O subsystem. Supports both polled devices where no
> +  iio trigger is available and non-polled devices which are triggered
> +  by iio.
>  
>  properties:
>    compatible:
>      const: adc-joystick
>  
> +  adc-joystick,polled:
> +    type: boolean
> +    description:
> +      If the device does not support triggered buffers and needs to be polled.

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


Best regards,
Krzysztof

On Thu, Jun 02, 2022 at 11:56:10AM +0200, Krzysztof Kozlowski wrote:
> On 01/06/2022 22:49, Chris Morgan wrote:
> > From: Chris Morgan <macromorgan@hotmail.com>
> > 
> > Add documentation for adc-joystick,polled. New device-tree properties
> > have been added.
> > 
> > - adc-joystick,polled: A boolean value noting the joystick device
> > 		       should be polled rather than use a triggered
> > 		       buffer.
> > 
> > Signed-off-by: Maya Matuszczyk <maccraft123mc@gmail.com>
> > Signed-off-by: Chris Morgan <macromorgan@hotmail.com>
> > ---
> >  .../devicetree/bindings/input/adc-joystick.yaml          | 9 ++++++++-
> >  1 file changed, 8 insertions(+), 1 deletion(-)
> > 
> > diff --git a/Documentation/devicetree/bindings/input/adc-joystick.yaml b/Documentation/devicetree/bindings/input/adc-joystick.yaml
> > index 2ee04e03bc22..4f49a1a5772e 100644
> > --- a/Documentation/devicetree/bindings/input/adc-joystick.yaml
> > +++ b/Documentation/devicetree/bindings/input/adc-joystick.yaml
> > @@ -12,12 +12,19 @@ maintainers:
> >  
> >  description: >
> >    Bindings for joystick devices connected to ADC controllers supporting
> > -  the Industrial I/O subsystem.
> > +  the Industrial I/O subsystem. Supports both polled devices where no
> > +  iio trigger is available and non-polled devices which are triggered
> > +  by iio.
> >  
> >  properties:
> >    compatible:
> >      const: adc-joystick
> >  
> > +  adc-joystick,polled:
> > +    type: boolean
> > +    description:
> > +      If the device does not support triggered buffers and needs to be polled.
> 

What would your recommendation be? I'm basically proposing polling
instead of utilizing a triggered buffer, so instead of the driver
relying on a hardware trigger or a software trigger being set up to
fill the buffer that is read by the input subsystem we use the input
subsystem polling function directly (this is useful for my use-case
where the Rockchip SARADC doesn't have a hardware trigger).

Thank you for your help.

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