1# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
2%YAML 1.2
3---
4$id: http://devicetree.org/schemas/i3c/i3c.yaml#
5$schema: http://devicetree.org/meta-schemas/core.yaml#
6
7title: I3C bus
8
9maintainers:
10  - Alexandre Belloni <alexandre.belloni@bootlin.com>
11  - Miquel Raynal <miquel.raynal@bootlin.com>
12
13description: |
14  I3C busses can be described with a node for the primary I3C controller device
15  and a set of child nodes for each I2C or I3C slave on the bus. Each of them
16  may, during the life of the bus, request mastership.
17
18properties:
19  $nodename:
20    pattern: "^i3c-master@[0-9a-f]+$"
21
22  "#address-cells":
23    const: 3
24    description: |
25      Each I2C device connected to the bus should be described in a subnode.
26
27      All I3C devices are supposed to support DAA (Dynamic Address Assignment),
28      and are thus discoverable. So, by default, I3C devices do not have to be
29      described in the device tree. This being said, one might want to attach
30      extra resources to these devices, and those resources may have to be
31      described in the device tree, which in turn means we have to describe
32      I3C devices.
33
34      Another use case for describing an I3C device in the device tree is when
35      this I3C device has a static I2C address and we want to assign it a
36      specific I3C dynamic address before the DAA takes place (so that other
37      devices on the bus can't take this dynamic address).
38
39  "#size-cells":
40    const: 0
41
42  i3c-scl-hz:
43    description: |
44      Frequency of the SCL signal used for I3C transfers. When undefined, the
45      default value should be 12.5MHz.
46
47      May not be supported by all controllers.
48
49  i2c-scl-hz:
50    description: |
51      Frequency of the SCL signal used for I2C transfers. When undefined, the
52      default should be to look at LVR (Legacy Virtual Register) values of
53      I2C devices described in the device tree to determine the maximum I2C
54      frequency.
55
56      May not be supported by all controllers.
57
58required:
59  - "#address-cells"
60  - "#size-cells"
61
62patternProperties:
63  "@[0-9a-f]+$":
64    type: object
65    description: |
66      I2C child, should be named: <device-type>@<i2c-address>
67
68      All properties described in Documentation/devicetree/bindings/i2c/i2c.txt
69      are valid here, except the reg property whose content is changed.
70
71    properties:
72      compatible:
73        description:
74          Compatible of the I2C device.
75
76      reg:
77        items:
78          - items:
79              - description: |
80                  I2C address. 10 bit addressing is not supported. Devices with
81                  10-bit address can't be properly passed through DEFSLVS
82                  command.
83                minimum: 0
84                maximum: 0x7f
85              - const: 0
86              - description: |
87                  Shall encode the I3C LVR (Legacy Virtual Register):
88                    bit[31:8]: unused/ignored
89                    bit[7:5]: I2C device index. Possible values:
90                      * 0: I2C device has a 50 ns spike filter
91                      * 1: I2C device does not have a 50 ns spike filter but
92                           supports high frequency on SCL
93                      * 2: I2C device does not have a 50 ns spike filter and is
94                           not tolerant to high frequencies
95                      * 3-7: reserved
96                    bit[4]: tell whether the device operates in FM (Fast Mode)
97                            or FM+ mode:
98                      * 0: FM+ mode
99                      * 1: FM mode
100                    bit[3:0]: device type
101                      * 0-15: reserved
102
103    required:
104      - compatible
105      - reg
106
107  "@[0-9a-f]+,[0-9a-f]+$":
108    type: object
109    description: |
110      I3C child, should be named: <device-type>@<static-i2c-address>,<i3c-pid>
111
112    properties:
113      reg:
114        items:
115          - items:
116              - description: |
117                  Encodes the static I2C address. Should be 0 if the device does
118                  not have one (0 is not a valid I2C address).
119                minimum: 0
120                maximum: 0x7f
121              - description: |
122                  First half of the Provisional ID (following the PID
123                  definition provided by the I3C specification).
124
125                  Contains the manufacturer ID left-shifted by 1.
126              - description: |
127                  Second half of the Provisional ID (following the PID
128                  definition provided by the I3C specification).
129
130                  Contains the ORing of the part ID left-shifted by 16,
131                  the instance ID left-shifted by 12 and extra information.
132
133      assigned-address:
134        $ref: /schemas/types.yaml#/definitions/uint32
135        minimum: 0x1
136        maximum: 0xff
137        description: |
138          Dynamic address to be assigned to this device. In case static address is
139          present (first cell of the reg property != 0), this address is assigned
140          through SETDASA. If static address is not present, this address is assigned
141          through SETNEWDA after assigning a temporary address via ENTDAA.
142
143    required:
144      - reg
145
146additionalProperties: true
147
148examples:
149  - |
150    i3c-master@d040000 {
151        compatible = "cdns,i3c-master";
152        clocks = <&coreclock>, <&i3csysclock>;
153        clock-names = "pclk", "sysclk";
154        interrupts = <3 0>;
155        reg = <0x0d040000 0x1000>;
156        #address-cells = <3>;
157        #size-cells = <0>;
158        i2c-scl-hz = <100000>;
159
160        /* I2C device. */
161        eeprom@57 {
162            compatible = "atmel,24c01";
163            reg = <0x57 0x0 0x10>;
164            pagesize = <0x8>;
165        };
166
167        /* I3C device with a static I2C address and assigned address. */
168        thermal_sensor: sensor@68,39200144004 {
169            reg = <0x68 0x392 0x144004>;
170            assigned-address = <0xa>;
171        };
172
173        /* I3C device with only assigned address. */
174        pressure_sensor: sensor@0,39200124004 {
175            reg = <0x0 0x392 0x124000>;
176            assigned-address = <0xc>;
177        };
178
179        /*
180         * I3C device without a static I2C address but requiring
181         * resources described in the DT.
182         */
183        sensor@0,39200154004 {
184            reg = <0x0 0x392 0x154004>;
185            clocks = <&clock_provider 0>;
186        };
187    };
188