[RFC PATCH 7/8] dt-bindings: sound: qcom: add Tambora WCD9378 SDCA codec

[Srinivas Kandagatla]

Describe the WCD9378 SDCA peripheral node (compatible sdw20217011000)
driven by the wcd9378-sdca codec driver for headphone playback, headset
mic capture and jack detection via the SimpleJack SDCA function type.

WCD9378 codec can be wired up in 2 different modes.
"mobile mode" on phone/tablet SoCs is enumerated as tx and rx device,
each of which has dedicated control and data lines.
"compute mode" on compute platforms such as Glymur is enumerated as
single standard MIPI SDCA class device.

Both modes share same Device ID, compatible; qcom,compute-mode selects
which driver path is taken.  Supplies, reset GPIO and mic-bias voltages
live on the SoundWire slave node in compute mode and are forbidden in
mobile mode (owned by the top-level codec parent there).

Assisted-by: Claude:claude-opus-4-7
Signed-off-by: Srinivas Kandagatla <srinivas.kandagatla@xxxxxxxxxxxxxxxx>
---
 .../bindings/sound/qcom,wcd9378-sdw.yaml      | 200 ++++++++++++++++++
 1 file changed, 200 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/sound/qcom,wcd9378-sdw.yaml

diff --git a/Documentation/devicetree/bindings/sound/qcom,wcd9378-sdw.yaml b/Documentation/devicetree/bindings/sound/qcom,wcd9378-sdw.yaml
new file mode 100644
index 000000000000..2ed4ad92958e
--- /dev/null
+++ b/Documentation/devicetree/bindings/sound/qcom,wcd9378-sdw.yaml
@@ -0,0 +1,200 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/sound/qcom,wcd9378-sdw.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Qualcomm SoundWire Slave devices on WCD9378
+
+maintainers:
+  - Jorijn van der Graaf <jorijnvdgraaf@xxxxxxxxxxxxx>
+  - Srinivas Kandagatla <srinivas.kandagatla@xxxxxxxxxxxxxxxx>
+
+description: |
+  The Qualcomm WCD9378 codec presents its SoundWire slave devices with
+  class ID sdw20217011000 in both operating modes:
+
+    * mobile mode -- two slave instances sit on separate SoundWire
+      masters carrying data only.  A separate top-level codec node
+      owns the codec's supplies, mic-bias voltages and reset GPIO.
+
+    * SDCA / compute mode -- one aggregated slave sits on a multi-lane
+      master and carries both control and data.  There is no separate
+      top-level codec node, so the SoundWire slave node itself owns
+      supplies, reset GPIO and mic-bias voltage configuration.  It is
+      marked with qcom,compute-mode.
+
+  Codec drivers that match sdw20217011000 use qcom,compute-mode to
+  decide which mode to serve; the presence or absence of this property
+  also gates whether the supply and mic-bias properties on this node
+  are required or forbidden.
+
+properties:
+  compatible:
+    const: sdw20217011000
+
+  reg:
+    maxItems: 1
+
+  qcom,compute-mode:
+    description: |
+      Marks this SoundWire slave as the single aggregated slave that
+      implements the codec in SDCA / compute mode.  Only present when
+      the codec has no separate top-level codec parent; in that case
+      this slave node also owns the codec's supplies, reset GPIO and
+      mic-bias voltage configuration.  Absent in mobile mode.
+    type: boolean
+
+  qcom,port-mapping:
+    description: |
+      Static mapping between codec SoundWire peripheral ports and master
+      ports on the SoundWire bus.  Length and interpretation depend on
+      the slave's role as fixed by the parent codec node:
+
+        mobile (5 entries): the mobile-mode driver derives direction
+            (RX / TX) from its own context (parent phandle from the
+            top-level codec node, or the presence of
+            qcom,tx-port-mapping / qcom,rx-port-mapping on other slaves
+            in that binding).
+        SDCA (7 entries):   DP1..DP7 aggregated on the single slave
+            (index 0 unused).
+    $ref: /schemas/types.yaml#/definitions/uint32-array
+    minItems: 5
+    maxItems: 8
+
+  reset-gpios:
+    description: |
+      SDCA / compute mode only.  GPIO used to release the codec from
+      reset.  Active-low.
+    maxItems: 1
+
+  vdd-buck-supply:
+    description: SDCA / compute mode only.  1.8 V analog buck supply.
+
+  vdd-rxtx-supply:
+    description: SDCA / compute mode only.  1.8 V RX/TX supply.
+
+  vdd-io-supply:
+    description: SDCA / compute mode only.  Digital I/O supply.
+
+  vdd-mic-bias-supply:
+    description: SDCA / compute mode only.  Mic bias supply.
+
+  qcom,micbias1-microvolt:
+    description: SDCA / compute mode only.  MICB1 rail voltage in microvolts.
+    minimum: 1800000
+    maximum: 2850000
+
+  qcom,micbias2-microvolt:
+    description: |
+      SDCA / compute mode only.  MICB2 rail voltage in microvolts.
+      Used by the SDCA SimpleJack headset-mic input (IT33 / AMIC2).
+    minimum: 1800000
+    maximum: 2850000
+
+  qcom,micbias3-microvolt:
+    description: SDCA / compute mode only.  MICB3 rail voltage in microvolts.
+    minimum: 1800000
+    maximum: 2850000
+
+  '#sound-dai-cells':
+    const: 1
+
+required:
+  - compatible
+  - reg
+  - qcom,port-mapping
+  - '#sound-dai-cells'
+
+allOf:
+  # qcom,compute-mode gates the standalone-slave shape: supplies, reset
+  # and mic-bias voltages live on this node in compute mode and are
+  # forbidden in mobile mode (owned by the top-level codec parent there).
+  - if:
+      required:
+        - qcom,compute-mode
+    then:
+      required:
+        - vdd-buck-supply
+        - vdd-rxtx-supply
+        - vdd-io-supply
+        - vdd-mic-bias-supply
+        - qcom,micbias1-microvolt
+        - qcom,micbias2-microvolt
+        - qcom,micbias3-microvolt
+    else:
+      properties:
+        vdd-buck-supply: false
+        vdd-rxtx-supply: false
+        vdd-io-supply: false
+        vdd-mic-bias-supply: false
+        qcom,micbias1-microvolt: false
+        qcom,micbias2-microvolt: false
+        qcom,micbias3-microvolt: false
+        reset-gpios: false
+
+additionalProperties: false
+
+examples:
+  # Mobile mode: two SoundWire slaves on separate masters.  Neither
+  # carries supplies or mic-bias -- the top-level codec parent owns
+  # those.
+  - |
+    soundwire@3210000 {
+        reg = <0x03210000 0x2000>;
+        #address-cells = <2>;
+        #size-cells = <0>;
+
+        wcd9378_rx: audio-codec@0,4 {
+            compatible = "sdw20217011000";
+            reg = <0 4>;
+            qcom,port-mapping = <1 2 3 4 5>;
+            #sound-dai-cells = <1>;
+        };
+    };
+
+    soundwire@33b0000 {
+        reg = <0x033b0000 0x2000>;
+        #address-cells = <2>;
+        #size-cells = <0>;
+
+        wcd9378_tx: audio-codec@0,3 {
+            compatible = "sdw20217011000";
+            reg = <0 3>;
+            qcom,port-mapping = <1 1 1 2 3>;
+            #sound-dai-cells = <1>;
+        };
+    };
+
+  # SDCA / compute mode: single aggregated slave -- owns supplies,
+  # reset GPIO and mic-bias voltages.
+  - |
+    #include <dt-bindings/gpio/gpio.h>
+
+    soundwire@7630000 {
+        reg = <0x07630000 0x10000>;
+        #address-cells = <2>;
+        #size-cells = <0>;
+
+        wcd9378c_sdw: audio-codec@3,0 {
+            compatible = "sdw20217011000";
+            reg = <0 3>;
+
+            qcom,compute-mode;
+            qcom,port-mapping = <2 2 3 4 5 6 7 8>;
+
+            reset-gpios = <&tlmm 191 GPIO_ACTIVE_LOW>;
+
+            vdd-buck-supply = <&vreg_l15b_1p8>;
+            vdd-rxtx-supply = <&vreg_l15b_1p8>;
+            vdd-io-supply = <&vreg_l18b_1p2>;
+            vdd-mic-bias-supply = <&vreg_bob1>;
+
+            qcom,micbias1-microvolt = <1800000>;
+            qcom,micbias2-microvolt = <2750000>;
+            qcom,micbias3-microvolt = <1800000>;
+
+            #sound-dai-cells = <1>;
+        };
+    };
+...
-- 
2.53.0