[1/2] dt-bindings: iio: adc: Add binding documentation for Renesas RZ/G2L A/D converter

Commit Message

Prabhakar June 29, 2021, 10:03 p.m. UTC

Add binding documentation for Renesas RZ/G2L A/D converter block.

Signed-off-by: Lad Prabhakar <[e-mail]>
Reviewed-by: Biju Das <[e-mail]>
---
 .../bindings/iio/adc/renesas,rzg2l-adc.yaml   | 121 ++++++++++++++++++
 1 file changed, 121 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml

Comments

Rob Herring (Arm) July 1, 2021, 2:02 p.m. UTC | #1

On Tue, 29 Jun 2021 23:03:27 +0100, Lad Prabhakar wrote:
> Add binding documentation for Renesas RZ/G2L A/D converter block.
> 
> Signed-off-by: Lad Prabhakar <[e-mail]>
> Reviewed-by: Biju Das <[e-mail]>
> ---
>  .../bindings/iio/adc/renesas,rzg2l-adc.yaml   | 121 ++++++++++++++++++
>  1 file changed, 121 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml
> 

My bot found errors running 'make DT_CHECKER_FLAGS=-m dt_binding_check'
on your patch (DT_CHECKER_FLAGS is new in v5.13):

yamllint warnings/errors:

dtschema/dtc warnings/errors:
Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.example.dts:19:18: fatal error: dt-bindings/clock/r9a07g044-cpg.h: No such file or directory
   19 |         #include <dt-bindings/clock/r9a07g044-cpg.h>
      |                  ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
compilation terminated.
make[1]: *** [scripts/Makefile.lib:380: Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.example.dt.yaml] Error 1
make[1]: *** Waiting for unfinished jobs....
make: *** [Makefile:1416: dt_binding_check] Error 2
\ndoc reference errors (make refcheckdocs):

See https://patchwork.ozlabs.org/patch/1498675

This check can fail if there are any dependencies. The base for a patch
series is generally the most recent rc1.

If you already ran 'make dt_binding_check' and didn't see the above
error(s), then make sure 'yamllint' is installed and dt-schema is up to
date:

pip3 install dtschema --upgrade

Please check and re-submit.

Rob Herring (Arm) July 1, 2021, 8:21 p.m. UTC | #2

On Tue, Jun 29, 2021 at 11:03:27PM +0100, Lad Prabhakar wrote:
> Add binding documentation for Renesas RZ/G2L A/D converter block.
> 
> Signed-off-by: Lad Prabhakar <[e-mail]>
> Reviewed-by: Biju Das <[e-mail]>
> ---
>  .../bindings/iio/adc/renesas,rzg2l-adc.yaml   | 121 ++++++++++++++++++
>  1 file changed, 121 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml
> 
> diff --git a/Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml b/Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml
> new file mode 100644
> index 000000000000..db935d6d59eb
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml
> @@ -0,0 +1,121 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/iio/adc/renesas,rzg2l-adc.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Renesas RZ/G2L ADC
> +
> +maintainers:
> +  - Lad Prabhakar <[e-mail]>
> +
> +description: |
> +  A/D Converter block is a successive approximation analog-to-digital converter
> +  with a 12-bit accuracy. Up to eight analog input channels can be selected.
> +  Conversions can be performed in single or repeat mode. Result of the ADC is
> +  stored in a 32-bit data register corresponding to each channel.
> +
> +properties:
> +  compatible:
> +    oneOf:

You can drop oneOf here.

> +      - items:
> +          - enum:
> +              - renesas,r9a07g044-adc   # RZ/G2{L,LC}
> +          - const: renesas,rzg2l-adc
> +
> +  reg:
> +    maxItems: 1
> +
> +  interrupts:
> +    maxItems: 1
> +
> +  clocks:
> +    items:
> +      - description: converter clock
> +      - description: peripheral clock
> +
> +  clock-names:
> +    items:
> +      - const: adclk
> +      - const: pclk
> +
> +  power-domains:
> +    maxItems: 1
> +
> +  resets:
> +    maxItems: 2
> +
> +  reset-names:
> +    items:
> +      - const: presetn
> +      - const: adrst-n
> +
> +  renesas-rzg2l,adc-trigger-mode:
> +    $ref: /schemas/types.yaml#/definitions/uint8
> +    description: Trigger mode for A/D converter
> +    enum:
> +      - 0 # Software trigger mode (Defaults)
> +      - 1 # Asynchronous trigger using ADC_TRG trigger input pin
> +      - 2 # Synchronous trigger (Trigger from MTU3a/GPT)
> +    default: 0
> +
> +  gpios:

A named gpio is preferred. trigger-gpios?

> +    description:
> +      ADC_TRG trigger input pin
> +    maxItems: 1
> +
> +  renesas-rzg2l,adc-channels:
> +    $ref: /schemas/types.yaml#/definitions/uint8-array
> +    description: Input channels available on platform
> +    uniqueItems: true
> +    minItems: 1
> +    maxItems: 8
> +    items:
> +      enum: [0, 1, 2, 3, 4, 5, 6, 7]
> +
> +  "#io-channel-cells":
> +    const: 1
> +
> +required:
> +  - compatible
> +  - reg
> +  - interrupts
> +  - clocks
> +  - clock-names
> +  - power-domains
> +  - resets
> +  - reset-names
> +  - renesas-rzg2l,adc-channels
> +  - "#io-channel-cells"
> +
> +allOf:
> +  - if:
> +      properties:
> +        renesas-rzg2l,adc-trigger-mode:
> +          const: 1
> +    then:
> +      required:
> +        - gpios
> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    #include <dt-bindings/clock/r9a07g044-cpg.h>
> +    #include <dt-bindings/interrupt-controller/arm-gic.h>
> +
> +    adc: adc@10059000 {
> +      compatible = "renesas,r9a07g044-adc", "renesas,rzg2l-adc";
> +      reg = <0x10059000 0x400>;
> +      interrupts = <GIC_SPI 347 IRQ_TYPE_EDGE_RISING>;
> +      clocks = <&cpg CPG_MOD R9A07G044_ADC_ADCLK>,
> +               <&cpg CPG_MOD R9A07G044_ADC_PCLK>;
> +      clock-names = "adclk", "pclk";
> +      power-domains = <&cpg>;
> +      resets = <&cpg R9A07G044_ADC_PRESETN>,
> +               <&cpg R9A07G044_ADC_ADRST_N>;
> +      reset-names = "presetn", "adrst-n";
> +      #io-channel-cells = <1>;
> +      renesas-rzg2l,adc-trigger-mode = /bits/ 8 <0>;
> +      renesas-rzg2l,adc-channels = /bits/ 8 <0 1 2 3 4 5 6>;
> +    };
> -- 
> 2.17.1
> 
>

Jonathan Cameron July 3, 2021, 5:19 p.m. UTC | #3

On Tue, 29 Jun 2021 23:03:27 +0100
Lad Prabhakar <[e-mail]> wrote:

> Add binding documentation for Renesas RZ/G2L A/D converter block.
> 
> Signed-off-by: Lad Prabhakar <[e-mail]>
> Reviewed-by: Biju Das <[e-mail]>
Hi,

See inline

Jonathan

> ---
>  .../bindings/iio/adc/renesas,rzg2l-adc.yaml   | 121 ++++++++++++++++++
>  1 file changed, 121 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml
> 
> diff --git a/Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml b/Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml
> new file mode 100644
> index 000000000000..db935d6d59eb
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml
> @@ -0,0 +1,121 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/iio/adc/renesas,rzg2l-adc.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Renesas RZ/G2L ADC
> +
> +maintainers:
> +  - Lad Prabhakar <[e-mail]>
> +
> +description: |
> +  A/D Converter block is a successive approximation analog-to-digital converter
> +  with a 12-bit accuracy. Up to eight analog input channels can be selected.
> +  Conversions can be performed in single or repeat mode. Result of the ADC is
> +  stored in a 32-bit data register corresponding to each channel.
> +
> +properties:
> +  compatible:
> +    oneOf:
> +      - items:
> +          - enum:
> +              - renesas,r9a07g044-adc   # RZ/G2{L,LC}
> +          - const: renesas,rzg2l-adc
> +
> +  reg:
> +    maxItems: 1
> +
> +  interrupts:
> +    maxItems: 1
> +
> +  clocks:
> +    items:
> +      - description: converter clock
> +      - description: peripheral clock
> +
> +  clock-names:
> +    items:
> +      - const: adclk
> +      - const: pclk
> +
> +  power-domains:
> +    maxItems: 1
> +
> +  resets:
> +    maxItems: 2
> +
> +  reset-names:
> +    items:
> +      - const: presetn
> +      - const: adrst-n
> +
> +  renesas-rzg2l,adc-trigger-mode:
> +    $ref: /schemas/types.yaml#/definitions/uint8
> +    description: Trigger mode for A/D converter
> +    enum:
> +      - 0 # Software trigger mode (Defaults)
> +      - 1 # Asynchronous trigger using ADC_TRG trigger input pin
> +      - 2 # Synchronous trigger (Trigger from MTU3a/GPT)

