Re: [PATCH v1 1/4] dt-bindings: ata: tegra: Convert binding documentation to YAML

[Rob Herring]

On Thu, Nov 05, 2020 at 06:16:05PM -0800, Sowjanya Komatineni wrote:
> This patch converts text based dt-binding document to YAML based
> dt-binding document.
> 
> Signed-off-by: Sowjanya Komatineni <skomatineni@xxxxxxxxxx>
> ---
>  .../devicetree/bindings/ata/nvidia,tegra-ahci.yaml | 152 +++++++++++++++++++++
>  .../bindings/ata/nvidia,tegra124-ahci.txt          |  44 ------
>  2 files changed, 152 insertions(+), 44 deletions(-)
>  create mode 100644 Documentation/devicetree/bindings/ata/nvidia,tegra-ahci.yaml
>  delete mode 100644 Documentation/devicetree/bindings/ata/nvidia,tegra124-ahci.txt
> 
> diff --git a/Documentation/devicetree/bindings/ata/nvidia,tegra-ahci.yaml b/Documentation/devicetree/bindings/ata/nvidia,tegra-ahci.yaml
> new file mode 100644
> index 0000000..ac20f6e
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/ata/nvidia,tegra-ahci.yaml
> @@ -0,0 +1,152 @@
> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/ata/nvidia,tegra-ahci.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Tegra AHCI SATA Controller
> +
> +maintainers:
> +  - Thierry Reding <thierry.reding@xxxxxxxxx>
> +  - Jonathan Hunter <jonathanh@xxxxxxxxxx>
> +
> +properties:
> +  compatible:
> +    enum:
> +      - nvidia,tegra124-ahci
> +      - nvidia,tegra132-ahci
> +      - nvidia,tegra210-ahci
> +
> +  reg:
> +    minItems: 2
> +    maxItems: 3
> +    items:
> +      - description: AHCI registers
> +      - description: SATA configuration and IPFS registers
> +      - description: SATA AUX registers
> +
> +  interrupts:
> +    maxItems: 1
> +
> +  clock-names:
> +    maxItems: 2

Don't need maxItems, implied by the size of 'items'.

> +    items:
> +      - const: sata
> +      - const: sata-oob
> +
> +  clocks:
> +    maxItems: 2
> +    description:
> +      Must contain an entry for each entry in clock-names.
> +      See ../clocks/clock-bindings.txt for details.

Drop 'description'. Says nothing specific to this binding.

> +
> +  reset-names:
> +    maxItems: 3

Need to define what each reset is.

> +
> +  resets:
> +    maxItems: 3
> +    description:
> +      Must contain an entry for each entry in reset-names.
> +      See ../reset/reset.txt for details.

Drop 'description'. Says nothing specific to this binding.

> +
> +  phy-names:
> +    items:
> +      - const: sata-0
> +
> +  phys:
> +    maxItems: 1
> +    description:
> +      Must contain an entry for each entry in phy-names.
> +      See ../phy/phy-bindings.txt for details.

Drop 'description'. Says nothing specific to this binding.

> +
> +  hvdd-supply:
> +    description: SATA HVDD regulator supply.
> +
> +  vddio-supply:
> +    description: SATA VDDIO regulator supply.
> +
> +  avdd-supply:
> +    description: SATA AVDD regulator supply.
> +
> +  target-5v-supply:
> +    description: SATA 5V power regulator supply.
> +
> +  target-12v-supply:
> +    description: SATA 12V power regulator supply.
> +
> +required:
> +  - compatible
> +  - reg
> +  - interrupts
> +  - clock-names
> +  - clocks
> +  - reset-names
> +  - resets
> +
> +allOf:
> +  - if:
> +      properties:
> +        compatible:
> +          contains:
> +            enum:
> +              - nvidia,tegra124-ahci
> +              - nvidia,tegra132-ahci
> +    then:
> +      properties:
> +        reg:
> +          maxItems: 2

> +        reset-names:
> +          minItems: 3
> +          items:
> +            - const: sata
> +            - const: sata-oob
> +            - const: sata-cold
> +        resets:
> +          minItems: 3

