Re: [PATCH v8 1/6] dt-bindings: iio/adc: Convert ingenic-adc docs to YAML.

[Jonathan Cameron <jic23@kernel.org>]

On Thu,  9 Jul 2020 17:21:55 +0200
Artur Rojek <contact@artur-rojek.eu> wrote:

> Convert the textual documentation of Device Tree bindings for the
> Ingenic JZ47xx SoCs ADC controller to YAML.
> 
> The `interrupts` property is now explicitly listed and marked as
> required. While missing from the previous textual documentation, this
> property has been used with all the boards which probe this driver.
> 
> Signed-off-by: Artur Rojek <contact@artur-rojek.eu>
> Tested-by: Paul Cercueil <paul@crapouillou.net>
> Reviewed-by: Rob Herring <robh@kernel.org>

Given this is a good change on it's own. I'll apply it before even
reading the rest of the series.  If we do need to go to a v9 at least
it'll be shorter ;) 

Applied to the togreg branch of iio.git and pushed out as testing
for the autobuilders to poke at it.

Thanks,

Jonathan

> ---
> 
>  Changes:
> 
>  v6: new patch
> 
>  v7: - specify `maxItems: 1` for single entry properties
>      - get rid of redundant descriptions of said properties
> 
>  v8: no change
> 
>  .../bindings/iio/adc/ingenic,adc.txt          | 49 -------------
>  .../bindings/iio/adc/ingenic,adc.yaml         | 71 +++++++++++++++++++
>  2 files changed, 71 insertions(+), 49 deletions(-)
>  delete mode 100644 Documentation/devicetree/bindings/iio/adc/ingenic,adc.txt
>  create mode 100644 Documentation/devicetree/bindings/iio/adc/ingenic,adc.yaml
> 
> diff --git a/Documentation/devicetree/bindings/iio/adc/ingenic,adc.txt b/Documentation/devicetree/bindings/iio/adc/ingenic,adc.txt
> deleted file mode 100644
> index cd9048cf9dcf..000000000000
> --- a/Documentation/devicetree/bindings/iio/adc/ingenic,adc.txt
> +++ /dev/null
> @@ -1,49 +0,0 @@
> -* Ingenic JZ47xx ADC controller IIO bindings
> -
> -Required properties:
> -
> -- compatible: Should be one of:
> -  * ingenic,jz4725b-adc
> -  * ingenic,jz4740-adc
> -  * ingenic,jz4770-adc
> -- reg: ADC controller registers location and length.
> -- clocks: phandle to the SoC's ADC clock.
> -- clock-names: Must be set to "adc".
> -- #io-channel-cells: Must be set to <1> to indicate channels are selected
> -  by index.
> -
> -ADC clients must use the format described in iio-bindings.txt, giving
> -a phandle and IIO specifier pair ("io-channels") to the ADC controller.
> -
> -Example:
> -
> -#include <dt-bindings/iio/adc/ingenic,adc.h>
> -
> -adc: adc@10070000 {
> -	compatible = "ingenic,jz4740-adc";
> -	#io-channel-cells = <1>;
> -
> -	reg = <0x10070000 0x30>;
> -
> -	clocks = <&cgu JZ4740_CLK_ADC>;
> -	clock-names = "adc";
> -
> -	interrupt-parent = <&intc>;
> -	interrupts = <18>;
> -};
> -
> -adc-keys {
> -	...
> -	compatible = "adc-keys";
> -	io-channels = <&adc INGENIC_ADC_AUX>;
> -	io-channel-names = "buttons";
> -	...
> -};
> -
> -battery {
> -	...
> -	compatible = "ingenic,jz4740-battery";
> -	io-channels = <&adc INGENIC_ADC_BATTERY>;
> -	io-channel-names = "battery";
> -	...
> -};
> diff --git a/Documentation/devicetree/bindings/iio/adc/ingenic,adc.yaml b/Documentation/devicetree/bindings/iio/adc/ingenic,adc.yaml
> new file mode 100644
> index 000000000000..9f414dbdae86
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/iio/adc/ingenic,adc.yaml
> @@ -0,0 +1,71 @@
> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
> +# Copyright 2019-2020 Artur Rojek
> +%YAML 1.2
> +---
> +$id: "http://devicetree.org/schemas/iio/adc/ingenic,adc.yaml#"
> +$schema: "http://devicetree.org/meta-schemas/core.yaml#"
> +
> +title: Ingenic JZ47xx ADC controller IIO bindings
> +
> +maintainers:
> +  - Artur Rojek <contact@artur-rojek.eu>
> +
> +description: >
> +  Industrial I/O subsystem bindings for ADC controller found in
> +  Ingenic JZ47xx SoCs.
> +
> +  ADC clients must use the format described in iio-bindings.txt, giving
> +  a phandle and IIO specifier pair ("io-channels") to the ADC controller.
> +
> +properties:
> +  compatible:
> +    enum:
> +      - ingenic,jz4725b-adc
> +      - ingenic,jz4740-adc
> +      - ingenic,jz4770-adc
> +
> +  '#io-channel-cells':
> +    const: 1
> +    description:
> +      Must be set to <1> to indicate channels are selected by index.
> +
> +  reg:
> +    maxItems: 1
> +
> +  clocks:
> +    maxItems: 1
> +
> +  clock-names:
> +    items:
> +      - const: adc
> +
> +  interrupts:
> +    maxItems: 1
> +
> +required:
> +  - compatible
> +  - '#io-channel-cells'
> +  - reg
> +  - clocks
> +  - clock-names
> +  - interrupts
> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    #include <dt-bindings/clock/jz4740-cgu.h>
> +    #include <dt-bindings/iio/adc/ingenic,adc.h>
> +
> +    adc@10070000 {
> +            compatible = "ingenic,jz4740-adc";
> +            #io-channel-cells = <1>;
> +
> +            reg = <0x10070000 0x30>;
> +
> +            clocks = <&cgu JZ4740_CLK_ADC>;
> +            clock-names = "adc";
> +
> +            interrupt-parent = <&intc>;
> +            interrupts = <18>;
> +    };