[PATCH v2 1/3] ASoC: dt-bindings: rk3308-codec: describe detection and ADC routing

[Xing Zheng <zhengxing@rock-chips.com>]

Describe the optional detect-GRF phandle and named interrupt resources
used by the B/C headphone detector. Retain the legacy interrupt order
and index-based lookup when names are absent. Document the detector
disable and reversed-jack properties and their resource dependencies.

Describe the ADC stereo-group routing consumed by the codec driver.
Require four unique group IDs in the range 0-3, in I2S2 SDI order,
matching the driver's validation. Leave GRF routing unchanged when
the property is absent.

Extend the example with headphone-detection resources and ADC routing.
Keep machine-driver amplifier GPIOs and debug interfaces outside this
codec binding.

Signed-off-by: Xing Zheng <zhengxing@rock-chips.com>
---
Changes in v2:
- Retain the original detection descriptions and legacy IRQ ordering.
- Keep the binding change in its own patch before the codec change.

 .../bindings/sound/rockchip,rk3308-codec.yaml | 55 +++++++++++++++++++
 1 file changed, 55 insertions(+)

diff --git a/Documentation/devicetree/bindings/sound/rockchip,rk3308-codec.yaml b/Documentation/devicetree/bindings/sound/rockchip,rk3308-codec.yaml
index 2cf229a076f0..60c6140dc5df 100644
--- a/Documentation/devicetree/bindings/sound/rockchip,rk3308-codec.yaml
+++ b/Documentation/devicetree/bindings/sound/rockchip,rk3308-codec.yaml
@@ -36,6 +36,49 @@ properties:
     description:
       Phandle to the General Register Files (GRF)
 
+  rockchip,detect-grf:
+    $ref: /schemas/types.yaml#/definitions/phandle
+    description:
+      Phandle to the detection GRF used for headphone insertion and
+      removal interrupts on codec revisions B and C.
+
+  interrupts:
+    description:
+      Keep the legacy interrupt order. If interrupt-names is omitted,
+      the driver uses the second interrupt for B/C headphone detection.
+    items:
+      - description: Legacy codec headphone detection interrupt
+      - description: Detection GRF headphone interrupt for revisions B and C
+
+  interrupt-names:
+    items:
+      - const: codec
+      - const: hpdet
+
+  rockchip,no-hp-det:
+    type: boolean
+    description: Disable the internal headphone detector.
+
+  rockchip,hp-jack-reversed:
+    type: boolean
+    description: Reverse the headphone detection polarity.
+
+  rockchip,adc-grps-route:
+    $ref: /schemas/types.yaml#/definitions/uint32-array
+    description: |
+      ADC stereo-group mapping to the four I2S2 SDI inputs. Each entry
+      selects the ADC group connected to the corresponding SDI input,
+      in SDI0 through SDI3 order. Group IDs 0 through 3 represent
+      MIC1/MIC2, MIC3/MIC4, MIC5/MIC6 and MIC7/MIC8 respectively.
+      All four groups must appear exactly once. For example, <1 2 3 0>
+      connects groups 1, 2, 3 and 0 to SDI0, SDI1, SDI2 and SDI3.
+      If omitted, the GRF routing is left unchanged.
+    minItems: 4
+    maxItems: 4
+    uniqueItems: true
+    items:
+      enum: [ 0, 1, 2, 3 ]
+
   clocks:
     items:
       - description: clock for TX
@@ -72,6 +115,12 @@ properties:
 
     enum: [ 50, 55, 60, 65, 70, 75, 80, 85 ]
 
+dependentRequired:
+  rockchip,detect-grf:
+    - interrupts
+  interrupt-names:
+    - interrupts
+
 required:
   - compatible
   - reg
@@ -85,11 +134,17 @@ additionalProperties: false
 examples:
   - |
     #include <dt-bindings/clock/rk3308-cru.h>
+    #include <dt-bindings/interrupt-controller/arm-gic.h>
 
     audio_codec: audio-codec@ff560000 {
         compatible = "rockchip,rk3308-codec";
         reg = <0xff560000 0x10000>;
         rockchip,grf = <&grf>;
+        rockchip,detect-grf = <&detect_grf>;
+        interrupts = <GIC_SPI 114 IRQ_TYPE_LEVEL_HIGH>,
+                     <GIC_SPI 115 IRQ_TYPE_LEVEL_HIGH>;
+        interrupt-names = "codec", "hpdet";
+        rockchip,adc-grps-route = <1 2 3 0>;
         clock-names = "mclk_tx", "mclk_rx", "hclk";
         clocks = <&cru SCLK_I2S2_8CH_TX_OUT>,
                  <&cru SCLK_I2S2_8CH_RX_OUT>,