diff mbox series

[02/40] dt-bindings: mfd: ti,am3359-tscadc: Add a yaml description for this MFD

Message ID 20210825152518.379386-3-miquel.raynal@bootlin.com (mailing list archive)
State Superseded
Headers show
Series TI AM437X ADC1 | expand

Commit Message

Miquel Raynal Aug. 25, 2021, 3:24 p.m. UTC
There is a very light description of this MFD in a text file dedicated
to a touchscreen controller (which is one of the two children of the
MFD). Here is now a complete yaml description.

Signed-off-by: Miquel Raynal <miquel.raynal@bootlin.com>
---
 .../bindings/mfd/ti,am3359-tscadc.yaml        | 75 +++++++++++++++++++
 1 file changed, 75 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/mfd/ti,am3359-tscadc.yaml

Comments

Jonathan Cameron Aug. 30, 2021, 12:47 p.m. UTC | #1
On Wed, 25 Aug 2021 17:24:40 +0200
Miquel Raynal <miquel.raynal@bootlin.com> wrote:

> There is a very light description of this MFD in a text file dedicated
> to a touchscreen controller (which is one of the two children of the
> MFD). Here is now a complete yaml description.

Make sure to call out places where you are filling in gaps in the
txt file description.  Looks like we forgot to keep that up to date as the driver
evolved. oops.

> 
> Signed-off-by: Miquel Raynal <miquel.raynal@bootlin.com>
> ---
>  .../bindings/mfd/ti,am3359-tscadc.yaml        | 75 +++++++++++++++++++
>  1 file changed, 75 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/mfd/ti,am3359-tscadc.yaml
> 
> diff --git a/Documentation/devicetree/bindings/mfd/ti,am3359-tscadc.yaml b/Documentation/devicetree/bindings/mfd/ti,am3359-tscadc.yaml
> new file mode 100644
> index 000000000000..96b329508d8a
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/mfd/ti,am3359-tscadc.yaml
> @@ -0,0 +1,75 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/mfd/ti,am3359-tscadc.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: TI AM3359 Touchscreen controller/ADC
> +
> +maintainers:
> +  - Miquel Raynal <miquel.raynal@bootlin.com>
> +
> +properties:
> +  compatible:
> +    const: ti,am3359-tscadc

text documents the more specific ti,am654-tscadc as well.
Something like

   properties:
     compatible:
       oneof:
         - const: ti,am3359-tscadc
         - items:
             - const: ti,am654-tscadc
             - const: ti,am3359-tscadc

Note this superceeds my comment on later patches about changing to enum when
introducing the new compatible. Ah well.

example for this would be something like
Documentation/devicetree/bindings/iio/adc/amlogic,meson-saradc.yam;

> +
> +  reg:
> +    maxItems: 1
> +
> +  interrupts:
> +    maxItems: 1
> +
> +  clocks:
> +    maxItems: 1
> +
> +  clock-names:
> +    const: fck
> +
> +  dmas:
> +    items:
> +      - description: DMA controller phandle and request line for FIFO0
> +      - description: DMA controller phandle and request line for FIFO1
> +
> +  dma-names:
> +    items:
> +      - const: fifo0
> +      - const: fifo1
> +
> +patternProperties:
> +  "^adc$":
> +    description: ADC
> +
> +  "^tsc$":
> +    description: Touchscreen controller
> +
> +required:
> +  - compatible
> +  - reg
> +  - interrupts
> +  - clocks
> +  - clock-names
> +  - dmas
> +  - dma-names
> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    #include <dt-bindings/interrupt-controller/arm-gic.h>
> +
> +    tscadc: tscadc@0 {
> +        compatible = "ti,am3359-tscadc";
> +        reg = <0x0 0x1000>;
> +        interrupts = <GIC_SPI 16 IRQ_TYPE_LEVEL_HIGH>;
> +        clocks = <&adc_tsc_fck>;
> +        clock-names = "fck";
> +        dmas = <&edma 53 0>, <&edma 57 0>;
> +        dma-names = "fifo0", "fifo1";
> +        status = "disabled";
> +
> +        tsc {
> +        };
> +
> +        adc {
> +        };
> +    };
Rob Herring (Arm) Aug. 31, 2021, 7:33 p.m. UTC | #2
On Wed, Aug 25, 2021 at 05:24:40PM +0200, Miquel Raynal wrote:
> There is a very light description of this MFD in a text file dedicated
> to a touchscreen controller (which is one of the two children of the
> MFD). Here is now a complete yaml description.
> 
> Signed-off-by: Miquel Raynal <miquel.raynal@bootlin.com>
> ---
>  .../bindings/mfd/ti,am3359-tscadc.yaml        | 75 +++++++++++++++++++
>  1 file changed, 75 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/mfd/ti,am3359-tscadc.yaml
> 
> diff --git a/Documentation/devicetree/bindings/mfd/ti,am3359-tscadc.yaml b/Documentation/devicetree/bindings/mfd/ti,am3359-tscadc.yaml
> new file mode 100644
> index 000000000000..96b329508d8a
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/mfd/ti,am3359-tscadc.yaml
> @@ -0,0 +1,75 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/mfd/ti,am3359-tscadc.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: TI AM3359 Touchscreen controller/ADC
> +
> +maintainers:
> +  - Miquel Raynal <miquel.raynal@bootlin.com>
> +
> +properties:
> +  compatible:
> +    const: ti,am3359-tscadc
> +
> +  reg:
> +    maxItems: 1
> +
> +  interrupts:
> +    maxItems: 1
> +
> +  clocks:
> +    maxItems: 1
> +
> +  clock-names:
> +    const: fck
> +
> +  dmas:
> +    items:
> +      - description: DMA controller phandle and request line for FIFO0
> +      - description: DMA controller phandle and request line for FIFO1
> +
> +  dma-names:
> +    items:
> +      - const: fifo0
> +      - const: fifo1
> +
> +patternProperties:
> +  "^adc$":
> +    description: ADC
> +
> +  "^tsc$":
> +    description: Touchscreen controller

