Re: [PATCH] dt-bindings: iio: tsl2563: convert bindings to YAML

[Nishant Malpani]

A v3 PATCH [1] was generated taking care of the reviews which can be 
found inline.

[1] https://marc.info/?l=linux-iio&m=158451158827441&w=2

On 15/03/20 4:28 pm, Jonathan Cameron wrote:
> On Sat, 14 Mar 2020 19:12:37 +0530
> Nishant Malpani <nish.malpani25@xxxxxxxxx> wrote:
>
> > Convert the TSL2563 device tree bindings to the new YAML format.
> >
> > Signed-off-by: Nishant Malpani <nish.malpani25@xxxxxxxxx>
> > ---
> >
> > The link for the datasheet is not attached in the binding document
> > because it was not available on the manufacturer's (AMS) website [1].
>
> Very old part now, though plenty of them in circulation or least there
> used to be.  I have though not powered up that board for a while.
>
> When doing these conversions, do sanity check them against the driver
> as the old docs aren't always entirely accurate ; >
> Jonathan
>
> > [1] https://ams.com/ambient-light-sensors
> > ---
> >   .../devicetree/bindings/iio/light/tsl2563.txt | 19 --------
> >   .../bindings/iio/light/tsl2563.yaml           | 46 +++++++++++++++++++
> >   2 files changed, 46 insertions(+), 19 deletions(-)
> >   delete mode 100644 Documentation/devicetree/bindings/iio/light/tsl2563.txt
> >   create mode 100644 Documentation/devicetree/bindings/iio/light/tsl2563.yaml
> >
> > diff --git a/Documentation/devicetree/bindings/iio/light/tsl2563.txt b/Documentation/devicetree/bindings/iio/light/tsl2563.txt
> > deleted file mode 100644
> > index f91e809e736e..000000000000
> > --- a/Documentation/devicetree/bindings/iio/light/tsl2563.txt
> > +++ /dev/null
> > @@ -1,19 +0,0 @@
> > -* AMS TAOS TSL2563 ambient light sensor
> > -
> > -Required properties:
> > -
> > -  - compatible : should be "amstaos,tsl2563"
> > -  - reg : the I2C address of the sensor
> > -
> > -Optional properties:
> > -
> > -  - amstaos,cover-comp-gain : integer used as multiplier for gain
> > -                              compensation (default = 1)
> > -
> > -Example:
> > -
> > -tsl2563@29 {
> > -	compatible = "amstaos,tsl2563";
> > -	reg = <0x29>;
> > -	amstaos,cover-comp-gain = <16>;
> > -};
> > diff --git a/Documentation/devicetree/bindings/iio/light/tsl2563.yaml b/Documentation/devicetree/bindings/iio/light/tsl2563.yaml
> > new file mode 100644
> > index 000000000000..2a70b8d62760
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/iio/light/tsl2563.yaml
> > @@ -0,0 +1,46 @@
> > +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/iio/light/tsl2563.yaml#
>
> Convention is now to name files and this with the manufacturer part
> as well.

Got it! Taken care of in v3.
> light/amstaos,tsl2563.yaml
>
> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > +
> > +title: AMS TAOS TSL2563 ambient light sensor
> > +
> > +maintainers:
> > +  - Sebastian Reichel <sre@xxxxxxxxxx>
> > +
> > +description: |
> > +  Ambient light sensor with an i2c interface.
> > +
> > +properties:
> > +  compatible:
> > +    enum:
> > +      - amstaos,tsl2563
>
> The original binding was wrong on this.   Check the driver :)
> I'm a bit embarrassed I never noticed during review as I have
> a tsl2561, be it on a board that was never converted to DT.

You're right. Should have cross-checked with the driver before blindly 
following the original binding. Corrected in v3.
> > +
> > +  reg:
> > +    maxItems: 1
> > +
> > +  amstaos,cover-comp-gain:
> > +    description: Multiplier for gain compensation
> > +    allOf:
> > +      - $ref: /schemas/types.yaml#/definitions/uint32
> > +      - enum: [1, 16]
>
> Not sure it's that restricted...  or to be honest what
> that is for at all.  Superficially it looks like
> a multiplier to change the 'range' of the the sysfs control.
>
> I wonder if anyone cares or if we can just start ignoring that going
> forwards?  Sebastian, anyone else?

From what I understood while reading the datasheet [2] (Page 4), 
'amstaos,cover-comp-gain' is used to switch between the low gain and 
high gain mode which further adjusts the 'Illuminance Responsivity'. 
Ergo, I've taken it forward even in v3 since the driver also relies on 
it [3]. Please let me know if my reasoning is erroneous.

[2] 
https://media.digikey.com/pdf/Data%20Sheets/Austriamicrosystems%20PDFs/TSL2562,63.pdf

[3] 
https://git.kernel.org/pub/scm/linux/kernel/git/jic23/iio.git/tree/drivers/iio/light/tsl2563.c#n494
> > +
> > +required:
> > +  - compatible
> > +  - reg
> > +
> > +examples:
> > +  - |
> > +    i2c {
> > +
> > +      #address-cells = <1>;
> > +      #size-cells = <0>;
> > +
> > +      light-sensor@29 {
> > +        compatible = "amstaos,tsl2563";
> > +        reg = <0x29>;
> > +        amstaos,cover-comp-gain = <16>;
> > +      };
> > +    };
> > +...

With regards,
Nishant Malpani