diff mbox series

[4/4] dt-bindings: bus: Convert ACONNECT doc to json-schema

Message ID 1604571846-14037-5-git-send-email-spujar@nvidia.com (mailing list archive)
State Changes Requested
Headers show
Series [1/4] arm64: tegra: Rename ADMA device nodes for Tegra210 | expand

Commit Message

Sameer Pujar Nov. 5, 2020, 10:24 a.m. UTC 
Move ACONNECT documentation to YAML format.

Signed-off-by: Sameer Pujar <spujar@nvidia.com>
---
 .../bindings/bus/nvidia,tegra210-aconnect.txt      | 44 -----------
 .../bindings/bus/nvidia,tegra210-aconnect.yaml     | 86 ++++++++++++++++++++++
 2 files changed, 86 insertions(+), 44 deletions(-)
 delete mode 100644 Documentation/devicetree/bindings/bus/nvidia,tegra210-aconnect.txt
 create mode 100644 Documentation/devicetree/bindings/bus/nvidia,tegra210-aconnect.yaml

Comments

Rob Herring (Arm) Nov. 5, 2020, 7:05 p.m. UTC | #1 
On Thu, Nov 05, 2020 at 03:54:06PM +0530, Sameer Pujar wrote:
> Move ACONNECT documentation to YAML format.
> 
> Signed-off-by: Sameer Pujar <spujar@nvidia.com>
> ---
>  .../bindings/bus/nvidia,tegra210-aconnect.txt      | 44 -----------
>  .../bindings/bus/nvidia,tegra210-aconnect.yaml     | 86 ++++++++++++++++++++++
>  2 files changed, 86 insertions(+), 44 deletions(-)
>  delete mode 100644 Documentation/devicetree/bindings/bus/nvidia,tegra210-aconnect.txt
>  create mode 100644 Documentation/devicetree/bindings/bus/nvidia,tegra210-aconnect.yaml
> 
> diff --git a/Documentation/devicetree/bindings/bus/nvidia,tegra210-aconnect.txt b/Documentation/devicetree/bindings/bus/nvidia,tegra210-aconnect.txt
> deleted file mode 100644
> index 3108d03..0000000
> --- a/Documentation/devicetree/bindings/bus/nvidia,tegra210-aconnect.txt
> +++ /dev/null
> @@ -1,44 +0,0 @@
> -NVIDIA Tegra ACONNECT Bus
> -
> -The Tegra ACONNECT bus is an AXI switch which is used to connnect various
> -components inside the Audio Processing Engine (APE). All CPU accesses to
> -the APE subsystem go through the ACONNECT via an APB to AXI wrapper.
> -
> -Required properties:
> -- compatible: Must be "nvidia,tegra210-aconnect".
> -- clocks: Must contain the entries for the APE clock (TEGRA210_CLK_APE),
> -  and APE interface clock (TEGRA210_CLK_APB2APE).
> -- clock-names: Must contain the names "ape" and "apb2ape" for the corresponding
> -  'clocks' entries.
> -- power-domains: Must contain a phandle that points to the audio powergate
> -  (namely 'aud') for Tegra210.
> -- #address-cells: The number of cells used to represent physical base addresses
> -  in the aconnect address space. Should be 1.
> -- #size-cells: The number of cells used to represent the size of an address
> -  range in the aconnect address space. Should be 1.
> -- ranges: Mapping of the aconnect address space to the CPU address space.
> -
> -All devices accessed via the ACONNNECT are described by child-nodes.
> -
> -Example:
> -
> -	aconnect@702c0000 {
> -		compatible = "nvidia,tegra210-aconnect";
> -		clocks = <&tegra_car TEGRA210_CLK_APE>,
> -			 <&tegra_car TEGRA210_CLK_APB2APE>;
> -		clock-names = "ape", "apb2ape";
> -		power-domains = <&pd_audio>;
> -
> -		#address-cells = <1>;
> -		#size-cells = <1>;
> -		ranges = <0x702c0000 0x0 0x702c0000 0x00040000>;
> -
> -
> -		child1 {
> -			...
> -		};
> -
> -		child2 {
> -			...
> -		};
> -	};
> diff --git a/Documentation/devicetree/bindings/bus/nvidia,tegra210-aconnect.yaml b/Documentation/devicetree/bindings/bus/nvidia,tegra210-aconnect.yaml
> new file mode 100644
> index 0000000..f0161bc
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/bus/nvidia,tegra210-aconnect.yaml
> @@ -0,0 +1,86 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/bus/nvidia,tegra210-aconnect.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: NVIDIA Tegra ACONNECT Bus
> +
> +description: |
> +  The Tegra ACONNECT bus is an AXI switch which is used to connnect various
> +  components inside the Audio Processing Engine (APE). All CPU accesses to
> +  the APE subsystem go through the ACONNECT via an APB to AXI wrapper. All
> +  devices accessed via the ACONNNECT are described by child-nodes.
> +
> +maintainers:
> +  - Jon Hunter <jonathanh@nvidia.com>
> +
> +properties:
> +  compatible:
> +    oneOf:
> +      - const: nvidia,tegra210-aconnect
> +      - items:
> +          - enum:
> +              - nvidia,tegra186-aconnect
> +              - nvidia,tegra194-aconnect
> +          - const: nvidia,tegra210-aconnect
> +
> +  clocks:
> +    items:
> +      - description: Must contain the entry for APE clock
> +      - description: Must contain the entry for APE interface clock
> +
> +  clock-names:
> +    items:
> +      - const: ape
> +      - const: apb2ape
> +
> +  power-domains:
> +    maxItems: 1
> +
> +  "#address-cells":
> +    const: 1
> +
> +  "#size-cells":
> +    const: 1
> +
> +  ranges: true
> +
> +patternProperties:
> +  "^dma-controller(@[0-9a-f]+)?$":
> +    $ref: /schemas/dma/nvidia,tegra210-adma.yaml#
> +  "^interrupt-controller(@[0-9a-f]+)?$":
> +    $ref: /schemas/interrupt-controller/arm,gic.yaml#
> +  "^ahub(@[0-9a-f]+)?$":
> +    $ref: /schemas/sound/nvidia,tegra210-ahub.yaml#

