Skip to contentSkip to conversation

dt-bindings: dma: Add YAML schemas for the generic DMA bindings

PATCH In review Maxime Ripard 3 participants 8 messages Jul 11, 2019 – Jul 12, 2019

Subsystems (3)
lore
Share & tools
lore
#0 lore raw

PATCH 1/3 dt-bindings: dma: Add YAML schemas for the generic DMA bindings

The DMA controllers and consumers have a bunch of generic properties that are needed in a device tree. Add a YAML schemas for those.

---
 .../devicetree/bindings/dma/dma-consumer.yaml |  60 +++++++++
 .../bindings/dma/dma-controller.yaml          |  79 ++++++++++++
 Documentation/devicetree/bindings/dma/dma.txt | 114 +-----------------
 3 files changed, 140 insertions(+), 113 deletions(-)
 create mode 100644 Documentation/devicetree/bindings/dma/dma-consumer.yaml
 create mode 100644 Documentation/devicetree/bindings/dma/dma-controller.yaml
Documentation/devicetree/bindings/dma/dma-consumer.yaml new file +60 -0
new file mode 100644
index 000000000000..2f6315863ad1
@@ -0,0 +1,60 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/dma/dma-consumer.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: DMA Consumer Generic Binding
+
+maintainers:
+  - Vinod Koul <[email protected]>
+
+select: true
+
+properties:
+  dmas:
+    description:
+      List of one or more DMA specifiers, each consisting of
+          - A phandle pointing to DMA controller node
+          - A number of integer cells, as determined by the
+            \#dma-cells property in the node referenced by phandle
+            containing DMA controller specific information. This
+            typically contains a DMA request line number or a
+            channel number, but can contain any data that is
+            required for configuring a channel.
+
+  dma-names:
+    description:
+      Contains one identifier string for each DMA specifier in the
+      dmas property. The specific strings that can be used are defined
+      in the binding of the DMA client device.  Multiple DMA
+      specifiers can be used to represent alternatives and in this
+      case the dma-names for those DMA specifiers must be identical
+      (see examples).
+
+dependencies:
+  dma-names: [ dmas ]
+
+examples:
+  - |
+    /* A device with one DMA read channel, one DMA write channel */
+    i2c1: i2c@1 {
+         /* ... */
+         dmas = <&dma 2>, 	/* read channel */
+                <&dma 3>;	/* write channel */
+        dma-names = "rx", "tx";
+        /* ... */
+    };
+
+  - |
+    /* A single read-write channel with three alternative DMA controllers */
+    dmas = <&dma1 5>, <&dma2 7>, <&dma3 2>;
+    dma-names = "rx-tx", "rx-tx", "rx-tx";
+
+  - |
+    /* A device with three channels, one of which has two alternatives */
+    dmas = <&dma1 2>,		/* read channel */
+           <&dma1 3>,		/* write channel */
+           <&dma2 0>,		/* error read */
+           <&dma3 0>;		/* alternative error read */
+    dma-names = "rx", "tx", "error", "error";
Documentation/devicetree/bindings/dma/dma-controller.yaml new file +79 -0

79 lines not on this page · raw message

Documentation/devicetree/bindings/dma/dma.txt +1 -113

114 lines not on this page · raw message

Signature · 1 line
2.21.0
#1 lore raw

PATCH 2/3 dt-bindings: dma: Convert Allwinner A10 DMA to a schema

The older Allwinner SoCs have a DMA controller supported in Linux, with a matching Device Tree binding.

Now that we have the DT validation in place, let's convert the device tree bindings for that controller over to a YAML schemas.

---
 .../bindings/dma/allwinner,sun4i-a10-dma.yaml | 55 +++++++++++++++++++
 .../devicetree/bindings/dma/sun4i-dma.txt     | 45 ---------------
 2 files changed, 55 insertions(+), 45 deletions(-)
 create mode 100644 Documentation/devicetree/bindings/dma/allwinner,sun4i-a10-dma.yaml
 delete mode 100644 Documentation/devicetree/bindings/dma/sun4i-dma.txt
