[PATCH v3] dt-bindings: dma: img-mdc-dma: convert to DT schema

[PATCH v3] dt-bindings: dma: img-mdc-dma: convert to DT schema

[Nino Zhang]

Convert the img-mdc-dma binding from txt to YAML schema.
No functional changes except dropping the consumer node
(spi@18100f00) from the example, which belongs to the
consumer binding instead.

Signed-off-by: Nino Zhang <ninozhang001@gmail.com>
---
v2 -> v3:
- Fix remaining issues based on Rob's and Krzysztof's comments.
- Link to v2: https://lore.kernel.org/all/20250824034509.445743-1-ninozhang001@gmail.com/

v1 -> v2:
- Addressed review comments from Rob.
- Link to v1: https://lore.kernel.org/all/20250821150255.236884-1-ninozhang001@gmail.com/

 .../bindings/dma/img,pistachio-mdc-dma.yaml   | 89 +++++++++++++++++++
 .../devicetree/bindings/dma/img-mdc-dma.txt   | 57 ------------
 2 files changed, 89 insertions(+), 57 deletions(-)
 create mode 100644 Documentation/devicetree/bindings/dma/img,pistachio-mdc-dma.yaml
 delete mode 100644 Documentation/devicetree/bindings/dma/img-mdc-dma.txt