These all get applied already since they match on compatible strings. So 
having them here means the schema is applied twice. There's maybe some 
value to this if it's always going to be these 3 nodes.

Also, the unit-addresses shouldn't be optional.

I'd just do:

"@[0-9a-f]+$":
  type: object

> +
> +required:
> +  - compatible
> +  - clocks
> +  - clock-names
> +  - power-domains
> +  - "#address-cells"
> +  - "#size-cells"
> +  - ranges
> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    #include<dt-bindings/clock/tegra210-car.h>
> +
> +    aconnect@702c0000 {
> +        compatible = "nvidia,tegra210-aconnect";
> +        clocks = <&tegra_car TEGRA210_CLK_APE>,
> +                 <&tegra_car TEGRA210_CLK_APB2APE>;
> +        clock-names = "ape", "apb2ape";
> +        power-domains = <&pd_audio>;
> +
> +        #address-cells = <1>;
> +        #size-cells = <1>;
> +        ranges = <0x702c0000 0x702c0000 0x00040000>;
> +
> +        // Child device nodes follow ...
> +    };
> +
> +...
> -- 
> 2.7.4
>
Sameer Pujar Nov. 6, 2020, 6:44 a.m. UTC | #2 
>> Move ACONNECT documentation to YAML format.
>>
>> Signed-off-by: Sameer Pujar <spujar@nvidia.com>
>> ---
>>   .../bindings/bus/nvidia,tegra210-aconnect.txt      | 44 -----------
>>   .../bindings/bus/nvidia,tegra210-aconnect.yaml     | 86 ++++++++++++++++++++++
>>   2 files changed, 86 insertions(+), 44 deletions(-)
>>   delete mode 100644 Documentation/devicetree/bindings/bus/nvidia,tegra210-aconnect.txt
>>   create mode 100644 Documentation/devicetree/bindings/bus/nvidia,tegra210-aconnect.yaml
>>

...