Documentation/devicetree/bindings/dma/allwinner,sun4i-a10-dma.yaml new file +55 -0
new file mode 100644
index 000000000000..15abc0f9429f
@@ -0,0 +1,55 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/dma/allwinner,sun4i-a10-dma.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Allwinner A10 DMA Controller Device Tree Bindings
+
+maintainers:
+  - Chen-Yu Tsai <[email protected]>
+  - Maxime Ripard <[email protected]>
+
+allOf:
+  - $ref: "dma-controller.yaml#"
+
+properties:
+  "#dma-cells":
+    const: 2
+    description:
+      The first cell is either 0 or 1, the former to use the normal
+      DMA, 1 for dedicated DMA. The second cell is the request line
+      number.
+
+  compatible:
+    const: allwinner,sun4i-a10-dma
+
+  reg:
+    maxItems: 1
+
+  interrupts:
+    maxItems: 1
+
+  clocks:
+    maxItems: 1
+
+required:
+  - "#dma-cells"
+  - compatible
+  - reg
+  - interrupts
+  - clocks
+
+additionalProperties: false
+
+examples:
+  - |
+    dma: dma-controller@1c02000 {
+        compatible = "allwinner,sun4i-a10-dma";
+        reg = <0x01c02000 0x1000>;
+        interrupts = <27>;
+        clocks = <&ahb_gates 6>;
+        #dma-cells = <2>;
+    };
+
+...
Documentation/devicetree/bindings/dma/sun4i-dma.txt deleted +0 -45

45 lines not on this page · raw message

Signature · 1 line
2.21.0
Reviewed-by on v1 2/3
#2 lore raw

Re: [PATCH 2/3] dt-bindings: dma: Convert Allwinner A10 DMA to a schema

Quoted 7 lines · Maxime Ripard

The older Allwinner SoCs have a DMA controller supported in Linux, with a matching Device Tree binding.

Now that we have the DT validation in place, let's convert the device tree bindings for that controller over to a YAML schemas.

Quoted 7 lines
---
 .../bindings/dma/allwinner,sun4i-a10-dma.yaml | 55 +++++++++++++++++++
 .../devicetree/bindings/dma/sun4i-dma.txt     | 45 ---------------
 2 files changed, 55 insertions(+), 45 deletions(-)
 create mode 100644 Documentation/devicetree/bindings/dma/allwinner,sun4i-a10-dma.yaml
 delete mode 100644 Documentation/devicetree/bindings/dma/sun4i-dma.txt
#3 lore raw

PATCH 3/3 dt-bindings: dma: Convert Allwinner A31 and A64 DMA to a schema

In reply to Maxime Ripard

The newer Allwinner SoCs have a DMA controller supported in Linux, with a matching Device Tree binding.

Now that we have the DT validation in place, let's convert the device tree bindings for that controller over to a YAML schemas.

---
 .../dma/allwinner,sun50i-a64-dma.yaml         | 88 +++++++++++++++++++
 .../bindings/dma/allwinner,sun6i-a31-dma.yaml | 62 +++++++++++++
 .../devicetree/bindings/dma/sun6i-dma.txt     | 81 -----------------
 3 files changed, 150 insertions(+), 81 deletions(-)
 create mode 100644 Documentation/devicetree/bindings/dma/allwinner,sun50i-a64-dma.yaml
 create mode 100644 Documentation/devicetree/bindings/dma/allwinner,sun6i-a31-dma.yaml
 delete mode 100644 Documentation/devicetree/bindings/dma/sun6i-dma.txt
