On Wed, Jun 18, 2025 at 05:45:22PM +0200, Krzysztof Kozlowski wrote:

On 18/06/2025 14:15, Jorge Marques wrote:

quoted

quoted

quoted

Signed-off-by: Jorge Marques <jorge.marques@analog.com>
---
 .../devicetree/bindings/i3c/adi,i3c-master.yaml    | 63 ++++++++++++++++++++++
 MAINTAINERS                                        |  5 ++
 2 files changed, 68 insertions(+)

diff --git a/Documentation/devicetree/bindings/i3c/adi,i3c-master.yaml b/Documentation/devicetree/bindings/i3c/adi,i3c-master.yaml
new file mode 100644
index 0000000000000000000000000000000000000000..718733bbb450c34c5d4924050cc6f85d8a80fe4b
--- /dev/null
+++ b/Documentation/devicetree/bindings/i3c/adi,i3c-master.yaml

Filename based on the compatible, so adi,i3c-master-1.00.a.yaml

I agree, but I ended up following the pattern for the other adi,
bindings. I will move for v4. IMO the version suffix has no much use
since IP updates are handled in the driver.

Filename is not related to whether given ABI works with every device.
Filename helps us to organize bindings and existing convention is that
we want it to follow the compatible.

Hi Krzysztof,

Understood.

quoted

quoted

quoted

@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/i3c/adi,i3c-master.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Analog Devices I3C Controller
+
+description: |
+  FPGA-based I3C controller designed to interface with I3C and I2C peripherals,
+  implementing a subset of the I3C-basic specification.
+
+  https://analogdevicesinc.github.io/hdl/library/i3c_controller
+
+maintainers:
+  - Jorge Marques <jorge.marques@analog.com>
+
+properties:
+  compatible:
+    const: adi,i3c-master-1.00.a
+
+  reg:
+    maxItems: 1
+
+  clocks:
+    minItems: 1

Why?

The IP core requires a clock, and the second is optional.

OK

quoted

minItems sets the minimum number of required clocks and the maxItems is
inferred from the number of items.

On the IP core itself, one clock is required (axi), and if it is the
only provided, it means that the same clock for the AXI bus is used
also for the rest of the RTL logic.

Hm? What does it exactly mean - same clock? You mean one clock is routed
to two pins? That's still two clocks. Or you mean that IP core will
notice grounded clock input and do the routing inside?

The routing is inside the IP core, and only one clock pin is used. In
fullness, since it is a FPGA-based IP Core, the number of input clock
pins are defined by the parameter [1] ASYNC_CLK that enables the
asynchronous i3c clock input pin. The devicetree then describes how
things are wired, if two clocks provided, it describes that both clock
inputs, axi and i3c, are wired to the IP Core, if only axi, then there
is no clock signal to the i3c input clock pin and axi clock drives the
whole IP.

[1] https://analogdevicesinc.github.io/hdl/library/i3c_controller/i3c_controller_host_interface.html#configuration-parameters

quoted

If a second clock is provided, i3c, it means it drives the RTL logic and is
asynchronous to the axi clock, which then just drives the register map logic.
For i3c specified nominal speeds, the RTL logic should run with a speed of
100MHz. Some FPGAs, such as Altera CycloneV, have a default bus clock speed of
50MHz. Changing the bus speed is possible, but affects timing and it may not be
possible from users to double the bus speed since it will affect timing of all
IP cores using the bus clock.

quoted

quoted

+    items:
+      - description: The AXI interconnect clock.
+      - description: The I3C controller clock.

I will update the descriptions to:

        - description: The AXI interconnect clock, drives the register map.
        - description: The I3C controller clock. AXI clock drives all logic if not provided.

quoted

quoted

+
+  clock-names:

Not synced with clocks.

I will add `minItems: 1`.

quoted

quoted

+    items:
+      - const: axi
+      - const: i3c
+
+  interrupts:
+    maxItems: 1
+
+required:
+  - compatible
+  - reg
+  - clocks
+  - clock-names
+  - interrupts
+
+allOf:
+  - $ref: i3c.yaml#
+
+unevaluatedProperties: false
+
+examples:
+  - |
+    i3c@44a00000 {
+        compatible = "adi,i3c-master";
+        reg = <0x44a00000 0x1000>;
+        interrupts = <0 56 4>;

Use proper defines.

The following can added:

  #include <dt-bindings/interrupt-controller/irq.h>

  interrupts = <0 56 IRQ_TYPE_LEVEL_HIGH>;

Is there any other to be replaced?

Usually 0 has a meaning as well. Where is this used DTS snippet used (on
which platform)?

The example provided is used on AMD xilinx arm,cortex-a9-gic.
The IP core is tested on AMD Xilinx, Altera FPGAs (arm, microblaze, arm64).
Test/support to RiscV-based Lattice FPGAs should eventually also come.

In this example 0 means Shared Peripheral Interrupt, but has no header
file defining. I guess I could make it generic and set to

  interrupts = <3 IRQ_TYPE_LEVEL_HIGH>;

and let the user figure out for his target platform.

Best regards,
Krzysztof

Best regards,
Jorge