>> diff --git a/Documentation/devicetree/bindings/bus/nvidia,tegra210-aconnect.yaml b/Documentation/devicetree/bindings/bus/nvidia,tegra210-aconnect.yaml
>> new file mode 100644
>> index 0000000..f0161bc
>> --- /dev/null
>> +++ b/Documentation/devicetree/bindings/bus/nvidia,tegra210-aconnect.yaml
>> @@ -0,0 +1,86 @@
>> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
>> +%YAML 1.2
>> +---
>> +$id: http://devicetree.org/schemas/bus/nvidia,tegra210-aconnect.yaml#
>> +$schema: http://devicetree.org/meta-schemas/core.yaml#
>> +
>> +title: NVIDIA Tegra ACONNECT Bus
>> +
>> +description: |
>> +  The Tegra ACONNECT bus is an AXI switch which is used to connnect various
>> +  components inside the Audio Processing Engine (APE). All CPU accesses to
>> +  the APE subsystem go through the ACONNECT via an APB to AXI wrapper. All
>> +  devices accessed via the ACONNNECT are described by child-nodes.
>> +

...

>> +
>> +patternProperties:
>> +  "^dma-controller(@[0-9a-f]+)?$":
>> +    $ref: /schemas/dma/nvidia,tegra210-adma.yaml#
>> +  "^interrupt-controller(@[0-9a-f]+)?$":
>> +    $ref: /schemas/interrupt-controller/arm,gic.yaml#
>> +  "^ahub(@[0-9a-f]+)?$":
>> +    $ref: /schemas/sound/nvidia,tegra210-ahub.yaml#
> These all get applied already since they match on compatible strings. So
> having them here means the schema is applied twice. There's maybe some
> value to this if it's always going to be these 3 nodes.

1) May be this could be dropped with "additionalProperties = true", but 
that allows any arbitary property to be added for the device. Without 
this 'make dtbs_check' complains about not matching properties in DT files.

2) These may not be the final list of nodes this device can have. In 
future if any new device support gets added under this, above needs to 
be updated. But it will be limited number of devices.

So is [2] fine or you would suggest [1] would be good enough?

>
> Also, the unit-addresses shouldn't be optional.
>
> I'd just do:
>
> "@[0-9a-f]+$":
>    type: object
>
>> +
>> +required:
>> +  - compatible
>> +  - clocks
>> +  - clock-names
>> +  - power-domains
>> +  - "#address-cells"
>> +  - "#size-cells"
>> +  - ranges
>> +
>> +additionalProperties: false
>> +
>> +examples:
>> +  - |
>> +    #include<dt-bindings/clock/tegra210-car.h>
>> +
>> +    aconnect@702c0000 {
>> +        compatible = "nvidia,tegra210-aconnect";
>> +        clocks = <&tegra_car TEGRA210_CLK_APE>,
>> +                 <&tegra_car TEGRA210_CLK_APB2APE>;
>> +        clock-names = "ape", "apb2ape";
>> +        power-domains = <&pd_audio>;
>> +
>> +        #address-cells = <1>;
>> +        #size-cells = <1>;
>> +        ranges = <0x702c0000 0x702c0000 0x00040000>;
>> +
>> +        // Child device nodes follow ...
>> +    };
>> +
>> +...
>> --
>> 2.7.4
>>
Rob Herring (Arm) Nov. 6, 2020, 2:37 p.m. UTC | #3 
On Fri, Nov 6, 2020 at 12:44 AM Sameer Pujar <spujar@nvidia.com> wrote:
>
>
> >> Move ACONNECT documentation to YAML format.
> >>
> >> Signed-off-by: Sameer Pujar <spujar@nvidia.com>
> >> ---
> >>   .../bindings/bus/nvidia,tegra210-aconnect.txt      | 44 -----------
> >>   .../bindings/bus/nvidia,tegra210-aconnect.yaml     | 86 ++++++++++++++++++++++
> >>   2 files changed, 86 insertions(+), 44 deletions(-)
> >>   delete mode 100644 Documentation/devicetree/bindings/bus/nvidia,tegra210-aconnect.txt
> >>   create mode 100644 Documentation/devicetree/bindings/bus/nvidia,tegra210-aconnect.yaml
> >>
>
> ...
>
> >> diff --git a/Documentation/devicetree/bindings/bus/nvidia,tegra210-aconnect.yaml b/Documentation/devicetree/bindings/bus/nvidia,tegra210-aconnect.yaml
> >> new file mode 100644
> >> index 0000000..f0161bc
> >> --- /dev/null
> >> +++ b/Documentation/devicetree/bindings/bus/nvidia,tegra210-aconnect.yaml
> >> @@ -0,0 +1,86 @@
> >> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> >> +%YAML 1.2
> >> +---
> >> +$id: http://devicetree.org/schemas/bus/nvidia,tegra210-aconnect.yaml#
> >> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> >> +
> >> +title: NVIDIA Tegra ACONNECT Bus
> >> +
> >> +description: |
> >> +  The Tegra ACONNECT bus is an AXI switch which is used to connnect various
> >> +  components inside the Audio Processing Engine (APE). All CPU accesses to
> >> +  the APE subsystem go through the ACONNECT via an APB to AXI wrapper. All
> >> +  devices accessed via the ACONNNECT are described by child-nodes.
> >> +
>
> ...
>
> >> +
> >> +patternProperties:
> >> +  "^dma-controller(@[0-9a-f]+)?$":
> >> +    $ref: /schemas/dma/nvidia,tegra210-adma.yaml#
> >> +  "^interrupt-controller(@[0-9a-f]+)?$":
> >> +    $ref: /schemas/interrupt-controller/arm,gic.yaml#
> >> +  "^ahub(@[0-9a-f]+)?$":
> >> +    $ref: /schemas/sound/nvidia,tegra210-ahub.yaml#
> > These all get applied already since they match on compatible strings. So
> > having them here means the schema is applied twice. There's maybe some
> > value to this if it's always going to be these 3 nodes.
>
> 1) May be this could be dropped with "additionalProperties = true", but
> that allows any arbitary property to be added for the device. Without
> this 'make dtbs_check' complains about not matching properties in DT files.

