[PATCH v2 1/2] dt-bindings: i3c: add Realtek RTS490x I3C HUB

[zain_zhou]

From: Yin Zhou <zain_zhou@xxxxxxxxxxxxxx>

Add DT binding schema for Realtek RTS490x series I3C HUB devices.

The binding describes configuration properties for:
  - LDO enable/disable and voltage level per port group
  - Pull-up resistance per port group
  - IO driver strength per port
  - Per target-port mode (I3C/SMBus/GPIO/disabled), pull-up,
    IO mode, SMBus clock frequency and polling interval
  - Hub network always-I3C mode
  - Hardware identification via CSEL pin (id) and CP1 pins (id-cp1)

Signed-off-by: Yin Zhou <zain_zhou@xxxxxxxxxxxxxx>

Changes in v2:
- Rework binding per Krzysztof Kozlowski's review:
  add realtek, vendor prefix to all custom properties; use boolean
  for enable flags; use u32 with unit suffixes (-microvolt, -ohms)
  for voltage/resistance; change to unevaluatedProperties: false;
  fix title, maintainer name, description, $nodename pattern
- Consolidate examples; add dt-bindings/i2c/i2c.h include
---
 .../bindings/i3c/realtek,rts490x-i3c-hub.yaml | 263 ++++++++++++++++++
 1 file changed, 263 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/i3c/realtek,rts490x-i3c-hub.yaml