diff --git a/Documentation/devicetree/bindings/dma/img,pistachio-mdc-dma.yaml b/Documentation/devicetree/bindings/dma/img,pistachio-mdc-dma.yaml
new file mode 100644
index 000000000000..198e80b528c8
--- /dev/null
+++ b/Documentation/devicetree/bindings/dma/img,pistachio-mdc-dma.yaml
@@ -0,0 +1,89 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/dma/img,pistachio-mdc-dma.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: IMG Multi-threaded DMA Controller (MDC)
+
+maintainers:
+  - Rahul Bedarkar <rahulbedarkar89@gmail.com>
+  - linux-mips@vger.kernel.org
+
+allOf:
+  - $ref: /schemas/dma/dma-controller.yaml#
+
+properties:
+  compatible:
+    const: img,pistachio-mdc-dma
+
+  reg:
+    maxItems: 1
+
+  interrupts:
+    minItems: 1
+    maxItems: 32
+
+  clocks:
+    maxItems: 1
+
+  clock-names:
+    items:
+      - const: sys
+
+  img,cr-periph:
+    $ref: /schemas/types.yaml#/definitions/phandle
+    description:
+      Phandle to peripheral control syscon node with DMA request to channel
+      mapping registers.
+
+  img,max-burst-multiplier:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    minimum: 1
+    description:
+      Maximum supported burst size multiplier. The maximum burst size is this
+      value multiplied by the hardware-reported bus width.
+
+  "#dma-cells":
+    const: 3
+    description: |
+      DMA specifier cells:
+        1: peripheral's DMA request line
+        2: channel bitmap: bit N set indicates channel N is usable
+        3: thread ID to be used by the channel
+
+  dma-channels:
+    minimum: 1
+    maximum: 32
+    description: Defaults to HW-reported value if not specified.
+
+required:
+  - compatible
+  - reg
+  - interrupts
+  - clocks
+  - clock-names
+  - img,cr-periph
+  - img,max-burst-multiplier
+  - "#dma-cells"
+
+unevaluatedProperties: false
+
+examples:
+  - |
+    #include <dt-bindings/interrupt-controller/mips-gic.h>
+    #include <dt-bindings/interrupt-controller/irq.h>
+
+    dma-controller@18143000 {
+      compatible = "img,pistachio-mdc-dma";
+      reg = <0x18143000 0x1000>;
+      interrupts = <GIC_SHARED 27 IRQ_TYPE_LEVEL_HIGH>,
+                   <GIC_SHARED 28 IRQ_TYPE_LEVEL_HIGH>;
+      clocks = <&system_clk>;
+      clock-names = "sys";
+
+      img,max-burst-multiplier = <16>;
+      img,cr-periph = <&cr_periph>;
+
+      #dma-cells = <3>;
+    };
diff --git a/Documentation/devicetree/bindings/dma/img-mdc-dma.txt b/Documentation/devicetree/bindings/dma/img-mdc-dma.txt
deleted file mode 100644
index 28c1341db346..000000000000
--- a/Documentation/devicetree/bindings/dma/img-mdc-dma.txt
+++ /dev/null
@@ -1,57 +0,0 @@
-* IMG Multi-threaded DMA Controller (MDC)
-
-Required properties:
-- compatible: Must be "img,pistachio-mdc-dma".
-- reg: Must contain the base address and length of the MDC registers.
-- interrupts: Must contain all the per-channel DMA interrupts.
-- clocks: Must contain an entry for each entry in clock-names.
-  See ../clock/clock-bindings.txt for details.
-- clock-names: Must include the following entries:
-  - sys: MDC system interface clock.
-- img,cr-periph: Must contain a phandle to the peripheral control syscon
-  node which contains the DMA request to channel mapping registers.
-- img,max-burst-multiplier: Must be the maximum supported burst size multiplier.
-  The maximum burst size is this value multiplied by the hardware-reported bus
-  width.
-- #dma-cells: Must be 3:
-  - The first cell is the peripheral's DMA request line.
-  - The second cell is a bitmap specifying to which channels the DMA request
-    line may be mapped (i.e. bit N set indicates channel N is usable).
-  - The third cell is the thread ID to be used by the channel.
-
-Optional properties:
-- dma-channels: Number of supported DMA channels, up to 32.  If not specified
-  the number reported by the hardware is used.
-
-Example:
-
-mdc: dma-controller@18143000 {
-	compatible = "img,pistachio-mdc-dma";
-	reg = <0x18143000 0x1000>;
-	interrupts = <GIC_SHARED 27 IRQ_TYPE_LEVEL_HIGH>,
-		     <GIC_SHARED 28 IRQ_TYPE_LEVEL_HIGH>,
-		     <GIC_SHARED 29 IRQ_TYPE_LEVEL_HIGH>,
-		     <GIC_SHARED 30 IRQ_TYPE_LEVEL_HIGH>,
-		     <GIC_SHARED 31 IRQ_TYPE_LEVEL_HIGH>,
-		     <GIC_SHARED 32 IRQ_TYPE_LEVEL_HIGH>,
-		     <GIC_SHARED 33 IRQ_TYPE_LEVEL_HIGH>,
-		     <GIC_SHARED 34 IRQ_TYPE_LEVEL_HIGH>,
-		     <GIC_SHARED 35 IRQ_TYPE_LEVEL_HIGH>,
-		     <GIC_SHARED 36 IRQ_TYPE_LEVEL_HIGH>,
-		     <GIC_SHARED 37 IRQ_TYPE_LEVEL_HIGH>,
-		     <GIC_SHARED 38 IRQ_TYPE_LEVEL_HIGH>;
-	clocks = <&system_clk>;
-	clock-names = "sys";
-
-	img,max-burst-multiplier = <16>;
-	img,cr-periph = <&cr_periph>;
-
-	#dma-cells = <3>;
-};
-
-spi@18100f00 {
-	...
-	dmas = <&mdc 9 0xffffffff 0>, <&mdc 10 0xffffffff 0>;
-	dma-names = "tx", "rx";
-	...
-};
-- 
2.43.0

Re: [PATCH v3] dt-bindings: dma: img-mdc-dma: convert to DT schema

[Krzysztof Kozlowski]

On Mon, Aug 25, 2025 at 03:41:41PM +0800, Nino Zhang wrote:
> Convert the img-mdc-dma binding from txt to YAML schema.
> No functional changes except dropping the consumer node
> (spi@18100f00) from the example, which belongs to the
> consumer binding instead.
> 
> Signed-off-by: Nino Zhang <ninozhang001@gmail.com>
> ---
> v2 -> v3:
> - Fix remaining issues based on Rob's and Krzysztof's comments.

That's vague. What exactly did you change?

Especially that this is not true. You never responded to comments, never
implemented them.