Not if you do what I suggested below. Then only arbitrary nodes can be added.

>
> 2) These may not be the final list of nodes this device can have. In
> future if any new device support gets added under this, above needs to
> be updated. But it will be limited number of devices.
>
> So is [2] fine or you would suggest [1] would be good enough?
>
> >
> > Also, the unit-addresses shouldn't be optional.
> >
> > I'd just do:
> >
> > "@[0-9a-f]+$":
> >    type: object
> >
> >> +
> >> +required:
> >> +  - compatible
> >> +  - clocks
> >> +  - clock-names
> >> +  - power-domains
> >> +  - "#address-cells"
> >> +  - "#size-cells"
> >> +  - ranges
> >> +
> >> +additionalProperties: false
> >> +
> >> +examples:
> >> +  - |
> >> +    #include<dt-bindings/clock/tegra210-car.h>
> >> +
> >> +    aconnect@702c0000 {
> >> +        compatible = "nvidia,tegra210-aconnect";
> >> +        clocks = <&tegra_car TEGRA210_CLK_APE>,
> >> +                 <&tegra_car TEGRA210_CLK_APB2APE>;
> >> +        clock-names = "ape", "apb2ape";
> >> +        power-domains = <&pd_audio>;
> >> +
> >> +        #address-cells = <1>;
> >> +        #size-cells = <1>;
> >> +        ranges = <0x702c0000 0x702c0000 0x00040000>;
> >> +
> >> +        // Child device nodes follow ...
> >> +    };
> >> +
> >> +...
> >> --
> >> 2.7.4
> >>
>
diff mbox series

Patch

