diff mbox series

[1/2] dt-bindings: iio: tsl2772: convert bindings to YAML format

Message ID 20190416084552.1538-1-masneyb@onstation.org (mailing list archive)
State New, archived
Headers show
Series [1/2] dt-bindings: iio: tsl2772: convert bindings to YAML format | expand

Commit Message

Brian Masney April 16, 2019, 8:45 a.m. UTC 
Convert the tsl2772 device tree bindings to the new YAML format.

Signed-off-by: Brian Masney <masneyb@onstation.org>
---
 .../devicetree/bindings/iio/light/tsl2772.txt | 42 ---------
 .../bindings/iio/light/tsl2772.yaml           | 85 +++++++++++++++++++
 2 files changed, 85 insertions(+), 42 deletions(-)
 delete mode 100644 Documentation/devicetree/bindings/iio/light/tsl2772.txt
 create mode 100644 Documentation/devicetree/bindings/iio/light/tsl2772.yaml

Comments

Jonathan Cameron April 22, 2019, 12:52 p.m. UTC | #1 
On Tue, 16 Apr 2019 04:45:51 -0400
Brian Masney <masneyb@onstation.org> wrote:

> Convert the tsl2772 device tree bindings to the new YAML format.
> 
> Signed-off-by: Brian Masney <masneyb@onstation.org>
Hi Brian,

Good to see this.  I'm afraid it's all a bit new to me so what
I haven't yet understood is how prescriptive we should be.
For example, are the phandle references below needed or not?

So for a while yet I'm going to be relying on Rob and others
to review these and put me on the right track.

Jonathan

> ---
>  .../devicetree/bindings/iio/light/tsl2772.txt | 42 ---------
>  .../bindings/iio/light/tsl2772.yaml           | 85 +++++++++++++++++++
>  2 files changed, 85 insertions(+), 42 deletions(-)
>  delete mode 100644 Documentation/devicetree/bindings/iio/light/tsl2772.txt
>  create mode 100644 Documentation/devicetree/bindings/iio/light/tsl2772.yaml
> 
> diff --git a/Documentation/devicetree/bindings/iio/light/tsl2772.txt b/Documentation/devicetree/bindings/iio/light/tsl2772.txt
> deleted file mode 100644
> index 1c5e6f17a1df..000000000000
> --- a/Documentation/devicetree/bindings/iio/light/tsl2772.txt
> +++ /dev/null
> @@ -1,42 +0,0 @@
> -* AMS/TAOS ALS and proximity sensor
> -
> -Required properties:
> -
> -  - compatible: Should be one of
> -		"amstaos,tsl2571"
> -		"amstaos,tsl2671"
> -		"amstaos,tmd2671"
> -		"amstaos,tsl2771"
> -		"amstaos,tmd2771"
> -		"amstaos,tsl2572"
> -		"amstaos,tsl2672"
> -		"amstaos,tmd2672"
> -		"amstaos,tsl2772"
> -		"amstaos,tmd2772"
> -		"avago,apds9930"
> -  - reg: the I2C address of the device
> -
> -Optional properties:
> -
> -  - amstaos,proximity-diodes - proximity diodes to enable. <0>, <1>, or <0 1>
> -                               are the only valid values.
> -  - led-max-microamp - current for the proximity LED. Must be 100000, 50000,
> -                       25000, or 13000.
> -  - vdd-supply: phandle to the regulator that provides power to the sensor.
> -  - vddio-supply: phandle to the regulator that provides power to the bus.
> -  - interrupts: the sole interrupt generated by the device
> -
> -  Refer to interrupt-controller/interrupts.txt for generic interrupt client
> -  node bindings.
> -
> -Example:
> -
> -tsl2772@39 {
> -	compatible = "amstaos,tsl2772";
> -	reg = <0x39>;
> -	interrupts-extended = <&msmgpio 61 IRQ_TYPE_EDGE_FALLING>;
> -	vdd-supply = <&pm8941_l17>;
> -	vddio-supply = <&pm8941_lvs1>;
> -	amstaos,proximity-diodes = <0>;
> -	led-max-microamp = <100000>;
> -};
> diff --git a/Documentation/devicetree/bindings/iio/light/tsl2772.yaml b/Documentation/devicetree/bindings/iio/light/tsl2772.yaml
> new file mode 100644
> index 000000000000..b3ac182288d2
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/iio/light/tsl2772.yaml
> @@ -0,0 +1,85 @@
> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/iio/light/tsl2772.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: AMS/TAOS Ambient Light Sensor (ALS) and Proximity Detector
> +
> +maintainers:
> +  - Brian Masney <masneyb@onstation.org>
> +
> +description: |
> +  Ambient light sensing and proximity detection with an i2c interface.
> +  https://ams.com/documents/20143/36005/TSL2772_DS000181_2-00.pdf
> +
> +properties:
> +  compatible:
> +    enum:
> +      - amstaos,tsl2571
> +      - amstaos,tsl2671
> +      - amstaos,tmd2671
> +      - amstaos,tsl2771
> +      - amstaos,tmd2771
> +      - amstaos,tsl2572
> +      - amstaos,tsl2672
> +      - amstaos,tmd2672
> +      - amstaos,tsl2772
> +      - amstaos,tmd2772
> +      - avago,apds9930
> +
> +  reg:
> +    description: The I2C address of the device
> +    maxItems: 1
> +
> +  amstaos,proximity-diodes:
> +    description: Proximity diodes to enable
> +    allOf:
> +      - $ref: /schemas/types.yaml#/definitions/uint32-array
> +      - minItems: 1
> +        maxItems: 2
> +        items:
> +          minimum: 0
> +          maximum: 1

