[PATCH 1/8] dt-bindings: i3c: Document the AST2700 I3C controller

[Billy Tsai]

The AST2700 I3C controller implements the MIPI I3C HCI programming
model, extended with an ASPEED in-house control block and a PHY
programming window advertised through an HCI vendor extended
capability. Follow the existing aspeed,ast2600-i3c precedent of
describing SoC integrations of a common I3C IP in their own schema.

The controller takes a core clock for PHY timing and two reset-names
lines: its own reset and a DMA engine reset shared by all I3C
controllers on the SoC.

The PHY timings derived from the core clock and bus rate assume
nominal bus loading. Boards with long traces, weak pull-ups, or
capacitive loading need different ratios and setup periods, so
document properties to override the push-pull and open-drain SCL
periods, the SDA TX hold time, the tCAS/tCBP periods, and the SCL low
period used for a repeated START or STOP.

Boards without external I3C pull-up resistors can use the PHY's
built-in pull-ups instead. The achievable resistance depends on the
voltage domain of the pins (high-voltage vs low-voltage), which can be
determined from the pin group assigned to the bus. Reuse bias-pull-up
(pincfg-node.yaml) for the strength in Ohms; it is declared on this
node rather than a pin-config node since the pull-up switch is part of
the I3C PHY, not the broader SoC pin control IPs.

Signed-off-by: Billy Tsai <billy_tsai@xxxxxxxxxxxxxx>
Assisted-by: Claude:claude-fable-5

---
We considered formally expressing bias-pull-up's dependency on a
pinctrl state in the schema, but couldn't find a clean way to say
"depends on whichever pinctrl-N is active" without hard-coding
pinctrl-0 specifically, which would be wrong in general (a node's
active pin state doesn't have to sit at index 0). We've added
pinctrl-0 to the example to illustrate the typical usage instead,
without a formal schema-level dependency.
---
 .../bindings/i3c/aspeed,ast2700-i3c-hci.yaml       | 133 +++++++++++++++++++++
 1 file changed, 133 insertions(+)

diff --git a/Documentation/devicetree/bindings/i3c/aspeed,ast2700-i3c-hci.yaml b/Documentation/devicetree/bindings/i3c/aspeed,ast2700-i3c-hci.yaml
new file mode 100644
index 000000000000..19ecb5b15038
--- /dev/null
+++ b/Documentation/devicetree/bindings/i3c/aspeed,ast2700-i3c-hci.yaml
@@ -0,0 +1,133 @@
+# SPDX-License-Identifier: GPL-2.0 OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i3c/aspeed,ast2700-i3c-hci.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ASPEED AST2700 I3C controller
+
+maintainers:
+  - Billy Tsai <billy_tsai@xxxxxxxxxxxxxx>
+
+description:
+  The AST2700 I3C controller implements the MIPI I3C HCI programming model,
+  extended with an ASPEED in-house control block and a PHY programming window
+  that are advertised through an HCI vendor extended capability.
+
+properties:
+  compatible:
+    const: aspeed,ast2700-i3c-hci
+
+  reg:
+    maxItems: 1
+
+  interrupts:
+    maxItems: 1
+
+  clocks:
+    maxItems: 1
+
+  resets:
+    items:
+      - description: Core controller reset.
+      - description: DMA engine reset shared by all I3C controllers.
+
+  reset-names:
+    items:
+      - const: core
+      - const: dma
+
+  bias-pull-up:
+    $ref: /schemas/pinctrl/pincfg-node.yaml#/properties/bias-pull-up
+    enum: [177, 231, 261, 317, 400, 470, 550, 600, 750]
+    description:
+      Enable the PHY-internal pull-ups on SCL and SDA and select their
+      strength, in Ohms. High-voltage pins support 400, 470 or 600 Ohms,
+      and low-voltage pins support 177, 231, 261, 317, 400, 550 or 750
+      Ohms. When absent the internal pull-ups stay disabled and the bus
+      relies on external pull-ups.
+
+  aspeed,pp-scl-high-ns:
+    description:
+      Push-pull SCL high period. Overrides the value derived from the
+      i3c-scl-hz bus rate.
+
+  aspeed,pp-scl-low-ns:
+    description:
+      Push-pull SCL low period. Overrides the value derived from the
+      i3c-scl-hz bus rate.
+
+  aspeed,od-scl-high-ns:
+    default: 380
+    description:
+      Open-drain SCL high period.
+
+  aspeed,od-scl-low-ns:
+    default: 620
+    description:
+      Open-drain SCL low period.
+
+  aspeed,sda-tx-hold-ns:
+    default: 10
+    description:
+      SDA output hold time relative to the SCL edge.
+
+  aspeed,cas-ns:
+    minimum: 39
+    description:
+      Clock-after-start (tCAS) period driven after a START condition.
+      When absent it is derived from the SCL low period of the
+      applicable bus context, clamped to the protocol minimum.
+
+  aspeed,cbp-ns:
+    minimum: 20
+    description:
+      Clock-before-stop (tCBP) period driven before a STOP condition.
+      When absent it is derived from the SCL low period of the
+      applicable bus context, clamped to the protocol minimum.
+
+  aspeed,sr-p-scl-low-ns:
+    default: 40
+    description:
+      SCL low period used while preparing a repeated START or STOP
+      condition, kept separate from the push-pull SCL low period to
+      satisfy the MIPI I3C clock stalling requirements.
+
+dependencies:
+  aspeed,pp-scl-high-ns:
+    - aspeed,pp-scl-low-ns
+  aspeed,pp-scl-low-ns:
+    - aspeed,pp-scl-high-ns
+  aspeed,od-scl-high-ns:
+    - aspeed,od-scl-low-ns
+  aspeed,od-scl-low-ns:
+    - aspeed,od-scl-high-ns
+
+required:
+  - compatible
+  - reg
+  - interrupts
+  - clocks
+  - resets
+  - reset-names
+
+allOf:
+  - $ref: i3c.yaml#
+
+unevaluatedProperties: false
+
+examples:
+  - |
+    i3c@14c24000 {
+        compatible = "aspeed,ast2700-i3c-hci";
+        reg = <0x14c24000 0x1000>;
+        interrupts = <100>;
+        clocks = <&syscon 20>;
+        resets = <&syscon 37>, <&syscon 34>;
+        reset-names = "core", "dma";
+        bias-pull-up = <400>;
+        pinctrl-names = "default";
+        pinctrl-0 = <&pinctrl_i3c4_default>;
+        #address-cells = <3>;
+        #size-cells = <0>;
+    };

-- 
2.34.1