Documentation/devicetree/bindings/dma/allwinner,sun50i-a64-dma.yaml new file +88 -0
new file mode 100644
index 000000000000..4cb9d6b93138
@@ -0,0 +1,88 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/dma/allwinner,sun50i-a64-dma.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Allwinner A64 DMA Controller Device Tree Bindings
+
+maintainers:
+  - Chen-Yu Tsai <[email protected]>
+  - Maxime Ripard <[email protected]>
+
+allOf:
+  - $ref: "dma-controller.yaml#"
+
+properties:
+  "#dma-cells":
+    const: 1
+    description: The cell is the request line number.
+
+  compatible:
+    enum:
+      - allwinner,sun50i-a64-dma
+      - allwinner,sun50i-h6-dma
+
+  reg:
+    maxItems: 1
+
+  interrupts:
+    maxItems: 1
+
+  clocks:
+    minItems: 1
+    maxItems: 2
+
+  clock-names:
+    items:
+      - const: bus
+      - const: mbus
+
+  resets:
+    maxItems: 1
+
+required:
+  - "#dma-cells"
+  - compatible
+  - reg
+  - interrupts
+  - clocks
+  - resets
+  - dma-channels
+
+if:
+  properties:
+    compatible:
+      const: allwinner,sun50i-h6-dma
+
+then:
+  properties:
+    clocks:
+      maxItems: 2
+
+  required:
+    - clock-names
+
+else:
+  properties:
+    clocks:
+      maxItems: 1
+
+# FIXME: We should set it, but it would report all the generic
+# properties as additional properties.
+# additionalProperties: false
+
+examples:
+  - |
+    dma: dma-controller@1c02000 {
+        compatible = "allwinner,sun50i-a64-dma";
+        reg = <0x01c02000 0x1000>;
+        interrupts = <0 50 4>;
+        clocks = <&ccu 30>;
+        dma-channels = <8>;
+        dma-requests = <27>;
+        resets = <&ccu 7>;
+        #dma-cells = <1>;
+    };
+
+...
Documentation/devicetree/bindings/dma/allwinner,sun6i-a31-dma.yaml new file +62 -0

62 lines not on this page · raw message

Documentation/devicetree/bindings/dma/sun6i-dma.txt deleted +0 -81

81 lines not on this page · raw message

Signature · 1 line
2.21.0
Reviewed-by on v1 3/3
#4 lore raw

Re: [PATCH 3/3] dt-bindings: dma: Convert Allwinner A31 and A64 DMA to a schema

Quoted 8 lines · Maxime Ripard

The newer Allwinner SoCs have a DMA controller supported in Linux, with a matching Device Tree binding.

Now that we have the DT validation in place, let's convert the device tree bindings for that controller over to a YAML schemas.

Quoted 8 lines
---
 .../dma/allwinner,sun50i-a64-dma.yaml         | 88 +++++++++++++++++++
 .../bindings/dma/allwinner,sun6i-a31-dma.yaml | 62 +++++++++++++
 .../devicetree/bindings/dma/sun6i-dma.txt     | 81 -----------------
 3 files changed, 150 insertions(+), 81 deletions(-)
 create mode 100644 Documentation/devicetree/bindings/dma/allwinner,sun50i-a64-dma.yaml
 create mode 100644 Documentation/devicetree/bindings/dma/allwinner,sun6i-a31-dma.yaml
 delete mode 100644 Documentation/devicetree/bindings/dma/sun6i-dma.txt
#5 lore raw
In reply to Maxime Ripard
Quoted 7 lines · Maxime Ripard

The DMA controllers and consumers have a bunch of generic properties that are needed in a device tree. Add a YAML schemas for those.

---
 .../devicetree/bindings/dma/dma-consumer.yaml |  60 +++++++++

This already exists in the dt-schema/schemas/dma/dma.yaml though not the descriptions because that needs relicensing.

Looks like we need NVidia's (Jon H) and TI's (Peter U) permission.

Quoted 124 lines
 .../bindings/dma/dma-controller.yaml          |  79 ++++++++++++
 Documentation/devicetree/bindings/dma/dma.txt | 114 +-----------------
 3 files changed, 140 insertions(+), 113 deletions(-)
 create mode 100644 Documentation/devicetree/bindings/dma/dma-consumer.yaml
 create mode 100644 Documentation/devicetree/bindings/dma/dma-controller.yaml