Do we need to represent that these can't be <1 0> ?
(specified in old docs)
We also have a tighter spec than the uint32-array format in types.yaml
as don't allow <0>, <1> under the current binding where only <0, 1> is
allowed.

> +
> +  interrupts:
> +    description: Interrupt generated by the device
> +    maxItems: 1
> +
> +  led-max-microamp:
> +    description: Current for the proximity LED
> +    allOf:
> +      - $ref: /schemas/types.yaml#/definitions/uint32
> +      - enum: [13000, 25000, 50000, 100000]
> +
> +  vdd-supply:
> +    $ref: /schemas/types.yaml#/definitions/phandle
> +    description: Regulator that provides power to the sensor
> +
> +  vddio-supply:
> +    $ref: /schemas/types.yaml#/definitions/phandle
> +    description: Regulator that provides power to the bus
> +
> +required:
> +  - compatible
> +  - reg
> +
> +examples:
> +  - |
> +    #include <dt-bindings/interrupt-controller/irq.h>
> +
> +    i2c {
> +        #address-cells = <1>;
> +        #size-cells = <0>;
> +
> +        tsl2772@39 {
> +                compatible = "amstaos,tsl2772";
> +                reg = <0x39>;
> +                interrupts-extended = <&msmgpio 61 IRQ_TYPE_EDGE_FALLING>;
> +                vdd-supply = <&pm8941_l17>;
> +                vddio-supply = <&pm8941_lvs1>;
> +                amstaos,proximity-diodes = <0>;
> +                led-max-microamp = <100000>;
> +        };
> +    };
> +...
Rob Herring April 24, 2019, 1:34 a.m. UTC | #2 
On Mon, Apr 22, 2019 at 7:52 AM Jonathan Cameron <jic23@kernel.org> wrote:
>
> On Tue, 16 Apr 2019 04:45:51 -0400
> Brian Masney <masneyb@onstation.org> wrote:
>
> > Convert the tsl2772 device tree bindings to the new YAML format.
> >
> > Signed-off-by: Brian Masney <masneyb@onstation.org>
> Hi Brian,
>
> Good to see this.  I'm afraid it's all a bit new to me so what
> I haven't yet understood is how prescriptive we should be.
> For example, are the phandle references below needed or not?
>
> So for a while yet I'm going to be relying on Rob and others
> to review these and put me on the right track.
>
> Jonathan
>
> > ---
> >  .../devicetree/bindings/iio/light/tsl2772.txt | 42 ---------
> >  .../bindings/iio/light/tsl2772.yaml           | 85 +++++++++++++++++++
> >  2 files changed, 85 insertions(+), 42 deletions(-)
> >  delete mode 100644 Documentation/devicetree/bindings/iio/light/tsl2772.txt
> >  create mode 100644 Documentation/devicetree/bindings/iio/light/tsl2772.yaml
> >

> > diff --git a/Documentation/devicetree/bindings/iio/light/tsl2772.yaml b/Documentation/devicetree/bindings/iio/light/tsl2772.yaml
> > new file mode 100644
> > index 000000000000..b3ac182288d2
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/iio/light/tsl2772.yaml
> > @@ -0,0 +1,85 @@
> > +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)

Do you have the rights on the original file to add BSD license?

> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/iio/light/tsl2772.yaml#
> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > +
> > +title: AMS/TAOS Ambient Light Sensor (ALS) and Proximity Detector
> > +
> > +maintainers:
> > +  - Brian Masney <masneyb@onstation.org>
> > +
> > +description: |
> > +  Ambient light sensing and proximity detection with an i2c interface.
> > +  https://ams.com/documents/20143/36005/TSL2772_DS000181_2-00.pdf
> > +
> > +properties:
> > +  compatible:
> > +    enum:
> > +      - amstaos,tsl2571
> > +      - amstaos,tsl2671
> > +      - amstaos,tmd2671
> > +      - amstaos,tsl2771
> > +      - amstaos,tmd2771
> > +      - amstaos,tsl2572
> > +      - amstaos,tsl2672
> > +      - amstaos,tmd2672
> > +      - amstaos,tsl2772
> > +      - amstaos,tmd2772
> > +      - avago,apds9930
> > +
> > +  reg:
> > +    description: The I2C address of the device

No need for description on common properties unless you have something
unique to add.

> > +    maxItems: 1
> > +
> > +  amstaos,proximity-diodes:
> > +    description: Proximity diodes to enable
> > +    allOf:
> > +      - $ref: /schemas/types.yaml#/definitions/uint32-array
> > +      - minItems: 1
> > +        maxItems: 2
> > +        items:
> > +          minimum: 0
> > +          maximum: 1
>
> Do we need to represent that these can't be <1 0> ?
> (specified in old docs)
> We also have a tighter spec than the uint32-array format in types.yaml
> as don't allow <0>, <1> under the current binding where only <0, 1> is
> allowed.

The uint32-array definition is loose to avoid lots of warnings on
common properties where we can't define the exact size. Over time we
need to tighten up the dts syntax to be consistent (I have a dtc patch
which can spew out lots of warnings to fix these).

So this case is correct. '<0, 1>' means a single array with 2
elements. '<0>, <1>' means 2 arrays each with a single element. There
shouldn't be lots of occurrences.

> > +
> > +  interrupts:
> > +    description: Interrupt generated by the device

No need for description.

> > +    maxItems: 1
> > +
> > +  led-max-microamp:
> > +    description: Current for the proximity LED

This device only has proximity LEDs, right?

> > +    allOf:
> > +      - $ref: /schemas/types.yaml#/definitions/uint32
> > +      - enum: [13000, 25000, 50000, 100000]

We should assume a common schema for 'led-max-microamp', so we just
need the enum.

> > +
> > +  vdd-supply:
> > +    $ref: /schemas/types.yaml#/definitions/phandle
> > +    description: Regulator that provides power to the sensor

Same here for '*-supply'. So just the description is enough.

> > +
> > +  vddio-supply:
> > +    $ref: /schemas/types.yaml#/definitions/phandle
> > +    description: Regulator that provides power to the bus
> > +
> > +required:
> > +  - compatible
> > +  - reg
> > +
> > +examples:
> > +  - |
> > +    #include <dt-bindings/interrupt-controller/irq.h>
> > +
> > +    i2c {
> > +        #address-cells = <1>;
> > +        #size-cells = <0>;
> > +
> > +        tsl2772@39 {

proximity-sensor@39

> > +                compatible = "amstaos,tsl2772";
> > +                reg = <0x39>;
> > +                interrupts-extended = <&msmgpio 61 IRQ_TYPE_EDGE_FALLING>;
> > +                vdd-supply = <&pm8941_l17>;
> > +                vddio-supply = <&pm8941_lvs1>;
> > +                amstaos,proximity-diodes = <0>;
> > +                led-max-microamp = <100000>;
> > +        };
> > +    };
> > +...
>
Brian Masney April 24, 2019, 8:34 a.m. UTC | #3 
On Tue, Apr 23, 2019 at 08:34:13PM -0500, Rob Herring wrote:
> On Mon, Apr 22, 2019 at 7:52 AM Jonathan Cameron <jic23@kernel.org> wrote:
> > > diff --git a/Documentation/devicetree/bindings/iio/light/tsl2772.yaml b/Documentation/devicetree/bindings/iio/light/tsl2772.yaml
> > > new file mode 100644
> > > index 000000000000..b3ac182288d2
> > > --- /dev/null
> > > +++ b/Documentation/devicetree/bindings/iio/light/tsl2772.yaml
> > > @@ -0,0 +1,85 @@
> > > +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
> 
> Do you have the rights on the original file to add BSD license?

Yes, I'm the only contributor to the original file.

> > > +    maxItems: 1
> > > +
> > > +  led-max-microamp:
> > > +    description: Current for the proximity LED
> 
> This device only has proximity LEDs, right?

Yes

The other feedback makes sense. Thanks for the review!

Brian
diff mbox series

Patch