> - Link to v2: https://lore.kernel.org/all/20250824034509.445743-1-ninozhang001@gmail.com/
> 
> v1 -> v2:
> - Addressed review comments from Rob.
> - Link to v1: https://lore.kernel.org/all/20250821150255.236884-1-ninozhang001@gmail.com/
> 
>  .../bindings/dma/img,pistachio-mdc-dma.yaml   | 89 +++++++++++++++++++
>  .../devicetree/bindings/dma/img-mdc-dma.txt   | 57 ------------
>  2 files changed, 89 insertions(+), 57 deletions(-)
>  create mode 100644 Documentation/devicetree/bindings/dma/img,pistachio-mdc-dma.yaml
>  delete mode 100644 Documentation/devicetree/bindings/dma/img-mdc-dma.txt
> 
> diff --git a/Documentation/devicetree/bindings/dma/img,pistachio-mdc-dma.yaml b/Documentation/devicetree/bindings/dma/img,pistachio-mdc-dma.yaml
> new file mode 100644
> index 000000000000..198e80b528c8
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/dma/img,pistachio-mdc-dma.yaml
> @@ -0,0 +1,89 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/dma/img,pistachio-mdc-dma.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: IMG Multi-threaded DMA Controller (MDC)
> +
> +maintainers:
> +  - Rahul Bedarkar <rahulbedarkar89@gmail.com>
> +  - linux-mips@vger.kernel.org
> +
> +allOf:
> +  - $ref: /schemas/dma/dma-controller.yaml#
> +
> +properties:
> +  compatible:
> +    const: img,pistachio-mdc-dma
> +
> +  reg:
> +    maxItems: 1
> +
> +  interrupts:
> +    minItems: 1
> +    maxItems: 32

Nothing improved, so with vague commit msg it means you just ignored my
comment.

Best regards,
Krzysztof

Re: [PATCH v3] dt-bindings: dma: img-mdc-dma: convert to DT schema

[Nino Zhang]

On Fri, 29 Aug 2025 09:53:43 +0200 Krzysztof Kozlowski wrote:
> > Convert the img-mdc-dma binding from txt to YAML schema.
> > No functional changes except dropping the consumer node
> > (spi@18100f00) from the example, which belongs to the
> > consumer binding instead.
> > 
> > Signed-off-by: Nino Zhang <ninozhang001@gmail.com>
> > ---
> > v2 -> v3:
> > - Fix remaining issues based on Rob's and Krzysztof's comments.
> 
> That's vague. What exactly did you change?
> 
> Especially that this is not true. You never responded to comments, never
> implemented them.

Hi, Krzysztof,

You're right — my v3 changelog was too vague, and I should have replied
in this thread. Sorry about that.

For the record, my earlier, detailed replies were in the previous
threads:
Link: https://lore.kernel.org/all/20250824185543.475785-1-ninozhang001@gmail.com/

To summarise the concrete changes:
v2->v3:
- Ensured patches are not attached to unrelated/older threads.
- Dropped redundant '|' or '>' indicators in "description" fields.
- Dropped explicit "type" definition for "dma-channels" property.

v1->v2:
- Removed "Tested with 'make dt_binding_check'" from commit message.
- Renamed file to use the compatible string.
- Updated maintainers to Rahul Bedarkar and linux-mips@vger.kernel.org.
- Cleaned up redundant descriptions.
- Changed "minItems: 1" to "maxItems: 1" for "reg".
- Added "minItems: 1" and "maxItems: 32" for "interrupts".
- Added "maxItems: 1" for "clocks".
- Specified exact "clock-names" list with "items: - const: sys".
- Dropped redundant '|' indicators in descriptions.
- Added "minimum: 1" for "img,max-burst-multiplier".
- Removed unnecessary quotes in "required" section.
- Renamed example node "mdc: dma-controller@18143000" to "dma-controller@18143000".

If I still missed anything from your/Rob's comments, I'll fix it and
send a v4 shortly with:
- an explicit "Changes in v4" section in the commit message,
- inline replies in this thread to each point.

Thanks for pointing this out.

Best regards,
Nino