These are fixed strings, so move to 'properties'. They also need 'type: 
object' to indicate they are nodes.

> +
> +required:
> +  - compatible
> +  - reg
> +  - interrupts
> +  - clocks
> +  - clock-names
> +  - dmas
> +  - dma-names
> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    #include <dt-bindings/interrupt-controller/arm-gic.h>
> +
> +    tscadc: tscadc@0 {
> +        compatible = "ti,am3359-tscadc";
> +        reg = <0x0 0x1000>;
> +        interrupts = <GIC_SPI 16 IRQ_TYPE_LEVEL_HIGH>;
> +        clocks = <&adc_tsc_fck>;
> +        clock-names = "fck";
> +        dmas = <&edma 53 0>, <&edma 57 0>;
> +        dma-names = "fifo0", "fifo1";
> +        status = "disabled";

Don't show 'status' in examples. It disables some checks.

> +
> +        tsc {
> +        };
> +
> +        adc {
> +        };
> +    };
> -- 
> 2.27.0
> 
>
Miquel Raynal Sept. 2, 2021, 5:35 p.m. UTC | #3
Hi Jonathan,

Jonathan Cameron <jic23@kernel.org> wrote on Mon, 30 Aug 2021 13:47:14
+0100:

> On Wed, 25 Aug 2021 17:24:40 +0200
> Miquel Raynal <miquel.raynal@bootlin.com> wrote:
> 
> > There is a very light description of this MFD in a text file dedicated
> > to a touchscreen controller (which is one of the two children of the
> > MFD). Here is now a complete yaml description.  
> 
> Make sure to call out places where you are filling in gaps in the
> txt file description.  Looks like we forgot to keep that up to date as the driver
> evolved. oops.

Right, I always forget these links, will update them.

> 
> > 
> > Signed-off-by: Miquel Raynal <miquel.raynal@bootlin.com>
> > ---
> >  .../bindings/mfd/ti,am3359-tscadc.yaml        | 75 +++++++++++++++++++
> >  1 file changed, 75 insertions(+)
> >  create mode 100644 Documentation/devicetree/bindings/mfd/ti,am3359-tscadc.yaml
> > 
> > diff --git a/Documentation/devicetree/bindings/mfd/ti,am3359-tscadc.yaml b/Documentation/devicetree/bindings/mfd/ti,am3359-tscadc.yaml
> > new file mode 100644
> > index 000000000000..96b329508d8a
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/mfd/ti,am3359-tscadc.yaml
> > @@ -0,0 +1,75 @@
> > +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/mfd/ti,am3359-tscadc.yaml#
> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > +
> > +title: TI AM3359 Touchscreen controller/ADC
> > +
> > +maintainers:
> > +  - Miquel Raynal <miquel.raynal@bootlin.com>
> > +
> > +properties:
> > +  compatible:
> > +    const: ti,am3359-tscadc  
> 
> text documents the more specific ti,am654-tscadc as well.

Oops, I saw it and then forgot. Thanks for checking!

> Something like
> 
>    properties:
>      compatible:
>        oneof:
>          - const: ti,am3359-tscadc
>          - items:
>              - const: ti,am654-tscadc
>              - const: ti,am3359-tscadc
> 
> Note this superceeds my comment on later patches about changing to enum when
> introducing the new compatible. Ah well.

No problem (and thanks for the 50+ reviews btw ;) )

Thanks,
Miquèl
diff mbox series

Patch

diff --git a/Documentation/devicetree/bindings/mfd/ti,am3359-tscadc.yaml b/Documentation/devicetree/bindings/mfd/ti,am3359-tscadc.yaml
new file mode 100644
index 000000000000..96b329508d8a
--- /dev/null
+++ b/Documentation/devicetree/bindings/mfd/ti,am3359-tscadc.yaml
@@ -0,0 +1,75 @@ 
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mfd/ti,am3359-tscadc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: TI AM3359 Touchscreen controller/ADC
+
+maintainers:
+  - Miquel Raynal <miquel.raynal@bootlin.com>
+
+properties:
+  compatible:
+    const: ti,am3359-tscadc
+
+  reg:
+    maxItems: 1
+
+  interrupts:
+    maxItems: 1
+
+  clocks:
+    maxItems: 1
+
+  clock-names:
+    const: fck
+
+  dmas:
+    items:
+      - description: DMA controller phandle and request line for FIFO0
+      - description: DMA controller phandle and request line for FIFO1
+
+  dma-names:
+    items:
+      - const: fifo0
+      - const: fifo1
+
+patternProperties:
+  "^adc$":
+    description: ADC
+
+  "^tsc$":
+    description: Touchscreen controller
+
+required:
+  - compatible
+  - reg
+  - interrupts
+  - clocks
+  - clock-names
+  - dmas
+  - dma-names
+
+additionalProperties: false
+
+examples:
+  - |
+    #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+    tscadc: tscadc@0 {
+        compatible = "ti,am3359-tscadc";
+        reg = <0x0 0x1000>;
+        interrupts = <GIC_SPI 16 IRQ_TYPE_LEVEL_HIGH>;
+        clocks = <&adc_tsc_fck>;
+        clock-names = "fck";
+        dmas = <&edma 53 0>, <&edma 57 0>;
+        dma-names = "fifo0", "fifo1";
+        status = "disabled";
+
+        tsc {
+        };
+
+        adc {
+        };
+    };