diff --git a/Documentation/devicetree/bindings/iio/light/tsl2772.txt b/Documentation/devicetree/bindings/iio/light/tsl2772.txt
deleted file mode 100644
index 1c5e6f17a1df..000000000000
--- a/Documentation/devicetree/bindings/iio/light/tsl2772.txt
+++ /dev/null
@@ -1,42 +0,0 @@ 
-* AMS/TAOS ALS and proximity sensor
-
-Required properties:
-
-  - compatible: Should be one of
-		"amstaos,tsl2571"
-		"amstaos,tsl2671"
-		"amstaos,tmd2671"
-		"amstaos,tsl2771"
-		"amstaos,tmd2771"
-		"amstaos,tsl2572"
-		"amstaos,tsl2672"
-		"amstaos,tmd2672"
-		"amstaos,tsl2772"
-		"amstaos,tmd2772"
-		"avago,apds9930"
-  - reg: the I2C address of the device
-
-Optional properties:
-
-  - amstaos,proximity-diodes - proximity diodes to enable. <0>, <1>, or <0 1>
-                               are the only valid values.
-  - led-max-microamp - current for the proximity LED. Must be 100000, 50000,
-                       25000, or 13000.
-  - vdd-supply: phandle to the regulator that provides power to the sensor.
-  - vddio-supply: phandle to the regulator that provides power to the bus.
-  - interrupts: the sole interrupt generated by the device
-
-  Refer to interrupt-controller/interrupts.txt for generic interrupt client
-  node bindings.
-
-Example:
-
-tsl2772@39 {
-	compatible = "amstaos,tsl2772";
-	reg = <0x39>;
-	interrupts-extended = <&msmgpio 61 IRQ_TYPE_EDGE_FALLING>;
-	vdd-supply = <&pm8941_l17>;
-	vddio-supply = <&pm8941_lvs1>;
-	amstaos,proximity-diodes = <0>;
-	led-max-microamp = <100000>;
-};
diff --git a/Documentation/devicetree/bindings/iio/light/tsl2772.yaml b/Documentation/devicetree/bindings/iio/light/tsl2772.yaml
new file mode 100644
index 000000000000..b3ac182288d2
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/light/tsl2772.yaml
@@ -0,0 +1,85 @@ 
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/light/tsl2772.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: AMS/TAOS Ambient Light Sensor (ALS) and Proximity Detector
+
+maintainers:
+  - Brian Masney <masneyb@onstation.org>
+
+description: |
+  Ambient light sensing and proximity detection with an i2c interface.
+  https://ams.com/documents/20143/36005/TSL2772_DS000181_2-00.pdf
+
+properties:
+  compatible:
+    enum:
+      - amstaos,tsl2571
+      - amstaos,tsl2671
+      - amstaos,tmd2671
+      - amstaos,tsl2771
+      - amstaos,tmd2771
+      - amstaos,tsl2572
+      - amstaos,tsl2672
+      - amstaos,tmd2672
+      - amstaos,tsl2772
+      - amstaos,tmd2772
+      - avago,apds9930
+
+  reg:
+    description: The I2C address of the device
+    maxItems: 1
+
+  amstaos,proximity-diodes:
+    description: Proximity diodes to enable
+    allOf:
+      - $ref: /schemas/types.yaml#/definitions/uint32-array
+      - minItems: 1
+        maxItems: 2
+        items:
+          minimum: 0
+          maximum: 1
+
+  interrupts:
+    description: Interrupt generated by the device
+    maxItems: 1
+
+  led-max-microamp:
+    description: Current for the proximity LED
+    allOf:
+      - $ref: /schemas/types.yaml#/definitions/uint32
+      - enum: [13000, 25000, 50000, 100000]
+
+  vdd-supply:
+    $ref: /schemas/types.yaml#/definitions/phandle
+    description: Regulator that provides power to the sensor
+
+  vddio-supply:
+    $ref: /schemas/types.yaml#/definitions/phandle
+    description: Regulator that provides power to the bus
+
+required:
+  - compatible
+  - reg
+
+examples:
+  - |
+    #include <dt-bindings/interrupt-controller/irq.h>
+
+    i2c {
+        #address-cells = <1>;
+        #size-cells = <0>;
+
+        tsl2772@39 {
+                compatible = "amstaos,tsl2772";
+                reg = <0x39>;
+                interrupts-extended = <&msmgpio 61 IRQ_TYPE_EDGE_FALLING>;
+                vdd-supply = <&pm8941_l17>;
+                vddio-supply = <&pm8941_lvs1>;
+                amstaos,proximity-diodes = <0>;
+                led-max-microamp = <100000>;
+        };
+    };
+...