diff --git a/Documentation/devicetree/bindings/i3c/realtek,rts490x-i3c-hub.yaml b/Documentation/devicetree/bindings/i3c/realtek,rts490x-i3c-hub.yaml
new file mode 100644
index 000000000000..851a433abcd3
--- /dev/null
+++ b/Documentation/devicetree/bindings/i3c/realtek,rts490x-i3c-hub.yaml
@@ -0,0 +1,263 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i3c/realtek,rts490x-i3c-hub.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Realtek RTS490x I3C HUB
+
+maintainers:
+  - Yin Zhou <zain_zhou@xxxxxxxxxxxxxx>
+
+description:
+  The Realtek RTS490x is an I3C HUB device that provides voltage level
+  translation between I3C controller and target devices, bus capacitance
+  isolation, address conflict isolation, I3C port expansion (up to 8
+  target ports), simultaneous dual-controller port support, and per-port
+  mode selection (I3C, SMBus, GPIO, or disabled).
+
+properties:
+  $nodename:
+    pattern: "^hub@[0-9a-f]+(,[0-9a-f]+)*$"
+
+  compatible:
+    const: realtek,rts490x-i3c-hub
+
+  reg:
+    maxItems: 1
+    description:
+      Encodes the static I2C address, manufacturer ID, and part/instance ID
+      as defined by the I3C specification.
+
+  assigned-address:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    minimum: 0x1
+    maximum: 0xff
+    description:
+      Dynamic I3C address to assign to this device.
+
+  dcr:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    description:
+      Device Characteristic Register value of the hub.
+
+  "#address-cells":
+    const: 1
+
+  "#size-cells":
+    const: 0
+
+  realtek,cp0-ldo-enable:
+    type: boolean
+    description:
+      Enable the on-die LDO for Controller Port 0.
+
+  realtek,cp1-ldo-enable:
+    type: boolean
+    description:
+      Enable the on-die LDO for Controller Port 1.
+
+  realtek,tp0145-ldo-enable:
+    type: boolean
+    description:
+      Enable the on-die LDO for Target Ports 0/1/4/5.
+
+  realtek,tp2367-ldo-enable:
+    type: boolean
+    description:
+      Enable the on-die LDO for Target Ports 2/3/6/7.
+
+  realtek,cp0-ldo-microvolt:
+    enum: [1000000, 1100000, 1200000, 1800000]
+    description:
+      Output voltage of the Controller Port 0 on-die LDO, in microvolts.
+
+  realtek,cp1-ldo-microvolt:
+    enum: [1000000, 1100000, 1200000, 1800000]
+    description:
+      Output voltage of the Controller Port 1 on-die LDO, in microvolts.
+
+  realtek,tp0145-ldo-microvolt:
+    enum: [1000000, 1100000, 1200000, 1800000]
+    description:
+      Output voltage of the Target Ports 0/1/4/5 on-die LDO, in
+      microvolts.
+
+  realtek,tp2367-ldo-microvolt:
+    enum: [1000000, 1100000, 1200000, 1800000]
+    description:
+      Output voltage of the Target Ports 2/3/6/7 on-die LDO, in
+      microvolts.
+
+  realtek,tp0145-pullup-ohms:
+    enum: [0, 250, 500, 1000, 2000]
+    description:
+      Pull-up resistance for Target Ports 0/1/4/5, in ohms. 0 disables
+      the pull-up.
+
+  realtek,tp2367-pullup-ohms:
+    enum: [0, 250, 500, 1000, 2000]
+    description:
+      Pull-up resistance for Target Ports 2/3/6/7, in ohms. 0 disables
+      the pull-up.
+
+  realtek,cp0-io-strength-ohms:
+    enum: [20, 30, 40, 50]
+    description:
+      Output driver impedance for Controller Port 0, in ohms.
+
+  realtek,cp1-io-strength-ohms:
+    enum: [20, 30, 40, 50]
+    description:
+      Output driver impedance for Controller Port 1, in ohms.
+
+  realtek,tp0145-io-strength-ohms:
+    enum: [20, 30, 40, 50]
+    description:
+      Output driver impedance for Target Ports 0/1/4/5, in ohms.
+
+  realtek,tp2367-io-strength-ohms:
+    enum: [20, 30, 40, 50]
+    description:
+      Output driver impedance for Target Ports 2/3/6/7, in ohms.
+
+  realtek,id:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    enum: [0, 1, 3]
+    description: |
+      I3C HUB hardware ID based on CSEL pin state. Values:
+        0 - CP0 is selected as primary Controller Port
+        1 - Primary Controller Port selected by software
+        3 - CP1 is selected as primary Controller Port
+
+  realtek,id-cp1:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    enum: [0, 1, 2, 3]
+    description:
+      I3C HUB hardware ID based on CP1 SDA and SCL pin state probed
+      during power-on.
+
+patternProperties:
+  "^target-port@[0-9]+$":
+    type: object
+    description:
+      I3C HUB target port child node, named target-port@<id>.
+
+    properties:
+      compatible:
+        const: realtek,rts490x-i3c-hub-port
+
+      reg:
+        maxItems: 1
+        description:
+          Target port index (0-based).
+
+      "#address-cells":
+        const: 1
+
+      "#size-cells":
+        const: 0
+
+      realtek,mode:
+        enum: [disabled, i3c, smbus, gpio]
+        description:
+          Operating mode of this target port.
+
+      realtek,pullup-enable:
+        type: boolean
+        description:
+          When present, enables the pull-up for this target port.
+
+      realtek,always-enable:
+        type: boolean
+        description:
+          When present, the target port is always enabled. Otherwise
+          the port is enabled on demand and disabled after use.
+
+      realtek,polling-interval-ms:
+        minimum: 0
+        description:
+          SMBus polling interval in milliseconds. If absent or 0,
+          polling is disabled and IBI is used instead.
+
+      clock-frequency:
+        enum: [100000, 200000, 400000, 1000000]
+        description:
+          SMBus clock frequency in Hz. Applies only when mode is smbus.
+          Defaults to 400000 if absent.
+
+    additionalProperties: true
+
+required:
+  - compatible
+  - reg
+
+unevaluatedProperties: false
+
+examples:
+  - |
+    #include <dt-bindings/i2c/i2c.h>
+    i3c-master@d040000 {
+      reg = <0xd040000 0x1000>;
+      #address-cells = <3>;
+      #size-cells = <0>;
+
+      hub@70,4ba00000000 {
+        compatible = "realtek,rts490x-i3c-hub";
+        reg = <0x70 0x4ba 0x00000000>;
+        assigned-address = <0x70>;
+        dcr = <0xc2>;
+        #address-cells = <1>;
+        #size-cells = <0>;
+
+        realtek,cp0-ldo-enable;
+        realtek,cp1-ldo-enable;
+        realtek,cp0-ldo-microvolt = <1000000>;
+        realtek,cp1-ldo-microvolt = <1100000>;
+        realtek,tp0145-ldo-enable;
+        realtek,tp0145-ldo-microvolt = <1200000>;
+        realtek,tp2367-ldo-microvolt = <1800000>;
+        realtek,tp0145-pullup-ohms = <2000>;
+        realtek,tp2367-pullup-ohms = <500>;
+        realtek,tp0145-io-strength-ohms = <50>;
+        realtek,tp2367-io-strength-ohms = <30>;
+        realtek,cp0-io-strength-ohms = <20>;
+        realtek,cp1-io-strength-ohms = <40>;
+
+        target-port@0 {
+          compatible = "realtek,rts490x-i3c-hub-port";
+          reg = <0>;
+          realtek,mode = "i3c";
+          realtek,pullup-enable;
+          realtek,always-enable;
+        };
+
+        target-port@1 {
+          compatible = "realtek,rts490x-i3c-hub-port";
+          reg = <1>;
+          #address-cells = <1>;
+          #size-cells = <0>;
+          realtek,mode = "smbus";
+          realtek,pullup-enable;
+          clock-frequency = <1000000>;
+          realtek,polling-interval-ms = <10>;
+
+          i2c@10 {
+            compatible = "i2c-slave-mqueue";
+            reg = <(0x10 | I2C_OWN_SLAVE_ADDRESS)>;
+          };
+        };
+
+        target-port@2 {
+          compatible = "realtek,rts490x-i3c-hub-port";
+          reg = <2>;
+          realtek,mode = "gpio";
+        };
+
+        target-port@3 {
+          compatible = "realtek,rts490x-i3c-hub-port";
+          reg = <3>;
+          realtek,mode = "disabled";
+        };
+      };
+    };
-- 
2.34.1