Documentation/devicetree/bindings/dma/dma-consumer.yaml new file +60 -0
new file mode 100644
index 000000000000..2f6315863ad1
@@ -0,0 +1,60 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/dma/dma-consumer.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: DMA Consumer Generic Binding
+
+maintainers:
+  - Vinod Koul <[email protected]>
+
+select: true
+
+properties:
+  dmas:
+    description:
+      List of one or more DMA specifiers, each consisting of
+          - A phandle pointing to DMA controller node
+          - A number of integer cells, as determined by the
+            \#dma-cells property in the node referenced by phandle
+            containing DMA controller specific information. This
+            typically contains a DMA request line number or a
+            channel number, but can contain any data that is
+            required for configuring a channel.
+
+  dma-names:
+    description:
+      Contains one identifier string for each DMA specifier in the
+      dmas property. The specific strings that can be used are defined
+      in the binding of the DMA client device.  Multiple DMA
+      specifiers can be used to represent alternatives and in this
+      case the dma-names for those DMA specifiers must be identical
+      (see examples).
+
+dependencies:
+  dma-names: [ dmas ]
+
+examples:
+  - |
+    /* A device with one DMA read channel, one DMA write channel */
+    i2c1: i2c@1 {
+         /* ... */
+         dmas = <&dma 2>,      /* read channel */
+                <&dma 3>;      /* write channel */
+        dma-names = "rx", "tx";
+        /* ... */
+    };
+
+  - |
+    /* A single read-write channel with three alternative DMA controllers */
+    dmas = <&dma1 5>, <&dma2 7>, <&dma3 2>;
+    dma-names = "rx-tx", "rx-tx", "rx-tx";
+
+  - |
+    /* A device with three channels, one of which has two alternatives */
+    dmas = <&dma1 2>,          /* read channel */
+           <&dma1 3>,          /* write channel */
+           <&dma2 0>,          /* error read */
+           <&dma3 0>;          /* alternative error read */
+    dma-names = "rx", "tx", "error", "error";
Documentation/devicetree/bindings/dma/dma-controller.yaml new file +46 -0
new file mode 100644
index 000000000000..17c650131b78
@@ -0,0 +1,79 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/dma/dma-controller.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: DMA Controller Generic Binding
+
+maintainers:
+  - Vinod Koul <[email protected]>
+
+description:
+  Generic binding to provide a way for a driver using DMA Engine to
+  retrieve the DMA request or channel information that goes from a
+  hardware device to a DMA controller.
+
+properties:
+  $nodename:
+    pattern: "^dma-controller(@.*)?$"
+
+  "#dma-cells":
+    # minimum: 1
+    description:
+      Used to provide DMA controller specific information.
+
+  dma-channel-masks:
+    $ref: /schemas/types.yaml#definitions/uint32
+    description:
+      Bitmask of available DMA channels in ascending order that are
+      not reserved by firmware and are available to the
+      kernel. i.e. first channel corresponds to LSB.
+
+  dma-channels:
+    $ref: /schemas/types.yaml#definitions/uint32
+    description:
+      Number of DMA channels supported by the controller.
+
+  dma-masters:
+    $ref: /schemas/types.yaml#definitions/phandle-array
+    description:
+      DMA routers are transparent IP blocks used to route DMA request
+      lines from devices to the DMA controller. Some SoCs (like TI
+      DRA7x) have more peripherals integrated with DMA requests than
+      what the DMA controller can handle directly.
+
+      In such a case, dma-masters is an array of phandle to the DMA

Documentation/devicetree/bindings/dma/dma-controller.yaml line 56

