[PATCH 04/22] dt-bindings: dma: renesas,rz-dmac: Document optional DMA ACK cell

[John Madieu]

Some peripherals on RZ/V2H, RZ/V2N, and RZ/G3E SoCs require explicit
ACK signal routing through the ICU. Document the optional second cell
in the DMA specifier for specifying the ACK signal number.

The first cell remains unchanged and specifies the encoded MID/RID and
channel configuration. The optional second cell specifies the DMA ACK
signal number for peripherals requiring level-based handshaking.

Signed-off-by: John Madieu <john.madieu.xa@xxxxxxxxxxxxxx>
---
 .../bindings/dma/renesas,rz-dmac.yaml         | 28 +++++++++++++++++--
 1 file changed, 26 insertions(+), 2 deletions(-)

diff --git a/Documentation/devicetree/bindings/dma/renesas,rz-dmac.yaml b/Documentation/devicetree/bindings/dma/renesas,rz-dmac.yaml
index 0155a15e200b..f3966c288890 100644
--- a/Documentation/devicetree/bindings/dma/renesas,rz-dmac.yaml
+++ b/Documentation/devicetree/bindings/dma/renesas,rz-dmac.yaml
@@ -63,17 +63,27 @@ properties:
       - const: register
 
   '#dma-cells':
-    const: 1
-    description:
+    description: |
       The cell specifies the encoded MID/RID or the REQ No values of
       the DMAC port connected to the DMA client and the slave channel
       configuration parameters.
+      Use 1 cell for basic DMA configuration.
+      Use 2 cells when DMA ACK signal routing through ICU is required
+      (RZ/V2H, RZ/V2N, RZ/G3E audio peripherals such as SSIU, SPDIF, SRC, DVC).
+
+      First cell:
       bits[0:9] - Specifies the MID/RID or the REQ No value
       bit[10] - Specifies DMA request high enable (HIEN)
       bit[11] - Specifies DMA request detection type (LVL)
       bits[12:14] - Specifies DMAACK output mode (AM)
       bit[15] - Specifies Transfer Mode (TM)
 
+      Second cell (optional, when #dma-cells = <2>):
+      bits[6:0] - DMA acknowledge signal number (from ICU ACK table),
+                  where 0 is a valid signal number.
+                  Required for peripherals using level-based DMA
+                  handshaking (SSIU, SPDIF, RSPI, SCU, ADC, PDM).
+
   dma-channels:
     const: 16
 
@@ -212,6 +222,20 @@ allOf:
         - renesas,icu
         - resets
 
+  - if:
+      properties:
+        compatible:
+          contains:
+            const: renesas,r9a09g057-dmac
+    then:
+      properties:
+        '#dma-cells':
+          enum: [1, 2]
+    else:
+      properties:
+        '#dma-cells':
+          const: 1
+
   - if:
       properties:
         compatible:
-- 
2.25.1