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

[Frank Li <Frank.li@oss.nxp.com>]

On Tue, Sep 01, 2026 at 07:35:28PM +0800, Billy Tsai wrote:
> 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.

look likes AI generated message, can you try keep short and avoid
duplicate information, which already in binding doc.

Add AST2700 I3C controller, which compatible with MIPI I3C HCI. Extend with
an ASPEED in-house control block ....

introduce some hardware feature here ...

>
> Signed-off-by: Billy Tsai <billy_tsai@aspeedtech.com>
> 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@aspeedtech.com>
> +
> +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.

this one should go through pinctrl.

> +
> +  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.


these value is i3c stardard defined value, why need put into dt-binding.

Frank
> +
> +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
>