Quoted 10 lines
Documentation/devicetree/bindings/dma/dma-controller.yaml new file +10 -0
+      controllers the router can direct the signal to.
+
+  dma-requests:
+    $ref: /schemas/types.yaml#definitions/uint32
+    description:
+      Number of DMA request signals supported by the controller.
+
+examples:
+  - |
+    dma: dma@48000000 {

dma-controller@...

This is a case where I'd like some check that the schema is actually applied to the schema's example.

Quoted 145 lines
Documentation/devicetree/bindings/dma/dma-controller.yaml new file +23 -0
+        compatible = "ti,omap-sdma";
+        reg = <0x48000000 0x1000>;
+        interrupts = <0 12 0x4
+                      0 13 0x4
+                      0 14 0x4
+                      0 15 0x4>;
+        #dma-cells = <1>;
+        dma-channels = <32>;
+        dma-requests = <127>;
+        dma-channel-mask = <0xfffe>;
+    };
+
+  - |
+    sdma_xbar: dma-router@4a002b78 {
+        compatible = "ti,dra7-dma-crossbar";
+        reg = <0x4a002b78 0xfc>;
+        #dma-cells = <1>;
+        dma-requests = <205>;
+        ti,dma-safe-map = <0>;
+        dma-masters = <&sdma>;
+    };
+
+...
Documentation/devicetree/bindings/dma/dma.txt +1 -114
index eeb4e4d1771e..90a67a016a48 100644
@@ -1,113 +1 @@
-* Generic DMA Controller and DMA request bindings
-
-Generic binding to provide a way for a driver using DMA Engine to retrieve the
-DMA request or channel information that goes from a hardware device to a DMA
-controller.
-
-
-* DMA controller
-
-Required property:
-- #dma-cells:          Must be at least 1. Used to provide DMA controller
-                       specific information. See DMA client binding below for
-                       more details.
-
-Optional properties:
-- dma-channels:        Number of DMA channels supported by the controller.
-- dma-requests:        Number of DMA request signals supported by the
-                       controller.
-- dma-channel-mask:    Bitmask of available DMA channels in ascending order
-                       that are not reserved by firmware and are available to
-                       the kernel. i.e. first channel corresponds to LSB.
-
-Example:
-
-       dma: dma@48000000 {
-               compatible = "ti,omap-sdma";
-               reg = <0x48000000 0x1000>;
-               interrupts = <0 12 0x4
-                             0 13 0x4
-                             0 14 0x4
-                             0 15 0x4>;
-               #dma-cells = <1>;
-               dma-channels = <32>;
-               dma-requests = <127>;
-               dma-channel-mask = <0xfffe>
-       };
-
-* DMA router
-
-DMA routers are transparent IP blocks used to route DMA request lines from
-devices to the DMA controller. Some SoCs (like TI DRA7x) have more peripherals
-integrated with DMA requests than what the DMA controller can handle directly.
-
-Required property:
-- dma-masters:         phandle of the DMA controller or list of phandles for
-                       the DMA controllers the router can direct the signal to.
-- #dma-cells:          Must be at least 1. Used to provide DMA router specific
-                       information. See DMA client binding below for more
-                       details.
-
-Optional properties:
-- dma-requests:        Number of incoming request lines the router can handle.
-- In the node pointed by the dma-masters:
-       - dma-requests: The router driver might need to look for this in order
-                       to configure the routing.
-
-Example:
-       sdma_xbar: dma-router@4a002b78 {
-               compatible = "ti,dra7-dma-crossbar";
-               reg = <0x4a002b78 0xfc>;
-               #dma-cells = <1>;
-               dma-requests = <205>;
-               ti,dma-safe-map = <0>;
-               dma-masters = <&sdma>;
-       };
-
-* DMA client
-
-Client drivers should specify the DMA property using a phandle to the controller
-followed by DMA controller specific data.
-
-Required property:
-- dmas:                        List of one or more DMA specifiers, each consisting of
-                       - A phandle pointing to DMA controller node
-                       - A number of integer cells, as determined by the
-                         #dma-cells property in the node referenced by phandle
-                         containing DMA controller specific information. This
-                         typically contains a DMA request line number or a
-                         channel number, but can contain any data that is
-                         required for configuring a channel.
-- dma-names:           Contains one identifier string for each DMA specifier in
-                       the dmas property. The specific strings that can be used
-                       are defined in the binding of the DMA client device.
-                       Multiple DMA specifiers can be used to represent
-                       alternatives and in this case the dma-names for those
-                       DMA specifiers must be identical (see examples).
-
-Examples:
-
-1. A device with one DMA read channel, one DMA write channel:
-
-       i2c1: i2c@1 {
-               ...
-               dmas = <&dma 2          /* read channel */
-                       &dma 3>;        /* write channel */
-               dma-names = "rx", "tx";
-               ...
-       };
-
-2. A single read-write channel with three alternative DMA controllers:
-
-       dmas = <&dma1 5
-               &dma2 7
-               &dma3 2>;
-       dma-names = "rx-tx", "rx-tx", "rx-tx";
-
-3. A device with three channels, one of which has two alternatives:
-
-       dmas = <&dma1 2                 /* read channel */
-               &dma1 3                 /* write channel */
-               &dma2 0                 /* error read */
-               &dma3 0>;               /* alternative error read */
-       dma-names = "rx", "tx", "error", "error";
+This file has been moved to dma-controller.yaml.
--