This doesn't need to be conditional.

> +      required:
> +        - phys
> +        - phy-names
> +        - hvdd-supply
> +        - vddio-supply
> +        - avdd-supply
> +
> +  - if:
> +      properties:
> +        compatible:
> +          contains:
> +            enum:
> +              - nvidia,tegra210-ahci
> +    then:
> +      properties:
> +        reg:
> +          minItems: 3
> +        reset-names:
> +          minItems: 3
> +          items:
> +            - const: sata
> +            - const: sata-oob
> +            - const: sata-cold
> +        resets:
> +          minItems: 3
> +
> +additionalProperties: true
> +
> +examples:
> +  - |
> +    #include <dt-bindings/clock/tegra210-car.h>
> +    #include <dt-bindings/reset/tegra210-car.h>
> +
> +    sata@70020000 {
> +            compatible = "nvidia,tegra210-ahci";
> +            reg = <0x0 0x70027000 0x0 0x00002000>, /* AHCI */
> +                  <0x0 0x70020000 0x0 0x00007000>, /* SATA */
> +                  <0x0 0x70001100 0x0 0x00010000>; /* SATA AUX */
> +            interrupts = <GIC_SPI 23 IRQ_TYPE_LEVEL_HIGH>;
> +            clocks = <&tegra_car TEGRA210_CLK_SATA>,
> +                     <&tegra_car TEGRA210_CLK_SATA_OOB>;
> +            clock-names = "sata", "sata-oob";
> +            resets = <&tegra_car 124>,
> +                     <&tegra_car 123>,
> +                     <&tegra_car 129>;
> +            reset-names = "sata", "sata-oob", "sata-cold";
> +    };
> diff --git a/Documentation/devicetree/bindings/ata/nvidia,tegra124-ahci.txt b/Documentation/devicetree/bindings/ata/nvidia,tegra124-ahci.txt
> deleted file mode 100644
> index 12ab2f7..0000000
> --- a/Documentation/devicetree/bindings/ata/nvidia,tegra124-ahci.txt
> +++ /dev/null
> @@ -1,44 +0,0 @@
> -Tegra SoC SATA AHCI controller
> -
> -Required properties :
> -- compatible : Must be one of:
> -  - Tegra124 : "nvidia,tegra124-ahci"
> -  - Tegra132 : "nvidia,tegra132-ahci", "nvidia,tegra124-ahci"
> -  - Tegra210 : "nvidia,tegra210-ahci"
> -- reg : Should contain 2 entries:
> -  - AHCI register set (SATA BAR5)
> -  - SATA register set
> -- interrupts : Defines the interrupt used by SATA
> -- clocks : Must contain an entry for each entry in clock-names.
> -  See ../clocks/clock-bindings.txt for details.
> -- clock-names : Must include the following entries:
> -  - sata
> -  - sata-oob
> -- resets : Must contain an entry for each entry in reset-names.
> -  See ../reset/reset.txt for details.
> -- reset-names : Must include the following entries:
> -  - sata
> -  - sata-oob
> -  - sata-cold
> -- phys : Must contain an entry for each entry in phy-names.
> -  See ../phy/phy-bindings.txt for details.
> -- phy-names : Must include the following entries:
> -  - For Tegra124 and Tegra132:
> -    - sata-phy : XUSB PADCTL SATA PHY
> -- For Tegra124 and Tegra132:
> -  - hvdd-supply : Defines the SATA HVDD regulator
> -  - vddio-supply : Defines the SATA VDDIO regulator
> -  - avdd-supply : Defines the SATA AVDD regulator
> -  - target-5v-supply : Defines the SATA 5V power regulator
> -  - target-12v-supply : Defines the SATA 12V power regulator
> -
> -Optional properties:
> -- reg :
> -  - AUX register set
> -- clock-names :
> -  - cml1 :
> -    cml1 clock should be defined here if the PHY driver
> -    doesn't manage them. If it does, they should not be.
> -- phy-names :
> -  - For T210:
> -    - sata-phy
> -- 
> 2.7.4
>