The AST2600 I2C controller supports three transfer modes: byte,
buffer, and DMA. To allow board designers and firmware to
explicitly select the preferred transfer mode for each controller
instance. "aspeed,transfer-mode" to allow device tree to specify
the desired transfer method used by each I2C controller instance.

And AST2600 i2c controller have two register mode, one is legacy
register layout which is mix controller/target register control
together, another is new mode which is separate controller/target
register control.

Signed-off-by: Ryan Chen <ryan_chen@aspeedtech.com>
---
 .../devicetree/bindings/i2c/ast2600-i2c.yaml  | 32 ++++++++++++++++++-
 1 file changed, 31 insertions(+), 1 deletion(-)

diff --git a/Documentation/devicetree/bindings/i2c/ast2600-i2c.yaml b/Documentation/devicetree/bindings/i2c/ast2600-i2c.yaml
index 6ddcec5decdc..9fd6976cd622 100644
--- a/Documentation/devicetree/bindings/i2c/ast2600-i2c.yaml
+++ b/Documentation/devicetree/bindings/i2c/ast2600-i2c.yaml
@@ -42,11 +42,39 @@ properties:
     description: frequency of the bus clock in Hz defaults to 100 kHz when not
       specified
 
+  aspeed,transfer-mode:
+    description: |
+      ASPEED ast2600 platform equipped with 16 I2C controllers each i2c controller
+      have 1 byte transfer buffer(byte mode), 32 bytes buffer(buffer mode), and
+      share a DMA engine.
+      Select I2C transfer mode for this controller. Supported values are:
+        - "byte": Use 1 byte for i2c transmit (1-byte buffer).
+        - "buffer": Use buffer (32-byte buffer) for i2c transmit. (default)
+                    Better performance then byte mode.
+        - "dma": Each controller DMA mode is shared DMA engine. The AST2600 SoC
+                 provides a single DMA engine shared for 16 I2C controllers,
+                 so only a limited number of controllers can use DMA simultaneously.
+                 Therefore, the DTS must explicitly assign which controllers are
+                 configured to use DMA.
+      On AST2600, each controller supports all three modes.
+      If not specified, buffer mode is used by default.
+    enum:
+      - byte
+      - buffer
+      - dma
+
+  aspeed,global-regs:
+    $ref: /schemas/types.yaml#/definitions/phandle
+    description:
+      Phandle reference to the i2c global syscon node, containing the
+      SoC-common i2c register set.
+
 required:
   - reg
   - compatible
   - clocks
   - resets
+  - aspeed,global-regs
 
 unevaluatedProperties: false
 
@@ -57,10 +85,12 @@ examples:
       #address-cells = <1>;
       #size-cells = <0>;
       compatible = "aspeed,ast2600-i2c-bus";
-      reg = <0x40 0x40>;
+      reg = <0x80 0x80>, <0xc00 0x20>;
+      aspeed,global-regs = <&i2c_global>;
       clocks = <&syscon ASPEED_CLK_APB>;
       resets = <&syscon ASPEED_RESET_I2C>;
       bus-frequency = <100000>;
       interrupts = <0>;
       interrupt-parent = <&i2c_ic>;
+      aspeed,transfer-mode = "buffer";
     };
-- 
2.34.1

On 27/10/2025 07:12, Ryan Chen wrote:
> The AST2600 I2C controller supports three transfer modes: byte,
> buffer, and DMA. To allow board designers and firmware to
> explicitly select the preferred transfer mode for each controller
> instance. "aspeed,transfer-mode" to allow device tree to specify
> the desired transfer method used by each I2C controller instance.
> 
> And AST2600 i2c controller have two register mode, one is legacy
> register layout which is mix controller/target register control
> together, another is new mode which is separate controller/target
> register control.
> 

This implies your "reg" properties have now completely different meaning
and this would be quite an ABI break. We discussed this probably 15
revisions ago. Where did you document the resolution of that discussion?

>  
>  unevaluatedProperties: false
>  
> @@ -57,10 +85,12 @@ examples:
>        #address-cells = <1>;
>        #size-cells = <0>;
>        compatible = "aspeed,ast2600-i2c-bus";
> -      reg = <0x40 0x40>;
> +      reg = <0x80 0x80>, <0xc00 0x20>;

Not relevant to this patch. You just added this line in patch #1, so did
you add incorrect code just to fix it right away?

No, fix your example when creating it.


Best regards,
Krzysztof

On Mon, Oct 27, 2025 at 08:14:45PM +0100, Krzysztof Kozlowski wrote:
> On 27/10/2025 07:12, Ryan Chen wrote:
> > The AST2600 I2C controller supports three transfer modes: byte,
> > buffer, and DMA. To allow board designers and firmware to
> > explicitly select the preferred transfer mode for each controller
> > instance. "aspeed,transfer-mode" to allow device tree to specify
> > the desired transfer method used by each I2C controller instance.
> > 
> > And AST2600 i2c controller have two register mode, one is legacy
> > register layout which is mix controller/target register control
> > together, another is new mode which is separate controller/target
> > register control.
> > 
> 
> This implies your "reg" properties have now completely different meaning
> and this would be quite an ABI break. We discussed this probably 15
> revisions ago. Where did you document the resolution of that discussion?
> 
> >  
> >  unevaluatedProperties: false
> >  
> > @@ -57,10 +85,12 @@ examples:
> >        #address-cells = <1>;
> >        #size-cells = <0>;
> >        compatible = "aspeed,ast2600-i2c-bus";
> > -      reg = <0x40 0x40>;
> > +      reg = <0x80 0x80>, <0xc00 0x20>;
> 
> Not relevant to this patch. You just added this line in patch #1, so did
> you add incorrect code just to fix it right away?
> 
> No, fix your example when creating it.

Heh, and this was not even tested... you have warnings here (see
maintainer soc profiles).

Best regards,
Krzysztof