2.21.0

#6 lore raw
Quoted 5 lines · Rob Herring
Quoted 4 lines · Maxime Ripard

The DMA controllers and consumers have a bunch of generic properties that are needed in a device tree. Add a YAML schemas for those.

Quoted 8 lines
Quoted 3 lines
---
 .../devicetree/bindings/dma/dma-consumer.yaml |  60 +++++++++

This already exists in the dt-schema/schemas/dma/dma.yaml though not the descriptions because that needs relicensing.

Looks like we need NVidia's (Jon H) and TI's (Peter U) permission.

If I'm not mistaken the new license is GPL-2.0, if so I don't see any issue, but I'll ask our legal to be sure.

And one comment for the change.

Quoted 118 lines
Quoted 118 lines
 .../bindings/dma/dma-controller.yaml          |  79 ++++++++++++
 Documentation/devicetree/bindings/dma/dma.txt | 114 +-----------------
 3 files changed, 140 insertions(+), 113 deletions(-)
 create mode 100644 Documentation/devicetree/bindings/dma/dma-consumer.yaml
 create mode 100644 Documentation/devicetree/bindings/dma/dma-controller.yaml
Documentation/devicetree/bindings/dma/dma-consumer.yaml new file +60 -0
new file mode 100644
index 000000000000..2f6315863ad1
@@ -0,0 +1,60 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/dma/dma-consumer.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: DMA Consumer Generic Binding
+
+maintainers:
+  - Vinod Koul <[email protected]>
+
+select: true
+
+properties:
+  dmas:
+    description:
+      List of one or more DMA specifiers, each consisting of
+          - A phandle pointing to DMA controller node
+          - A number of integer cells, as determined by the
+            \#dma-cells property in the node referenced by phandle
+            containing DMA controller specific information. This
+            typically contains a DMA request line number or a
+            channel number, but can contain any data that is
+            required for configuring a channel.
+
+  dma-names:
+    description:
+      Contains one identifier string for each DMA specifier in the
+      dmas property. The specific strings that can be used are defined
+      in the binding of the DMA client device.  Multiple DMA
+      specifiers can be used to represent alternatives and in this
+      case the dma-names for those DMA specifiers must be identical
+      (see examples).
+
+dependencies:
+  dma-names: [ dmas ]
+
+examples:
+  - |
+    /* A device with one DMA read channel, one DMA write channel */
+    i2c1: i2c@1 {
+         /* ... */
+         dmas = <&dma 2>,      /* read channel */
+                <&dma 3>;      /* write channel */
+        dma-names = "rx", "tx";
+        /* ... */
+    };
+
+  - |
+    /* A single read-write channel with three alternative DMA controllers */
+    dmas = <&dma1 5>, <&dma2 7>, <&dma3 2>;
+    dma-names = "rx-tx", "rx-tx", "rx-tx";
+
+  - |
+    /* A device with three channels, one of which has two alternatives */
+    dmas = <&dma1 2>,          /* read channel */
+           <&dma1 3>,          /* write channel */
+           <&dma2 0>,          /* error read */
+           <&dma3 0>;          /* alternative error read */
+    dma-names = "rx", "tx", "error", "error";
Documentation/devicetree/bindings/dma/dma-controller.yaml new file +39 -0
new file mode 100644
index 000000000000..17c650131b78
@@ -0,0 +1,79 @@
+# SPDX-License-Identifier: GPL-2.0
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/dma/dma-controller.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: DMA Controller Generic Binding
+
+maintainers:
+  - Vinod Koul <[email protected]>
+
+description:
+  Generic binding to provide a way for a driver using DMA Engine to
+  retrieve the DMA request or channel information that goes from a
+  hardware device to a DMA controller.
+
+properties:
+  $nodename:
+    pattern: "^dma-controller(@.*)?$"
+
+  "#dma-cells":
+    # minimum: 1
+    description:
+      Used to provide DMA controller specific information.
+
+  dma-channel-masks:
+    $ref: /schemas/types.yaml#definitions/uint32
+    description:
+      Bitmask of available DMA channels in ascending order that are
+      not reserved by firmware and are available to the
+      kernel. i.e. first channel corresponds to LSB.
+
+  dma-channels:
+    $ref: /schemas/types.yaml#definitions/uint32
+    description:
+      Number of DMA channels supported by the controller.
+
+  dma-masters:
+    $ref: /schemas/types.yaml#definitions/phandle-array
Quoted 8 lines