Is this a function of the board in some fashion?  If not it sounds like
something that should be in control of userspace.  Normally we'd
do that by having the driver register some iio_triggers and depending
on which one is selected do the equivalent of what you have here.

> +    default: 0
> +
> +  gpios:
> +    description:
> +      ADC_TRG trigger input pin
> +    maxItems: 1
Why is this mode useful?  I'm assuming the gpio write would take a register
write and the software trigger mode also requires a register write.

Normally the reason for a pin like this is to support synchronising with
external hardware.   If that's the case, we should call that out here.
often the pin isn't even connected to a gpio in our control.
(i.e. it's a trigger signal from some other device.)

> +
> +  renesas-rzg2l,adc-channels:
> +    $ref: /schemas/types.yaml#/definitions/uint8-array
> +    description: Input channels available on platform
> +    uniqueItems: true
> +    minItems: 1
> +    maxItems: 8
> +    items:
> +      enum: [0, 1, 2, 3, 4, 5, 6, 7]

Is this a function of different devices (should have different compatibles)
or of what is wired up.  If it's what is wired up, then how do you know which
subset of channels are connected?  We have the generic adc channel binding
in iio/adc/adc.yaml for the case where we only want to expose those channels
that are wired up.  It uses a node per channel.

> +
> +  "#io-channel-cells":
> +    const: 1
> +
> +required:
> +  - compatible
> +  - reg
> +  - interrupts
> +  - clocks
> +  - clock-names
> +  - power-domains
> +  - resets
> +  - reset-names
> +  - renesas-rzg2l,adc-channels
> +  - "#io-channel-cells"
> +
> +allOf:
> +  - if:
> +      properties:
> +        renesas-rzg2l,adc-trigger-mode:
> +          const: 1
> +    then:
> +      required:
> +        - gpios
> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    #include <dt-bindings/clock/r9a07g044-cpg.h>
> +    #include <dt-bindings/interrupt-controller/arm-gic.h>
> +
> +    adc: adc@10059000 {
> +      compatible = "renesas,r9a07g044-adc", "renesas,rzg2l-adc";
> +      reg = <0x10059000 0x400>;
> +      interrupts = <GIC_SPI 347 IRQ_TYPE_EDGE_RISING>;
> +      clocks = <&cpg CPG_MOD R9A07G044_ADC_ADCLK>,
> +               <&cpg CPG_MOD R9A07G044_ADC_PCLK>;
> +      clock-names = "adclk", "pclk";
> +      power-domains = <&cpg>;
> +      resets = <&cpg R9A07G044_ADC_PRESETN>,
> +               <&cpg R9A07G044_ADC_ADRST_N>;
> +      reset-names = "presetn", "adrst-n";
> +      #io-channel-cells = <1>;
> +      renesas-rzg2l,adc-trigger-mode = /bits/ 8 <0>;
> +      renesas-rzg2l,adc-channels = /bits/ 8 <0 1 2 3 4 5 6>;
> +    };

Lad, Prabhakar July 13, 2021, 4 p.m. UTC | #4

Hi Rob,

Thank you for the review.

On Thu, Jul 1, 2021 at 9:21 PM Rob Herring <[e-mail]> wrote:
>
> On Tue, Jun 29, 2021 at 11:03:27PM +0100, Lad Prabhakar wrote:
> > Add binding documentation for Renesas RZ/G2L A/D converter block.
> >
> > Signed-off-by: Lad Prabhakar <[e-mail]>
> > Reviewed-by: Biju Das <[e-mail]>
> > ---
> >  .../bindings/iio/adc/renesas,rzg2l-adc.yaml   | 121 ++++++++++++++++++
> >  1 file changed, 121 insertions(+)
> >  create mode 100644 Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml
> >
> > diff --git a/Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml b/Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml
> > new file mode 100644
> > index 000000000000..db935d6d59eb
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml
> > @@ -0,0 +1,121 @@
> > +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/iio/adc/renesas,rzg2l-adc.yaml#
> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > +
> > +title: Renesas RZ/G2L ADC
> > +
> > +maintainers:
> > +  - Lad Prabhakar <[e-mail]>
> > +
> > +description: |
> > +  A/D Converter block is a successive approximation analog-to-digital converter
> > +  with a 12-bit accuracy. Up to eight analog input channels can be selected.
> > +  Conversions can be performed in single or repeat mode. Result of the ADC is
> > +  stored in a 32-bit data register corresponding to each channel.
> > +
> > +properties:
> > +  compatible:
> > +    oneOf:
>
> You can drop oneOf here.
>
Dropping oneOf from here dt_binding_check complains with below report,
Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml:
properties:compatible: [{'items': [{'enum':
['renesas,r9a07g044-adc']}, {'const': 'renesas,rzg2l-adc'}]}] is not
of type 'object', 'boolean'
from schema $id: http://json-schema.org/draft-07/schema#

> > +      - items:
> > +          - enum:
> > +              - renesas,r9a07g044-adc   # RZ/G2{L,LC}
> > +          - const: renesas,rzg2l-adc
> > +
> > +  reg:
> > +    maxItems: 1
> > +
> > +  interrupts:
> > +    maxItems: 1
> > +
> > +  clocks:
> > +    items:
> > +      - description: converter clock
> > +      - description: peripheral clock
> > +
> > +  clock-names:
> > +    items:
> > +      - const: adclk
> > +      - const: pclk
> > +
> > +  power-domains:
> > +    maxItems: 1
> > +
> > +  resets:
> > +    maxItems: 2
> > +
> > +  reset-names:
> > +    items:
> > +      - const: presetn
> > +      - const: adrst-n
> > +
> > +  renesas-rzg2l,adc-trigger-mode:
> > +    $ref: /schemas/types.yaml#/definitions/uint8
> > +    description: Trigger mode for A/D converter
> > +    enum:
> > +      - 0 # Software trigger mode (Defaults)
> > +      - 1 # Asynchronous trigger using ADC_TRG trigger input pin
> > +      - 2 # Synchronous trigger (Trigger from MTU3a/GPT)
> > +    default: 0
> > +
> > +  gpios:
>
> A named gpio is preferred. trigger-gpios?
>
Agreed.

Cheers,
Prabhakar

> > +    description:
> > +      ADC_TRG trigger input pin
> > +    maxItems: 1
> > +
> > +  renesas-rzg2l,adc-channels:
> > +    $ref: /schemas/types.yaml#/definitions/uint8-array
> > +    description: Input channels available on platform
> > +    uniqueItems: true
> > +    minItems: 1
> > +    maxItems: 8
> > +    items:
> > +      enum: [0, 1, 2, 3, 4, 5, 6, 7]
> > +
> > +  "#io-channel-cells":
> > +    const: 1
> > +
> > +required:
> > +  - compatible
> > +  - reg
> > +  - interrupts
> > +  - clocks
> > +  - clock-names
> > +  - power-domains
> > +  - resets
> > +  - reset-names
> > +  - renesas-rzg2l,adc-channels
> > +  - "#io-channel-cells"
> > +
> > +allOf:
> > +  - if:
> > +      properties:
> > +        renesas-rzg2l,adc-trigger-mode:
> > +          const: 1
> > +    then:
> > +      required:
> > +        - gpios
> > +
> > +additionalProperties: false
> > +
> > +examples:
> > +  - |
> > +    #include <dt-bindings/clock/r9a07g044-cpg.h>
> > +    #include <dt-bindings/interrupt-controller/arm-gic.h>
> > +
> > +    adc: adc@10059000 {
> > +      compatible = "renesas,r9a07g044-adc", "renesas,rzg2l-adc";
> > +      reg = <0x10059000 0x400>;
> > +      interrupts = <GIC_SPI 347 IRQ_TYPE_EDGE_RISING>;
> > +      clocks = <&cpg CPG_MOD R9A07G044_ADC_ADCLK>,
> > +               <&cpg CPG_MOD R9A07G044_ADC_PCLK>;
> > +      clock-names = "adclk", "pclk";
> > +      power-domains = <&cpg>;
> > +      resets = <&cpg R9A07G044_ADC_PRESETN>,
> > +               <&cpg R9A07G044_ADC_ADRST_N>;
> > +      reset-names = "presetn", "adrst-n";
> > +      #io-channel-cells = <1>;
> > +      renesas-rzg2l,adc-trigger-mode = /bits/ 8 <0>;
> > +      renesas-rzg2l,adc-channels = /bits/ 8 <0 1 2 3 4 5 6>;
> > +    };
> > --
> > 2.17.1
> >
> >

Geert Uytterhoeven July 13, 2021, 4:32 p.m. UTC | #5

Hi Prabhakar,

On Tue, Jul 13, 2021 at 6:01 PM Lad, Prabhakar
<[e-mail]> wrote:
> On Thu, Jul 1, 2021 at 9:21 PM Rob Herring <[e-mail]> wrote:
> > On Tue, Jun 29, 2021 at 11:03:27PM +0100, Lad Prabhakar wrote:
> > > Add binding documentation for Renesas RZ/G2L A/D converter block.
> > >
> > > Signed-off-by: Lad Prabhakar <[e-mail]>
> > > Reviewed-by: Biju Das <[e-mail]>
> > > ---
> > >  .../bindings/iio/adc/renesas,rzg2l-adc.yaml   | 121 ++++++++++++++++++
> > >  1 file changed, 121 insertions(+)
> > >  create mode 100644 Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml
> > >
> > > diff --git a/Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml b/Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml
> > > new file mode 100644
> > > index 000000000000..db935d6d59eb
> > > --- /dev/null
> > > +++ b/Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml
> > > @@ -0,0 +1,121 @@
> > > +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> > > +%YAML 1.2
> > > +---
> > > +$id: http://devicetree.org/schemas/iio/adc/renesas,rzg2l-adc.yaml#
> > > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > > +
> > > +title: Renesas RZ/G2L ADC
> > > +
> > > +maintainers:
> > > +  - Lad Prabhakar <[e-mail]>
> > > +
> > > +description: |
> > > +  A/D Converter block is a successive approximation analog-to-digital converter
> > > +  with a 12-bit accuracy. Up to eight analog input channels can be selected.
> > > +  Conversions can be performed in single or repeat mode. Result of the ADC is
> > > +  stored in a 32-bit data register corresponding to each channel.
> > > +
> > > +properties:
> > > +  compatible:
> > > +    oneOf:
> >
> > You can drop oneOf here.
> >
> Dropping oneOf from here dt_binding_check complains with below report,
> Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml:
> properties:compatible: [{'items': [{'enum':
> ['renesas,r9a07g044-adc']}, {'const': 'renesas,rzg2l-adc'}]}] is not
> of type 'object', 'boolean'
> from schema $id: http://json-schema.org/draft-07/schema#

You forgot to drop the dash in front of the items, right?

Gr{oetje,eeting}s,

                        Geert

Lad, Prabhakar July 13, 2021, 4:39 p.m. UTC | #6

Hi Geert,

On Tue, Jul 13, 2021 at 5:32 PM Geert Uytterhoeven <[e-mail]> wrote:
>
> Hi Prabhakar,
>
> On Tue, Jul 13, 2021 at 6:01 PM Lad, Prabhakar
> <[e-mail]> wrote:
> > On Thu, Jul 1, 2021 at 9:21 PM Rob Herring <[e-mail]> wrote:
> > > On Tue, Jun 29, 2021 at 11:03:27PM +0100, Lad Prabhakar wrote:
> > > > Add binding documentation for Renesas RZ/G2L A/D converter block.
> > > >
> > > > Signed-off-by: Lad Prabhakar <[e-mail]>
> > > > Reviewed-by: Biju Das <[e-mail]>
> > > > ---
> > > >  .../bindings/iio/adc/renesas,rzg2l-adc.yaml   | 121 ++++++++++++++++++
> > > >  1 file changed, 121 insertions(+)
> > > >  create mode 100644 Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml
> > > >
> > > > diff --git a/Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml b/Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml
> > > > new file mode 100644
> > > > index 000000000000..db935d6d59eb
> > > > --- /dev/null
> > > > +++ b/Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml
> > > > @@ -0,0 +1,121 @@
> > > > +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> > > > +%YAML 1.2
> > > > +---
> > > > +$id: http://devicetree.org/schemas/iio/adc/renesas,rzg2l-adc.yaml#
> > > > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > > > +
> > > > +title: Renesas RZ/G2L ADC
> > > > +
> > > > +maintainers:
> > > > +  - Lad Prabhakar <[e-mail]>
> > > > +
> > > > +description: |
> > > > +  A/D Converter block is a successive approximation analog-to-digital converter
> > > > +  with a 12-bit accuracy. Up to eight analog input channels can be selected.
> > > > +  Conversions can be performed in single or repeat mode. Result of the ADC is
> > > > +  stored in a 32-bit data register corresponding to each channel.
> > > > +
> > > > +properties:
> > > > +  compatible:
> > > > +    oneOf:
> > >
> > > You can drop oneOf here.
> > >
> > Dropping oneOf from here dt_binding_check complains with below report,
> > Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml:
> > properties:compatible: [{'items': [{'enum':
> > ['renesas,r9a07g044-adc']}, {'const': 'renesas,rzg2l-adc'}]}] is not
> > of type 'object', 'boolean'
> > from schema $id: http://json-schema.org/draft-07/schema#
>
> You forgot to drop the dash in front of the items, right?
>
Argh! Thanks for the pointer.

Cheers,
Prabhakar

> Gr{oetje,eeting}s,
>
>                         Geert
>
> --
> Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- [e-mail]
>
> In personal conversations with technical people, I call myself a hacker. But
> when I'm talking to journalists I just say "programmer" or something like that.
>                                 -- Linus Torvalds

Lad, Prabhakar July 14, 2021, 9:11 a.m. UTC | #7

Hi Jonathan,

Thank you for the review.

On Sat, Jul 3, 2021 at 6:17 PM Jonathan Cameron <[e-mail]> wrote:
>
> On Tue, 29 Jun 2021 23:03:27 +0100
> Lad Prabhakar <[e-mail]> wrote:
>
> > Add binding documentation for Renesas RZ/G2L A/D converter block.
> >
> > Signed-off-by: Lad Prabhakar <[e-mail]>
> > Reviewed-by: Biju Das <[e-mail]>
> Hi,
>
> See inline
>
> Jonathan
>
> > ---
> >  .../bindings/iio/adc/renesas,rzg2l-adc.yaml   | 121 ++++++++++++++++++
> >  1 file changed, 121 insertions(+)
> >  create mode 100644 Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml
> >
> > diff --git a/Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml b/Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml
> > new file mode 100644
> > index 000000000000..db935d6d59eb
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml
> > @@ -0,0 +1,121 @@
> > +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/iio/adc/renesas,rzg2l-adc.yaml#
> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > +
> > +title: Renesas RZ/G2L ADC
> > +
> > +maintainers:
> > +  - Lad Prabhakar <[e-mail]>
> > +
> > +description: |
> > +  A/D Converter block is a successive approximation analog-to-digital converter
> > +  with a 12-bit accuracy. Up to eight analog input channels can be selected.
> > +  Conversions can be performed in single or repeat mode. Result of the ADC is
> > +  stored in a 32-bit data register corresponding to each channel.
> > +
> > +properties:
> > +  compatible:
> > +    oneOf:
> > +      - items:
> > +          - enum:
> > +              - renesas,r9a07g044-adc   # RZ/G2{L,LC}
> > +          - const: renesas,rzg2l-adc
> > +
> > +  reg:
> > +    maxItems: 1
> > +
> > +  interrupts:
> > +    maxItems: 1
> > +
> > +  clocks:
> > +    items:
> > +      - description: converter clock
> > +      - description: peripheral clock
> > +
> > +  clock-names:
> > +    items:
> > +      - const: adclk
> > +      - const: pclk
> > +
> > +  power-domains:
> > +    maxItems: 1
> > +
> > +  resets:
> > +    maxItems: 2
> > +
> > +  reset-names:
> > +    items:
> > +      - const: presetn
> > +      - const: adrst-n
> > +
> > +  renesas-rzg2l,adc-trigger-mode:
> > +    $ref: /schemas/types.yaml#/definitions/uint8
> > +    description: Trigger mode for A/D converter
> > +    enum:
> > +      - 0 # Software trigger mode (Defaults)
> > +      - 1 # Asynchronous trigger using ADC_TRG trigger input pin
> > +      - 2 # Synchronous trigger (Trigger from MTU3a/GPT)
>
> Is this a function of the board in some fashion?  If not it sounds like
> something that should be in control of userspace.  Normally we'd
> do that by having the driver register some iio_triggers and depending
> on which one is selected do the equivalent of what you have here.
>
Agreed for Asynchronous and Synchronous triggers. WRT Software trigger
should this be registered as a  iio_triggers too or read_raw()
callback (with IIO_CHAN_INFO_RAW case)  should be treated as Software
trigger?

> > +    default: 0
> > +
> > +  gpios:
> > +    description:
> > +      ADC_TRG trigger input pin
> > +    maxItems: 1
> Why is this mode useful?  I'm assuming the gpio write would take a register
> write and the software trigger mode also requires a register write.
>
Yes gpio write would take a register write.

> Normally the reason for a pin like this is to support synchronising with
> external hardware.   If that's the case, we should call that out here.
> often the pin isn't even connected to a gpio in our control.
> (i.e. it's a trigger signal from some other device.)
>
So just setting the GPIO pin as input should do the trick.

> > +
> > +  renesas-rzg2l,adc-channels:
> > +    $ref: /schemas/types.yaml#/definitions/uint8-array
> > +    description: Input channels available on platform
> > +    uniqueItems: true
> > +    minItems: 1
> > +    maxItems: 8
> > +    items:
> > +      enum: [0, 1, 2, 3, 4, 5, 6, 7]
>
> Is this a function of different devices (should have different compatibles)
> or of what is wired up.  If it's what is wired up, then how do you know which
Its channels which are wired, for example if channels 0-5 are wired up
the board dts would include the property "renesas-rzg2l,adc-channels =
/bits/ 8 <0 1 2 3 4 5>;"

> subset of channels are connected?  We have the generic adc channel binding
> in iio/adc/adc.yaml for the case where we only want to expose those channels
> that are wired up.  It uses a node per channel.
>
Agreed will do that and drop the custom "renesas-rzg2l,adc-channels"

Cheers,
Prabhakar
> > +
> > +  "#io-channel-cells":
> > +    const: 1
> > +
> > +required:
> > +  - compatible
> > +  - reg
> > +  - interrupts
> > +  - clocks
> > +  - clock-names
> > +  - power-domains
> > +  - resets
> > +  - reset-names
> > +  - renesas-rzg2l,adc-channels
> > +  - "#io-channel-cells"
> > +
> > +allOf:
> > +  - if:
> > +      properties:
> > +        renesas-rzg2l,adc-trigger-mode:
> > +          const: 1
> > +    then:
> > +      required:
> > +        - gpios
> > +
> > +additionalProperties: false
> > +
> > +examples:
> > +  - |
> > +    #include <dt-bindings/clock/r9a07g044-cpg.h>
> > +    #include <dt-bindings/interrupt-controller/arm-gic.h>
> > +
> > +    adc: adc@10059000 {
> > +      compatible = "renesas,r9a07g044-adc", "renesas,rzg2l-adc";
> > +      reg = <0x10059000 0x400>;
> > +      interrupts = <GIC_SPI 347 IRQ_TYPE_EDGE_RISING>;
> > +      clocks = <&cpg CPG_MOD R9A07G044_ADC_ADCLK>,
> > +               <&cpg CPG_MOD R9A07G044_ADC_PCLK>;
> > +      clock-names = "adclk", "pclk";
> > +      power-domains = <&cpg>;
> > +      resets = <&cpg R9A07G044_ADC_PRESETN>,
> > +               <&cpg R9A07G044_ADC_ADRST_N>;
> > +      reset-names = "presetn", "adrst-n";
> > +      #io-channel-cells = <1>;
> > +      renesas-rzg2l,adc-trigger-mode = /bits/ 8 <0>;
> > +      renesas-rzg2l,adc-channels = /bits/ 8 <0 1 2 3 4 5 6>;
> > +    };
>

Jonathan Cameron July 14, 2021, 12:39 p.m. UTC | #8

On Wed, 14 Jul 2021 10:11:49 +0100
"Lad, Prabhakar" <[e-mail]> wrote:

> Hi Jonathan,
> 
> Thank you for the review.
> 
> On Sat, Jul 3, 2021 at 6:17 PM Jonathan Cameron <[e-mail]> wrote:
> >
> > On Tue, 29 Jun 2021 23:03:27 +0100
> > Lad Prabhakar <[e-mail]> wrote:
> >  
> > > Add binding documentation for Renesas RZ/G2L A/D converter block.
> > >
> > > Signed-off-by: Lad Prabhakar <[e-mail]>
> > > Reviewed-by: Biju Das <[e-mail]>  
> > Hi,
> >
> > See inline
> >
> > Jonathan
> >  
> > > ---
> > >  .../bindings/iio/adc/renesas,rzg2l-adc.yaml   | 121 ++++++++++++++++++
> > >  1 file changed, 121 insertions(+)
> > >  create mode 100644 Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml
> > >
> > > diff --git a/Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml b/Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml
> > > new file mode 100644
> > > index 000000000000..db935d6d59eb
> > > --- /dev/null
> > > +++ b/Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml
> > > @@ -0,0 +1,121 @@
> > > +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> > > +%YAML 1.2
> > > +---
> > > +$id: http://devicetree.org/schemas/iio/adc/renesas,rzg2l-adc.yaml#
> > > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > > +
> > > +title: Renesas RZ/G2L ADC
> > > +
> > > +maintainers:
> > > +  - Lad Prabhakar <[e-mail]>
> > > +
> > > +description: |
> > > +  A/D Converter block is a successive approximation analog-to-digital converter
> > > +  with a 12-bit accuracy. Up to eight analog input channels can be selected.
> > > +  Conversions can be performed in single or repeat mode. Result of the ADC is
> > > +  stored in a 32-bit data register corresponding to each channel.
> > > +
> > > +properties:
> > > +  compatible:
> > > +    oneOf:
> > > +      - items:
> > > +          - enum:
> > > +              - renesas,r9a07g044-adc   # RZ/G2{L,LC}
> > > +          - const: renesas,rzg2l-adc
> > > +
> > > +  reg:
> > > +    maxItems: 1
> > > +
> > > +  interrupts:
> > > +    maxItems: 1
> > > +
> > > +  clocks:
> > > +    items:
> > > +      - description: converter clock
> > > +      - description: peripheral clock
> > > +
> > > +  clock-names:
> > > +    items:
> > > +      - const: adclk
> > > +      - const: pclk
> > > +
> > > +  power-domains:
> > > +    maxItems: 1
> > > +
> > > +  resets:
> > > +    maxItems: 2
> > > +
> > > +  reset-names:
> > > +    items:
> > > +      - const: presetn
> > > +      - const: adrst-n
> > > +
> > > +  renesas-rzg2l,adc-trigger-mode:
> > > +    $ref: /schemas/types.yaml#/definitions/uint8
> > > +    description: Trigger mode for A/D converter
> > > +    enum:
> > > +      - 0 # Software trigger mode (Defaults)
> > > +      - 1 # Asynchronous trigger using ADC_TRG trigger input pin
> > > +      - 2 # Synchronous trigger (Trigger from MTU3a/GPT)  
> >
> > Is this a function of the board in some fashion?  If not it sounds like
> > something that should be in control of userspace.  Normally we'd
> > do that by having the driver register some iio_triggers and depending
> > on which one is selected do the equivalent of what you have here.
> >  
> Agreed for Asynchronous and Synchronous triggers. WRT Software trigger
> should this be registered as a  iio_triggers too or read_raw()
> callback (with IIO_CHAN_INFO_RAW case)  should be treated as Software
> trigger?
> 

Normally we'd use an external trigger to provide the software trigger
(plus as you say sysfs reads will map to this functionality).

Something like the sysfs trigger or the hrtimer one would get used, though
also fine to use the dataready trigger from a different device (if you want
approximately synced dta.

> > > +    default: 0
> > > +
> > > +  gpios:
> > > +    description:
> > > +      ADC_TRG trigger input pin
> > > +    maxItems: 1  
> > Why is this mode useful?  I'm assuming the gpio write would take a register
> > write and the software trigger mode also requires a register write.
> >  
> Yes gpio write would take a register write.
> 
> > Normally the reason for a pin like this is to support synchronising with
> > external hardware.   If that's the case, we should call that out here.
> > often the pin isn't even connected to a gpio in our control.
> > (i.e. it's a trigger signal from some other device.)
> >  
> So just setting the GPIO pin as input should do the trick.

Probably the best plan if you actually care about people writing some
trigger up to it that is otherwise invisible to the system.

> 
> > > +
> > > +  renesas-rzg2l,adc-channels:
> > > +    $ref: /schemas/types.yaml#/definitions/uint8-array
> > > +    description: Input channels available on platform
> > > +    uniqueItems: true
> > > +    minItems: 1
> > > +    maxItems: 8
> > > +    items:
> > > +      enum: [0, 1, 2, 3, 4, 5, 6, 7]  
> >
> > Is this a function of different devices (should have different compatibles)
> > or of what is wired up.  If it's what is wired up, then how do you know which  
> Its channels which are wired, for example if channels 0-5 are wired up
> the board dts would include the property "renesas-rzg2l,adc-channels =
> /bits/ 8 <0 1 2 3 4 5>;"
> 
> > subset of channels are connected?  We have the generic adc channel binding
> > in iio/adc/adc.yaml for the case where we only want to expose those channels
> > that are wired up.  It uses a node per channel.
> >  
> Agreed will do that and drop the custom "renesas-rzg2l,adc-channels"

Great,

Jonathan

> 
> Cheers,
> Prabhakar
> > > +
> > > +  "#io-channel-cells":
> > > +    const: 1
> > > +
> > > +required:
> > > +  - compatible
> > > +  - reg
> > > +  - interrupts
> > > +  - clocks
> > > +  - clock-names
> > > +  - power-domains
> > > +  - resets
> > > +  - reset-names
> > > +  - renesas-rzg2l,adc-channels
> > > +  - "#io-channel-cells"
> > > +
> > > +allOf:
> > > +  - if:
> > > +      properties:
> > > +        renesas-rzg2l,adc-trigger-mode:
> > > +          const: 1
> > > +    then:
> > > +      required:
> > > +        - gpios
> > > +
> > > +additionalProperties: false
> > > +
> > > +examples:
> > > +  - |
> > > +    #include <dt-bindings/clock/r9a07g044-cpg.h>
> > > +    #include <dt-bindings/interrupt-controller/arm-gic.h>
> > > +
> > > +    adc: adc@10059000 {
> > > +      compatible = "renesas,r9a07g044-adc", "renesas,rzg2l-adc";
> > > +      reg = <0x10059000 0x400>;
> > > +      interrupts = <GIC_SPI 347 IRQ_TYPE_EDGE_RISING>;
> > > +      clocks = <&cpg CPG_MOD R9A07G044_ADC_ADCLK>,
> > > +               <&cpg CPG_MOD R9A07G044_ADC_PCLK>;
> > > +      clock-names = "adclk", "pclk";
> > > +      power-domains = <&cpg>;
> > > +      resets = <&cpg R9A07G044_ADC_PRESETN>,
> > > +               <&cpg R9A07G044_ADC_ADRST_N>;
> > > +      reset-names = "presetn", "adrst-n";
> > > +      #io-channel-cells = <1>;
> > > +      renesas-rzg2l,adc-trigger-mode = /bits/ 8 <0>;
> > > +      renesas-rzg2l,adc-channels = /bits/ 8 <0 1 2 3 4 5 6>;
> > > +    };  
> >

Lad, Prabhakar July 14, 2021, 6:24 p.m. UTC | #9

Hi Jonathan,

On Wed, Jul 14, 2021 at 1:39 PM Jonathan Cameron
<[e-mail]> wrote:
>
> On Wed, 14 Jul 2021 10:11:49 +0100
> "Lad, Prabhakar" <[e-mail]> wrote:
>
> > Hi Jonathan,
> >
> > Thank you for the review.
> >
> > On Sat, Jul 3, 2021 at 6:17 PM Jonathan Cameron <[e-mail]> wrote:
> > >
> > > On Tue, 29 Jun 2021 23:03:27 +0100
> > > Lad Prabhakar <[e-mail]> wrote:
> > >
> > > > Add binding documentation for Renesas RZ/G2L A/D converter block.
> > > >
> > > > Signed-off-by: Lad Prabhakar <[e-mail]>
> > > > Reviewed-by: Biju Das <[e-mail]>
> > > Hi,
> > >
> > > See inline
> > >
> > > Jonathan
> > >
> > > > ---
> > > >  .../bindings/iio/adc/renesas,rzg2l-adc.yaml   | 121 ++++++++++++++++++
> > > >  1 file changed, 121 insertions(+)
> > > >  create mode 100644 Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml
> > > >
> > > > diff --git a/Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml b/Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml
> > > > new file mode 100644
> > > > index 000000000000..db935d6d59eb
> > > > --- /dev/null
> > > > +++ b/Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml
> > > > @@ -0,0 +1,121 @@
> > > > +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> > > > +%YAML 1.2
> > > > +---
> > > > +$id: http://devicetree.org/schemas/iio/adc/renesas,rzg2l-adc.yaml#
> > > > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > > > +
> > > > +title: Renesas RZ/G2L ADC
> > > > +
> > > > +maintainers:
> > > > +  - Lad Prabhakar <[e-mail]>
> > > > +
> > > > +description: |
> > > > +  A/D Converter block is a successive approximation analog-to-digital converter
> > > > +  with a 12-bit accuracy. Up to eight analog input channels can be selected.
> > > > +  Conversions can be performed in single or repeat mode. Result of the ADC is
> > > > +  stored in a 32-bit data register corresponding to each channel.
> > > > +
> > > > +properties:
> > > > +  compatible:
> > > > +    oneOf:
> > > > +      - items:
> > > > +          - enum:
> > > > +              - renesas,r9a07g044-adc   # RZ/G2{L,LC}
> > > > +          - const: renesas,rzg2l-adc
> > > > +
> > > > +  reg:
> > > > +    maxItems: 1
> > > > +
> > > > +  interrupts:
> > > > +    maxItems: 1
> > > > +
> > > > +  clocks:
> > > > +    items:
> > > > +      - description: converter clock
> > > > +      - description: peripheral clock
> > > > +
> > > > +  clock-names:
> > > > +    items:
> > > > +      - const: adclk
> > > > +      - const: pclk
> > > > +
> > > > +  power-domains:
> > > > +    maxItems: 1
> > > > +
> > > > +  resets:
> > > > +    maxItems: 2
> > > > +
> > > > +  reset-names:
> > > > +    items:
> > > > +      - const: presetn
> > > > +      - const: adrst-n
> > > > +
> > > > +  renesas-rzg2l,adc-trigger-mode:
> > > > +    $ref: /schemas/types.yaml#/definitions/uint8
> > > > +    description: Trigger mode for A/D converter
> > > > +    enum:
> > > > +      - 0 # Software trigger mode (Defaults)
> > > > +      - 1 # Asynchronous trigger using ADC_TRG trigger input pin
> > > > +      - 2 # Synchronous trigger (Trigger from MTU3a/GPT)
> > >
> > > Is this a function of the board in some fashion?  If not it sounds like
> > > something that should be in control of userspace.  Normally we'd
> > > do that by having the driver register some iio_triggers and depending
> > > on which one is selected do the equivalent of what you have here.
> > >
> > Agreed for Asynchronous and Synchronous triggers. WRT Software trigger
> > should this be registered as a  iio_triggers too or read_raw()
> > callback (with IIO_CHAN_INFO_RAW case)  should be treated as Software
> > trigger?
> >
>
> Normally we'd use an external trigger to provide the software trigger
> (plus as you say sysfs reads will map to this functionality).
>
> Something like the sysfs trigger or the hrtimer one would get used, though
> also fine to use the dataready trigger from a different device (if you want
> approximately synced dta.
>
We can live with syfs reads for now for SW triggers. Coming back to HW
triggers I responded too quickly!. I am now trying to implement a gpio
based HW trigger i.e. to kick adc conversion start but I couldn't find
any drivers doing that. I looked at iio-trig-interrupt.c which
registers irq based triggers, so something similar needs to be
implemented in the adc driver? If that is the case the gpio has to be
passed via to DT and use gpio_to_irq to register the handler. Or is it
that I am missing something here ?

Cheers,
Prabhakar

> > > > +    default: 0
> > > > +
> > > > +  gpios:
> > > > +    description:
> > > > +      ADC_TRG trigger input pin
> > > > +    maxItems: 1
> > > Why is this mode useful?  I'm assuming the gpio write would take a register
> > > write and the software trigger mode also requires a register write.
> > >
> > Yes gpio write would take a register write.
> >
> > > Normally the reason for a pin like this is to support synchronising with
> > > external hardware.   If that's the case, we should call that out here.
> > > often the pin isn't even connected to a gpio in our control.
> > > (i.e. it's a trigger signal from some other device.)
> > >
> > So just setting the GPIO pin as input should do the trick.
>
> Probably the best plan if you actually care about people writing some
> trigger up to it that is otherwise invisible to the system.
>
> >
> > > > +
> > > > +  renesas-rzg2l,adc-channels:
> > > > +    $ref: /schemas/types.yaml#/definitions/uint8-array
> > > > +    description: Input channels available on platform
> > > > +    uniqueItems: true
> > > > +    minItems: 1
> > > > +    maxItems: 8
> > > > +    items:
> > > > +      enum: [0, 1, 2, 3, 4, 5, 6, 7]
> > >
> > > Is this a function of different devices (should have different compatibles)
> > > or of what is wired up.  If it's what is wired up, then how do you know which
> > Its channels which are wired, for example if channels 0-5 are wired up
> > the board dts would include the property "renesas-rzg2l,adc-channels =
> > /bits/ 8 <0 1 2 3 4 5>;"
> >
> > > subset of channels are connected?  We have the generic adc channel binding
> > > in iio/adc/adc.yaml for the case where we only want to expose those channels
> > > that are wired up.  It uses a node per channel.
> > >
> > Agreed will do that and drop the custom "renesas-rzg2l,adc-channels"
>
> Great,
>
> Jonathan
>
> >
> > Cheers,
> > Prabhakar
> > > > +
> > > > +  "#io-channel-cells":
> > > > +    const: 1
> > > > +
> > > > +required:
> > > > +  - compatible
> > > > +  - reg
> > > > +  - interrupts
> > > > +  - clocks
> > > > +  - clock-names
> > > > +  - power-domains
> > > > +  - resets
> > > > +  - reset-names
> > > > +  - renesas-rzg2l,adc-channels
> > > > +  - "#io-channel-cells"
> > > > +
> > > > +allOf:
> > > > +  - if:
> > > > +      properties:
> > > > +        renesas-rzg2l,adc-trigger-mode:
> > > > +          const: 1
> > > > +    then:
> > > > +      required:
> > > > +        - gpios
> > > > +
> > > > +additionalProperties: false
> > > > +
> > > > +examples:
> > > > +  - |
> > > > +    #include <dt-bindings/clock/r9a07g044-cpg.h>
> > > > +    #include <dt-bindings/interrupt-controller/arm-gic.h>
> > > > +
> > > > +    adc: adc@10059000 {
> > > > +      compatible = "renesas,r9a07g044-adc", "renesas,rzg2l-adc";
> > > > +      reg = <0x10059000 0x400>;
> > > > +      interrupts = <GIC_SPI 347 IRQ_TYPE_EDGE_RISING>;
> > > > +      clocks = <&cpg CPG_MOD R9A07G044_ADC_ADCLK>,
> > > > +               <&cpg CPG_MOD R9A07G044_ADC_PCLK>;
> > > > +      clock-names = "adclk", "pclk";
> > > > +      power-domains = <&cpg>;
> > > > +      resets = <&cpg R9A07G044_ADC_PRESETN>,
> > > > +               <&cpg R9A07G044_ADC_ADRST_N>;
> > > > +      reset-names = "presetn", "adrst-n";
> > > > +      #io-channel-cells = <1>;
> > > > +      renesas-rzg2l,adc-trigger-mode = /bits/ 8 <0>;
> > > > +      renesas-rzg2l,adc-channels = /bits/ 8 <0 1 2 3 4 5 6>;
> > > > +    };
> > >
>

Jonathan Cameron July 15, 2021, 1:02 p.m. UTC | #10

On Wed, 14 Jul 2021 19:24:27 +0100
"Lad, Prabhakar" <[e-mail]> wrote:

> Hi Jonathan,
> 
> On Wed, Jul 14, 2021 at 1:39 PM Jonathan Cameron
> <[e-mail]> wrote:
> >
> > On Wed, 14 Jul 2021 10:11:49 +0100
> > "Lad, Prabhakar" <[e-mail]> wrote:
> >  
> > > Hi Jonathan,
> > >
> > > Thank you for the review.
> > >
> > > On Sat, Jul 3, 2021 at 6:17 PM Jonathan Cameron <[e-mail]> wrote:  
> > > >
> > > > On Tue, 29 Jun 2021 23:03:27 +0100
> > > > Lad Prabhakar <[e-mail]> wrote:
> > > >  
> > > > > Add binding documentation for Renesas RZ/G2L A/D converter block.
> > > > >
> > > > > Signed-off-by: Lad Prabhakar <[e-mail]>
> > > > > Reviewed-by: Biju Das <[e-mail]>  
> > > > Hi,
> > > >
> > > > See inline
> > > >
> > > > Jonathan
> > > >  
> > > > > ---
> > > > >  .../bindings/iio/adc/renesas,rzg2l-adc.yaml   | 121 ++++++++++++++++++
> > > > >  1 file changed, 121 insertions(+)
> > > > >  create mode 100644 Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml
> > > > >
> > > > > diff --git a/Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml b/Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml
> > > > > new file mode 100644
> > > > > index 000000000000..db935d6d59eb
> > > > > --- /dev/null
> > > > > +++ b/Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml
> > > > > @@ -0,0 +1,121 @@
> > > > > +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> > > > > +%YAML 1.2
> > > > > +---
> > > > > +$id: http://devicetree.org/schemas/iio/adc/renesas,rzg2l-adc.yaml#
> > > > > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > > > > +
> > > > > +title: Renesas RZ/G2L ADC
> > > > > +
> > > > > +maintainers:
> > > > > +  - Lad Prabhakar <[e-mail]>
> > > > > +
> > > > > +description: |
> > > > > +  A/D Converter block is a successive approximation analog-to-digital converter
> > > > > +  with a 12-bit accuracy. Up to eight analog input channels can be selected.
> > > > > +  Conversions can be performed in single or repeat mode. Result of the ADC is
> > > > > +  stored in a 32-bit data register corresponding to each channel.
> > > > > +
> > > > > +properties:
> > > > > +  compatible:
> > > > > +    oneOf:
> > > > > +      - items:
> > > > > +          - enum:
> > > > > +              - renesas,r9a07g044-adc   # RZ/G2{L,LC}
> > > > > +          - const: renesas,rzg2l-adc
> > > > > +
> > > > > +  reg:
> > > > > +    maxItems: 1
> > > > > +
> > > > > +  interrupts:
> > > > > +    maxItems: 1
> > > > > +
> > > > > +  clocks:
> > > > > +    items:
> > > > > +      - description: converter clock
> > > > > +      - description: peripheral clock
> > > > > +
> > > > > +  clock-names:
> > > > > +    items:
> > > > > +      - const: adclk
> > > > > +      - const: pclk
> > > > > +
> > > > > +  power-domains:
> > > > > +    maxItems: 1
> > > > > +
> > > > > +  resets:
> > > > > +    maxItems: 2
> > > > > +
> > > > > +  reset-names:
> > > > > +    items:
> > > > > +      - const: presetn
> > > > > +      - const: adrst-n
> > > > > +
> > > > > +  renesas-rzg2l,adc-trigger-mode:
> > > > > +    $ref: /schemas/types.yaml#/definitions/uint8
> > > > > +    description: Trigger mode for A/D converter
> > > > > +    enum:
> > > > > +      - 0 # Software trigger mode (Defaults)
> > > > > +      - 1 # Asynchronous trigger using ADC_TRG trigger input pin
> > > > > +      - 2 # Synchronous trigger (Trigger from MTU3a/GPT)  
> > > >
> > > > Is this a function of the board in some fashion?  If not it sounds like
> > > > something that should be in control of userspace.  Normally we'd
> > > > do that by having the driver register some iio_triggers and depending
> > > > on which one is selected do the equivalent of what you have here.
> > > >  
> > > Agreed for Asynchronous and Synchronous triggers. WRT Software trigger
> > > should this be registered as a  iio_triggers too or read_raw()
> > > callback (with IIO_CHAN_INFO_RAW case)  should be treated as Software
> > > trigger?
> > >  
> >
> > Normally we'd use an external trigger to provide the software trigger
> > (plus as you say sysfs reads will map to this functionality).
> >
> > Something like the sysfs trigger or the hrtimer one would get used, though
> > also fine to use the dataready trigger from a different device (if you want
> > approximately synced dta.
> >  
> We can live with syfs reads for now for SW triggers. Coming back to HW
> triggers I responded too quickly!. I am now trying to implement a gpio
> based HW trigger i.e. to kick adc conversion start but I couldn't find
> any drivers doing that. I looked at iio-trig-interrupt.c which
> registers irq based triggers, so something similar needs to be
> implemented in the adc driver? If that is the case the gpio has to be
> passed via to DT and use gpio_to_irq to register the handler. Or is it
> that I am missing something here ?

Ok, I'm not really following the usecase for this. Is the thought that you'll
get lower latency / jitter triggering via a gpio rather than using a
bus write to the device (though on an integrated ADC I can't see why that would
be the case)?

If so, then what is actually setting the gpio?  Something is ultimately
acting as the real trigger.  A common model would be an hrtimer trigger
for example.   If you then want to wire the driver up to capture on demand
using the gpio (to reduce latency) that's fine, but the gpio itself is
never a trigger in the sense of an IIO trigger (rather than a trigger
to the ADC itself).  In that case, have the trigger handler set the
the gpio and wait for data capture to finish.  Quite a few drivers
do this as some devices can only start sampling on an external pin being
set.  E.g. adc/ad7606.c 

The iio-trig-interrupt is about using an external interrupt to trigger
a capture initialized by a register write or similar, it's not a direct
hardware capture signal.

Jonathan

> 
> Cheers,
> Prabhakar
> 
> > > > > +    default: 0
> > > > > +
> > > > > +  gpios:
> > > > > +    description:
> > > > > +      ADC_TRG trigger input pin
> > > > > +    maxItems: 1  
> > > > Why is this mode useful?  I'm assuming the gpio write would take a register
> > > > write and the software trigger mode also requires a register write.
> > > >  
> > > Yes gpio write would take a register write.
> > >  
> > > > Normally the reason for a pin like this is to support synchronising with
> > > > external hardware.   If that's the case, we should call that out here.
> > > > often the pin isn't even connected to a gpio in our control.
> > > > (i.e. it's a trigger signal from some other device.)
> > > >  
> > > So just setting the GPIO pin as input should do the trick.  
> >
> > Probably the best plan if you actually care about people writing some
> > trigger up to it that is otherwise invisible to the system.
> >  
> > >  
> > > > > +
> > > > > +  renesas-rzg2l,adc-channels:
> > > > > +    $ref: /schemas/types.yaml#/definitions/uint8-array
> > > > > +    description: Input channels available on platform
> > > > > +    uniqueItems: true
> > > > > +    minItems: 1
> > > > > +    maxItems: 8
> > > > > +    items:
> > > > > +      enum: [0, 1, 2, 3, 4, 5, 6, 7]  
> > > >
> > > > Is this a function of different devices (should have different compatibles)
> > > > or of what is wired up.  If it's what is wired up, then how do you know which  
> > > Its channels which are wired, for example if channels 0-5 are wired up
> > > the board dts would include the property "renesas-rzg2l,adc-channels =
> > > /bits/ 8 <0 1 2 3 4 5>;"
> > >  
> > > > subset of channels are connected?  We have the generic adc channel binding
> > > > in iio/adc/adc.yaml for the case where we only want to expose those channels
> > > > that are wired up.  It uses a node per channel.
> > > >  
> > > Agreed will do that and drop the custom "renesas-rzg2l,adc-channels"  
> >
> > Great,
> >
> > Jonathan
> >  
> > >
> > > Cheers,
> > > Prabhakar  
> > > > > +
> > > > > +  "#io-channel-cells":
> > > > > +    const: 1
> > > > > +
> > > > > +required:
> > > > > +  - compatible
> > > > > +  - reg
> > > > > +  - interrupts
> > > > > +  - clocks
> > > > > +  - clock-names
> > > > > +  - power-domains
> > > > > +  - resets
> > > > > +  - reset-names
> > > > > +  - renesas-rzg2l,adc-channels
> > > > > +  - "#io-channel-cells"
> > > > > +
> > > > > +allOf:
> > > > > +  - if:
> > > > > +      properties:
> > > > > +        renesas-rzg2l,adc-trigger-mode:
> > > > > +          const: 1
> > > > > +    then:
> > > > > +      required:
> > > > > +        - gpios
> > > > > +
> > > > > +additionalProperties: false
> > > > > +
> > > > > +examples:
> > > > > +  - |
> > > > > +    #include <dt-bindings/clock/r9a07g044-cpg.h>
> > > > > +    #include <dt-bindings/interrupt-controller/arm-gic.h>
> > > > > +
> > > > > +    adc: adc@10059000 {
> > > > > +      compatible = "renesas,r9a07g044-adc", "renesas,rzg2l-adc";
> > > > > +      reg = <0x10059000 0x400>;
> > > > > +      interrupts = <GIC_SPI 347 IRQ_TYPE_EDGE_RISING>;
> > > > > +      clocks = <&cpg CPG_MOD R9A07G044_ADC_ADCLK>,
> > > > > +               <&cpg CPG_MOD R9A07G044_ADC_PCLK>;
> > > > > +      clock-names = "adclk", "pclk";
> > > > > +      power-domains = <&cpg>;
> > > > > +      resets = <&cpg R9A07G044_ADC_PRESETN>,
> > > > > +               <&cpg R9A07G044_ADC_ADRST_N>;
> > > > > +      reset-names = "presetn", "adrst-n";
> > > > > +      #io-channel-cells = <1>;
> > > > > +      renesas-rzg2l,adc-trigger-mode = /bits/ 8 <0>;
> > > > > +      renesas-rzg2l,adc-channels = /bits/ 8 <0 1 2 3 4 5 6>;
> > > > > +    };  
> > > >  
> >

Lad, Prabhakar July 16, 2021, 3:45 p.m. UTC | #11

Hi Jonathan,

On Thu, Jul 15, 2021 at 2:02 PM Jonathan Cameron
<[e-mail]> wrote:
>
> On Wed, 14 Jul 2021 19:24:27 +0100
> "Lad, Prabhakar" <[e-mail]> wrote:
>
> > Hi Jonathan,
> >
> > On Wed, Jul 14, 2021 at 1:39 PM Jonathan Cameron
> > <[e-mail]> wrote:
> > >
> > > On Wed, 14 Jul 2021 10:11:49 +0100
> > > "Lad, Prabhakar" <[e-mail]> wrote:
> > >
> > > > Hi Jonathan,
> > > >
> > > > Thank you for the review.
> > > >
> > > > On Sat, Jul 3, 2021 at 6:17 PM Jonathan Cameron <[e-mail]> wrote:
> > > > >
> > > > > On Tue, 29 Jun 2021 23:03:27 +0100
> > > > > Lad Prabhakar <[e-mail]> wrote:
> > > > >
> > > > > > Add binding documentation for Renesas RZ/G2L A/D converter block.
> > > > > >
> > > > > > Signed-off-by: Lad Prabhakar <[e-mail]>
> > > > > > Reviewed-by: Biju Das <[e-mail]>
> > > > > Hi,
> > > > >
> > > > > See inline
> > > > >
> > > > > Jonathan
> > > > >
> > > > > > ---
> > > > > >  .../bindings/iio/adc/renesas,rzg2l-adc.yaml   | 121 ++++++++++++++++++
> > > > > >  1 file changed, 121 insertions(+)
> > > > > >  create mode 100644 Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml
> > > > > >
> > > > > > diff --git a/Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml b/Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml
> > > > > > new file mode 100644
> > > > > > index 000000000000..db935d6d59eb
> > > > > > --- /dev/null
> > > > > > +++ b/Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml
> > > > > > @@ -0,0 +1,121 @@
> > > > > > +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> > > > > > +%YAML 1.2
> > > > > > +---
> > > > > > +$id: http://devicetree.org/schemas/iio/adc/renesas,rzg2l-adc.yaml#
> > > > > > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > > > > > +
> > > > > > +title: Renesas RZ/G2L ADC
> > > > > > +
> > > > > > +maintainers:
> > > > > > +  - Lad Prabhakar <[e-mail]>
> > > > > > +
> > > > > > +description: |
> > > > > > +  A/D Converter block is a successive approximation analog-to-digital converter
> > > > > > +  with a 12-bit accuracy. Up to eight analog input channels can be selected.
> > > > > > +  Conversions can be performed in single or repeat mode. Result of the ADC is
> > > > > > +  stored in a 32-bit data register corresponding to each channel.
> > > > > > +
> > > > > > +properties:
> > > > > > +  compatible:
> > > > > > +    oneOf:
> > > > > > +      - items:
> > > > > > +          - enum:
> > > > > > +              - renesas,r9a07g044-adc   # RZ/G2{L,LC}
> > > > > > +          - const: renesas,rzg2l-adc
> > > > > > +
> > > > > > +  reg:
> > > > > > +    maxItems: 1
> > > > > > +
> > > > > > +  interrupts:
> > > > > > +    maxItems: 1
> > > > > > +
> > > > > > +  clocks:
> > > > > > +    items:
> > > > > > +      - description: converter clock
> > > > > > +      - description: peripheral clock
> > > > > > +
> > > > > > +  clock-names:
> > > > > > +    items:
> > > > > > +      - const: adclk
> > > > > > +      - const: pclk
> > > > > > +
> > > > > > +  power-domains:
> > > > > > +    maxItems: 1
> > > > > > +
> > > > > > +  resets:
> > > > > > +    maxItems: 2
> > > > > > +
> > > > > > +  reset-names:
> > > > > > +    items:
> > > > > > +      - const: presetn
> > > > > > +      - const: adrst-n
> > > > > > +
> > > > > > +  renesas-rzg2l,adc-trigger-mode:
> > > > > > +    $ref: /schemas/types.yaml#/definitions/uint8
> > > > > > +    description: Trigger mode for A/D converter
> > > > > > +    enum:
> > > > > > +      - 0 # Software trigger mode (Defaults)
> > > > > > +      - 1 # Asynchronous trigger using ADC_TRG trigger input pin
> > > > > > +      - 2 # Synchronous trigger (Trigger from MTU3a/GPT)
> > > > >
> > > > > Is this a function of the board in some fashion?  If not it sounds like
> > > > > something that should be in control of userspace.  Normally we'd
> > > > > do that by having the driver register some iio_triggers and depending
> > > > > on which one is selected do the equivalent of what you have here.
> > > > >
> > > > Agreed for Asynchronous and Synchronous triggers. WRT Software trigger
> > > > should this be registered as a  iio_triggers too or read_raw()
> > > > callback (with IIO_CHAN_INFO_RAW case)  should be treated as Software
> > > > trigger?
> > > >
> > >
> > > Normally we'd use an external trigger to provide the software trigger
> > > (plus as you say sysfs reads will map to this functionality).
> > >
> > > Something like the sysfs trigger or the hrtimer one would get used, though
> > > also fine to use the dataready trigger from a different device (if you want
> > > approximately synced dta.
> > >
> > We can live with syfs reads for now for SW triggers. Coming back to HW
> > triggers I responded too quickly!. I am now trying to implement a gpio
> > based HW trigger i.e. to kick adc conversion start but I couldn't find
> > any drivers doing that. I looked at iio-trig-interrupt.c which
> > registers irq based triggers, so something similar needs to be
> > implemented in the adc driver? If that is the case the gpio has to be
> > passed via to DT and use gpio_to_irq to register the handler. Or is it
> > that I am missing something here ?
>
> Ok, I'm not really following the usecase for this. Is the thought that you'll
> get lower latency / jitter triggering via a gpio rather than using a
> bus write to the device (though on an integrated ADC I can't see why that would
> be the case)?
>
Sorry for the confusion. ADC_TRIG I was referring to automatically
triggers  ADC conversion depending on the edges (whatever its is
configured to). The external triggers can be handled by iio_trigger as
you pointed out earlier!

> If so, then what is actually setting the gpio?  Something is ultimately
> acting as the real trigger.  A common model would be an hrtimer trigger
> for example.   If you then want to wire the driver up to capture on demand
> using the gpio (to reduce latency) that's fine, but the gpio itself is
> never a trigger in the sense of an IIO trigger (rather than a trigger
> to the ADC itself).  In that case, have the trigger handler set the
> the gpio and wait for data capture to finish.  Quite a few drivers
> do this as some devices can only start sampling on an external pin being
> set.  E.g. adc/ad7606.c
>
> The iio-trig-interrupt is about using an external interrupt to trigger
> a capture initialized by a register write or similar, it's not a direct
> hardware capture signal.
>
thanks for the explanation, I realized it now.

Cheers,
Prabhakar

Patch

diff --git a/Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml b/Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml
new file mode 100644
index 000000000000..db935d6d59eb
--- /dev/null
+++ b/Documentation/devicetree/bindings/iio/adc/renesas,rzg2l-adc.yaml
@@ -0,0 +1,121 @@ 
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/iio/adc/renesas,rzg2l-adc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Renesas RZ/G2L ADC
+
+maintainers:
+  - Lad Prabhakar <[e-mail]>
+
+description: |
+  A/D Converter block is a successive approximation analog-to-digital converter
+  with a 12-bit accuracy. Up to eight analog input channels can be selected.
+  Conversions can be performed in single or repeat mode. Result of the ADC is
+  stored in a 32-bit data register corresponding to each channel.
+
+properties:
+  compatible:
+    oneOf:
+      - items:
+          - enum:
+              - renesas,r9a07g044-adc   # RZ/G2{L,LC}
+          - const: renesas,rzg2l-adc
+
+  reg:
+    maxItems: 1
+
+  interrupts:
+    maxItems: 1
+
+  clocks:
+    items:
+      - description: converter clock
+      - description: peripheral clock
+
+  clock-names:
+    items:
+      - const: adclk
+      - const: pclk
+
+  power-domains:
+    maxItems: 1
+
+  resets:
+    maxItems: 2
+
+  reset-names:
+    items:
+      - const: presetn
+      - const: adrst-n
+
+  renesas-rzg2l,adc-trigger-mode:
+    $ref: /schemas/types.yaml#/definitions/uint8
+    description: Trigger mode for A/D converter
+    enum:
+      - 0 # Software trigger mode (Defaults)
+      - 1 # Asynchronous trigger using ADC_TRG trigger input pin
+      - 2 # Synchronous trigger (Trigger from MTU3a/GPT)
+    default: 0
+
+  gpios:
+    description:
+      ADC_TRG trigger input pin
+    maxItems: 1
+
+  renesas-rzg2l,adc-channels:
+    $ref: /schemas/types.yaml#/definitions/uint8-array
+    description: Input channels available on platform
+    uniqueItems: true
+    minItems: 1
+    maxItems: 8
+    items:
+      enum: [0, 1, 2, 3, 4, 5, 6, 7]
+
+  "#io-channel-cells":
+    const: 1
+
+required:
+  - compatible
+  - reg
+  - interrupts
+  - clocks
+  - clock-names
+  - power-domains
+  - resets
+  - reset-names
+  - renesas-rzg2l,adc-channels
+  - "#io-channel-cells"
+
+allOf:
+  - if:
+      properties:
+        renesas-rzg2l,adc-trigger-mode:
+          const: 1
+    then:
+      required:
+        - gpios
+
+additionalProperties: false
+
+examples:
+  - |
+    #include <dt-bindings/clock/r9a07g044-cpg.h>
+    #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+    adc: adc@10059000 {
+      compatible = "renesas,r9a07g044-adc", "renesas,rzg2l-adc";
+      reg = <0x10059000 0x400>;
+      interrupts = <GIC_SPI 347 IRQ_TYPE_EDGE_RISING>;
+      clocks = <&cpg CPG_MOD R9A07G044_ADC_ADCLK>,
+               <&cpg CPG_MOD R9A07G044_ADC_PCLK>;
+      clock-names = "adclk", "pclk";
+      power-domains = <&cpg>;
+      resets = <&cpg R9A07G044_ADC_PRESETN>,
+               <&cpg R9A07G044_ADC_ADRST_N>;
+      reset-names = "presetn", "adrst-n";
+      #io-channel-cells = <1>;
+      renesas-rzg2l,adc-trigger-mode = /bits/ 8 <0>;
+      renesas-rzg2l,adc-channels = /bits/ 8 <0 1 2 3 4 5 6>;
+    };