diff --git a/Documentation/devicetree/bindings/bus/nvidia,tegra210-aconnect.txt b/Documentation/devicetree/bindings/bus/nvidia,tegra210-aconnect.txt
deleted file mode 100644
index 3108d03..0000000
--- a/Documentation/devicetree/bindings/bus/nvidia,tegra210-aconnect.txt
+++ /dev/null
@@ -1,44 +0,0 @@ 
-NVIDIA Tegra ACONNECT Bus
-
-The Tegra ACONNECT bus is an AXI switch which is used to connnect various
-components inside the Audio Processing Engine (APE). All CPU accesses to
-the APE subsystem go through the ACONNECT via an APB to AXI wrapper.
-
-Required properties:
-- compatible: Must be "nvidia,tegra210-aconnect".
-- clocks: Must contain the entries for the APE clock (TEGRA210_CLK_APE),
-  and APE interface clock (TEGRA210_CLK_APB2APE).
-- clock-names: Must contain the names "ape" and "apb2ape" for the corresponding
-  'clocks' entries.
-- power-domains: Must contain a phandle that points to the audio powergate
-  (namely 'aud') for Tegra210.
-- #address-cells: The number of cells used to represent physical base addresses
-  in the aconnect address space. Should be 1.
-- #size-cells: The number of cells used to represent the size of an address
-  range in the aconnect address space. Should be 1.
-- ranges: Mapping of the aconnect address space to the CPU address space.
-
-All devices accessed via the ACONNNECT are described by child-nodes.
-
-Example:
-
-	aconnect@702c0000 {
-		compatible = "nvidia,tegra210-aconnect";
-		clocks = <&tegra_car TEGRA210_CLK_APE>,
-			 <&tegra_car TEGRA210_CLK_APB2APE>;
-		clock-names = "ape", "apb2ape";
-		power-domains = <&pd_audio>;
-
-		#address-cells = <1>;
-		#size-cells = <1>;
-		ranges = <0x702c0000 0x0 0x702c0000 0x00040000>;
-
-
-		child1 {
-			...
-		};
-
-		child2 {
-			...
-		};
-	};
diff --git a/Documentation/devicetree/bindings/bus/nvidia,tegra210-aconnect.yaml b/Documentation/devicetree/bindings/bus/nvidia,tegra210-aconnect.yaml
new file mode 100644
index 0000000..f0161bc
--- /dev/null
+++ b/Documentation/devicetree/bindings/bus/nvidia,tegra210-aconnect.yaml
@@ -0,0 +1,86 @@ 
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/bus/nvidia,tegra210-aconnect.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: NVIDIA Tegra ACONNECT Bus
+
+description: |
+  The Tegra ACONNECT bus is an AXI switch which is used to connnect various
+  components inside the Audio Processing Engine (APE). All CPU accesses to
+  the APE subsystem go through the ACONNECT via an APB to AXI wrapper. All
+  devices accessed via the ACONNNECT are described by child-nodes.
+
+maintainers:
+  - Jon Hunter <jonathanh@nvidia.com>
+
+properties:
+  compatible:
+    oneOf:
+      - const: nvidia,tegra210-aconnect
+      - items:
+          - enum:
+              - nvidia,tegra186-aconnect
+              - nvidia,tegra194-aconnect
+          - const: nvidia,tegra210-aconnect
+
+  clocks:
+    items:
+      - description: Must contain the entry for APE clock
+      - description: Must contain the entry for APE interface clock
+
+  clock-names:
+    items:
+      - const: ape
+      - const: apb2ape
+
+  power-domains:
+    maxItems: 1
+
+  "#address-cells":
+    const: 1
+
+  "#size-cells":
+    const: 1
+
+  ranges: true
+
+patternProperties:
+  "^dma-controller(@[0-9a-f]+)?$":
+    $ref: /schemas/dma/nvidia,tegra210-adma.yaml#
+  "^interrupt-controller(@[0-9a-f]+)?$":
+    $ref: /schemas/interrupt-controller/arm,gic.yaml#
+  "^ahub(@[0-9a-f]+)?$":
+    $ref: /schemas/sound/nvidia,tegra210-ahub.yaml#
+
+required:
+  - compatible
+  - clocks
+  - clock-names
+  - power-domains
+  - "#address-cells"
+  - "#size-cells"
+  - ranges
+
+additionalProperties: false
+
+examples:
+  - |
+    #include<dt-bindings/clock/tegra210-car.h>
+
+    aconnect@702c0000 {
+        compatible = "nvidia,tegra210-aconnect";
+        clocks = <&tegra_car TEGRA210_CLK_APE>,
+                 <&tegra_car TEGRA210_CLK_APB2APE>;
+        clock-names = "ape", "apb2ape";
+        power-domains = <&pd_audio>;
+
+        #address-cells = <1>;
+        #size-cells = <1>;
+        ranges = <0x702c0000 0x702c0000 0x00040000>;
+
+        // Child device nodes follow ...
+    };
+
+...