Documentation/devicetree/bindings/dma/dma-controller.yaml line 47

Quoted 8 lines
Documentation/devicetree/bindings/dma/dma-controller.yaml new file +8 -0
+    description:
+      DMA routers are transparent IP blocks used to route DMA request
+      lines from devices to the DMA controller. Some SoCs (like TI
+      DRA7x) have more peripherals integrated with DMA requests than
+      what the DMA controller can handle directly.
+
+      In such a case, dma-masters is an array of phandle to the DMA
+      controllers the router can direct the signal to.

It is no longer clear what is needed and what is optional anymore and if I would need to look up how a DMA router node should look like I will be in trouble, iow if I need to figure out how to describe an SoC with DMA controller and DMA event router.

Quoted 160 lines

Documentation/devicetree/bindings/dma/dma-controller.yaml line 56

Quoted 9 lines
Documentation/devicetree/bindings/dma/dma-controller.yaml new file +9 -0
+
+  dma-requests:
+    $ref: /schemas/types.yaml#definitions/uint32
+    description:
+      Number of DMA request signals supported by the controller.
+
+examples:
+  - |
+    dma: dma@48000000 {

dma-controller@...

This is a case where I'd like some check that the schema is actually applied to the schema's example.

Quoted 145 lines
Documentation/devicetree/bindings/dma/dma-controller.yaml new file +23 -0
+        compatible = "ti,omap-sdma";
+        reg = <0x48000000 0x1000>;
+        interrupts = <0 12 0x4
+                      0 13 0x4
+                      0 14 0x4
+                      0 15 0x4>;
+        #dma-cells = <1>;
+        dma-channels = <32>;
+        dma-requests = <127>;
+        dma-channel-mask = <0xfffe>;
+    };
+
+  - |
+    sdma_xbar: dma-router@4a002b78 {
+        compatible = "ti,dra7-dma-crossbar";
+        reg = <0x4a002b78 0xfc>;
+        #dma-cells = <1>;
+        dma-requests = <205>;
+        ti,dma-safe-map = <0>;
+        dma-masters = <&sdma>;
+    };
+
+...
Documentation/devicetree/bindings/dma/dma.txt +1 -114
index eeb4e4d1771e..90a67a016a48 100644
@@ -1,113 +1 @@
-* Generic DMA Controller and DMA request bindings
-
-Generic binding to provide a way for a driver using DMA Engine to retrieve the
-DMA request or channel information that goes from a hardware device to a DMA
-controller.
-
-
-* DMA controller
-
-Required property:
-- #dma-cells:          Must be at least 1. Used to provide DMA controller
-                       specific information. See DMA client binding below for
-                       more details.
-
-Optional properties:
-- dma-channels:        Number of DMA channels supported by the controller.
-- dma-requests:        Number of DMA request signals supported by the
-                       controller.
-- dma-channel-mask:    Bitmask of available DMA channels in ascending order
-                       that are not reserved by firmware and are available to
-                       the kernel. i.e. first channel corresponds to LSB.
-
-Example:
-
-       dma: dma@48000000 {
-               compatible = "ti,omap-sdma";
-               reg = <0x48000000 0x1000>;
-               interrupts = <0 12 0x4
-                             0 13 0x4
-                             0 14 0x4
-                             0 15 0x4>;
-               #dma-cells = <1>;
-               dma-channels = <32>;
-               dma-requests = <127>;
-               dma-channel-mask = <0xfffe>
-       };
-
-* DMA router
-
-DMA routers are transparent IP blocks used to route DMA request lines from
-devices to the DMA controller. Some SoCs (like TI DRA7x) have more peripherals
-integrated with DMA requests than what the DMA controller can handle directly.
-
-Required property:
-- dma-masters:         phandle of the DMA controller or list of phandles for
-                       the DMA controllers the router can direct the signal to.
-- #dma-cells:          Must be at least 1. Used to provide DMA router specific
-                       information. See DMA client binding below for more
-                       details.
-
-Optional properties:
-- dma-requests:        Number of incoming request lines the router can handle.
-- In the node pointed by the dma-masters:
-       - dma-requests: The router driver might need to look for this in order
-                       to configure the routing.
-
-Example:
-       sdma_xbar: dma-router@4a002b78 {
-               compatible = "ti,dra7-dma-crossbar";
-               reg = <0x4a002b78 0xfc>;
-               #dma-cells = <1>;
-               dma-requests = <205>;
-               ti,dma-safe-map = <0>;
-               dma-masters = <&sdma>;
-       };
-
-* DMA client
-
-Client drivers should specify the DMA property using a phandle to the controller
-followed by DMA controller specific data.
-
-Required property:
-- dmas:                        List of one or more DMA specifiers, each consisting of
-                       - A phandle pointing to DMA controller node
-                       - A number of integer cells, as determined by the
-                         #dma-cells property in the node referenced by phandle
-                         containing DMA controller specific information. This
-                         typically contains a DMA request line number or a
-                         channel number, but can contain any data that is
-                         required for configuring a channel.
-- dma-names:           Contains one identifier string for each DMA specifier in
-                       the dmas property. The specific strings that can be used
-                       are defined in the binding of the DMA client device.
-                       Multiple DMA specifiers can be used to represent
-                       alternatives and in this case the dma-names for those
-                       DMA specifiers must be identical (see examples).
-
-Examples:
-
-1. A device with one DMA read channel, one DMA write channel:
-
-       i2c1: i2c@1 {
-               ...
-               dmas = <&dma 2          /* read channel */
-                       &dma 3>;        /* write channel */
-               dma-names = "rx", "tx";
-               ...
-       };
-
-2. A single read-write channel with three alternative DMA controllers:
-
-       dmas = <&dma1 5
-               &dma2 7
-               &dma3 2>;
-       dma-names = "rx-tx", "rx-tx", "rx-tx";
-
-3. A device with three channels, one of which has two alternatives:
-
-       dmas = <&dma1 2                 /* read channel */
-               &dma1 3                 /* write channel */
-               &dma2 0                 /* error read */
-               &dma3 0>;               /* alternative error read */
-       dma-names = "rx", "tx", "error", "error";
+This file has been moved to dma-controller.yaml.
--

2.21.0

Signature · 4 lines
Peter

Texas Instruments Finland Oy, Porkkalankatu 22, 00180 Helsinki.
Y-tunnus/Business ID: 0615521-4. Kotipaikka/Domicile: Helsinki
#7 lore raw
Quoted 13 lines · Peter Ujfalusi
Quoted 9 lines · Rob Herring
Quoted 7 lines · Maxime Ripard

The DMA controllers and consumers have a bunch of generic properties that are needed in a device tree. Add a YAML schemas for those.

---
 .../devicetree/bindings/dma/dma-consumer.yaml |  60 +++++++++
Quoted 7 lines
Quoted 4 lines

This already exists in the dt-schema/schemas/dma/dma.yaml though not the descriptions because that needs relicensing.

Looks like we need NVidia's (Jon H) and TI's (Peter U) permission.

If I'm not mistaken the new license is GPL-2.0, if so I don't see any issue, but I'll ask our legal to be sure.

To move it to the schema repository we need it to be (GPL-2.0 OR BSD-2-Clause). I'd prefer to have the core bindings in the dt-schema repo rather than add to the kernel.

Rob