[PATCH v2 1/9] dt-bindings: i3c: Document generic bus timing properties

[Billy Tsai]

The push-pull and open-drain SCL periods, push-pull SDA output hold
time, and the tCAS/tCBP periods around START and STOP conditions are
normally derived from i3c-scl-hz, but board-level trace length,
pull-up strength and capacitive loading can require different values
than what that derivation produces for a given board.

Document properties to override each of these independently, naming
them after the MIPI I3C Basic Specification v1.1.1 timing parameters
they adjust:

 - i3c-pp-scl-high-period-ns, i3c-pp-scl-low-period-ns
   tHIGH, tLOW: Table 87 (I3C Push-Pull Timing Parameters)

 - i3c-od-scl-high-period-ns, i3c-od-scl-low-period-ns
   tHIGH, tLOW_OD: Table 86 (I3C Open Drain Timing Parameters)

 - i3c-pp-sda-hold-ns
   tHD_PP: Table 87 (I3C Push-Pull Timing Parameters)

 - i3c-cas-period-ns, i3c-cbp-period-ns
   tCAS, tCBP: Table 86, Figures 144/145 (I3C Open Drain Timing
   Parameters). These carry the protocol minima as constraints.

 - i3c-sr-p-scl-low-period-ns
   The SCL low period held while a Controller stalls the clock in
   the T-Bit phase before a STOP or repeated START, per Section
   5.1.2.5 "Controller Clock Stalling" (Figures 19 and 20). The
   specification describes this requirement qualitatively and does
   not assign it a dedicated timing symbol, unlike the other
   properties above.

Any property left out keeps the derived default.

Signed-off-by: Billy Tsai <billy_tsai@xxxxxxxxxxxxxx>
---
 Documentation/devicetree/bindings/i3c/i3c.yaml | 86 ++++++++++++++++++++++++++
 1 file changed, 86 insertions(+)

diff --git a/Documentation/devicetree/bindings/i3c/i3c.yaml b/Documentation/devicetree/bindings/i3c/i3c.yaml
index 5603f2e7807d..30f65fd1afa7 100644
--- a/Documentation/devicetree/bindings/i3c/i3c.yaml
+++ b/Documentation/devicetree/bindings/i3c/i3c.yaml
@@ -57,6 +57,82 @@ properties:
 
       May not be supported by all controllers.
 
+  i3c-pp-scl-high-period-ns:
+    description: |
+      Push-pull SCL high period override, in nanoseconds (tHIGH, MIPI
+      I3C Basic Specification v1.1.1 Table 87). When undefined, the
+      value is derived from i3c-scl-hz.
+
+      May not be supported by all controllers.
+
+  i3c-pp-scl-low-period-ns:
+    description: |
+      Push-pull SCL low period override, in nanoseconds (tLOW, MIPI I3C
+      Basic Specification v1.1.1 Table 87). When undefined, the value is
+      derived from i3c-scl-hz.
+
+      May not be supported by all controllers.
+
+  i3c-od-scl-high-period-ns:
+    description: |
+      Open-drain SCL high period override, in nanoseconds (tHIGH, MIPI
+      I3C Basic Specification v1.1.1 Table 86). Open-drain timing is not
+      a function of i3c-scl-hz; when undefined, the controller uses its
+      own default.
+
+      May not be supported by all controllers.
+
+  i3c-od-scl-low-period-ns:
+    description: |
+      Open-drain SCL low period override, in nanoseconds (tLOW_OD, MIPI
+      I3C Basic Specification v1.1.1 Table 86). Open-drain timing is not
+      a function of i3c-scl-hz; when undefined, the controller uses its
+      own default.
+
+      May not be supported by all controllers.
+
+  i3c-pp-sda-hold-ns:
+    description: |
+      Push-pull SDA output hold time override relative to the SCL edge,
+      in nanoseconds (tHD_PP, MIPI I3C Basic Specification v1.1.1 Table
+      87). When undefined, the controller uses its own default.
+
+      May not be supported by all controllers.
+
+  i3c-cas-period-ns:
+    minimum: 39
+    description: |
+      Clock-after-start (tCAS) period override driven after a START
+      condition, in nanoseconds (MIPI I3C Basic Specification v1.1.1
+      Table 86, Figure 144). When absent it is derived from the SCL low
+      period of the applicable bus context, clamped to the protocol
+      minimum.
+
+      May not be supported by all controllers.
+
+  i3c-cbp-period-ns:
+    minimum: 20
+    description: |
+      Clock-before-stop (tCBP) period override driven before a STOP
+      condition, in nanoseconds (MIPI I3C Basic Specification v1.1.1
+      Table 86, Figure 145). When absent it is derived from the SCL low
+      period of the applicable bus context, clamped to the protocol
+      minimum.
+
+      May not be supported by all controllers.
+
+  i3c-sr-p-scl-low-period-ns:
+    description: |
+      SCL low period override used while extending (stalling) the clock
+      in the T-Bit phase before a STOP or repeated START condition, in
+      nanoseconds (MIPI I3C Basic Specification v1.1.1 Section 5.1.2.5
+      "Controller Clock Stalling", Figures 19 and 20; no dedicated
+      timing symbol is defined there). Kept separate from the push-pull
+      SCL low period to satisfy that requirement. When undefined, the
+      controller uses its own default.
+
+      May not be supported by all controllers.
+
   mctp-controller:
     type: boolean
     description: |
@@ -67,6 +143,16 @@ required:
   - "#address-cells"
   - "#size-cells"
 
+dependencies:
+  i3c-pp-scl-high-period-ns:
+    - i3c-pp-scl-low-period-ns
+  i3c-pp-scl-low-period-ns:
+    - i3c-pp-scl-high-period-ns
+  i3c-od-scl-high-period-ns:
+    - i3c-od-scl-low-period-ns
+  i3c-od-scl-low-period-ns:
+    - i3c-od-scl-high-period-ns
+
 patternProperties:
   "@[0-9a-f]+$":
     type: object

-- 
2.34.1