1Generic device tree bindings for I3C busses
2===========================================
3
4This document describes generic bindings that should be used to describe I3C
5busses in a device tree.
6
7Required properties
8-------------------
9
10- #address-cells  - should be <3>. Read more about addresses below.
11- #size-cells     - should be <0>.
12- compatible      - name of the I3C master controller driving the I3C bus
13
14For other required properties e.g. to describe register sets,
15clocks, etc. check the binding documentation of the specific driver.
16The node describing an I3C bus should be named i3c-master.
17
18Optional properties
19-------------------
20
21These properties may not be supported by all I3C master drivers. Each I3C
22master bindings should specify which of them are supported.
23
24- i3c-scl-hz: frequency of the SCL signal used for I3C transfers.
25	      When undefined the core sets it to 12.5MHz.
26
27- i2c-scl-hz: frequency of the SCL signal used for I2C transfers.
28	      When undefined, the core looks at LVR (Legacy Virtual Register)
29	      values of I2C devices described in the device tree to determine
30	      the maximum I2C frequency.
31
32I2C devices
33===========
34
35Each I2C device connected to the bus should be described in a subnode. All
36properties described in Documentation/devicetree/bindings/i2c/i2c.txt are
37valid here, but several new properties have been added.
38
39New constraint on existing properties:
40--------------------------------------
41- reg: contains 3 cells
42  + first cell : still encoding the I2C address. 10 bit addressing is not
43    supported. Devices with 10 bit address can't be properly passed through
44    DEFSLVS command.
45
46  + second cell: shall be 0
47
48  + third cell: shall encode the I3C LVR (Legacy Virtual Register)
49	bit[31:8]: unused/ignored
50	bit[7:5]: I2C device index. Possible values
51	* 0: I2C device has a 50 ns spike filter
52	* 1: I2C device does not have a 50 ns spike filter but supports high
53	     frequency on SCL
54	* 2: I2C device does not have a 50 ns spike filter and is not tolerant
55	     to high frequencies
56	* 3-7: reserved
57
58	bit[4]: tell whether the device operates in FM (Fast Mode) or FM+ mode
59	* 0: FM+ mode
60	* 1: FM mode
61
62	bit[3:0]: device type
63	* 0-15: reserved
64
65The I2C node unit-address should always match the first cell of the reg
66property: <device-type>@<i2c-address>.
67
68I3C devices
69===========
70
71All I3C devices are supposed to support DAA (Dynamic Address Assignment), and
72are thus discoverable. So, by default, I3C devices do not have to be described
73in the device tree.
74This being said, one might want to attach extra resources to these devices,
75and those resources may have to be described in the device tree, which in turn
76means we have to describe I3C devices.
77
78Another use case for describing an I3C device in the device tree is when this
79I3C device has a static I2C address and we want to assign it a specific I3C
80dynamic address before the DAA takes place (so that other devices on the bus
81can't take this dynamic address).
82
83The I3C device should be names <device-type>@<static-i2c-address>,<i3c-pid>,
84where device-type is describing the type of device connected on the bus
85(gpio-controller, sensor, ...).
86
87Required properties
88-------------------
89- reg: contains 3 cells
90  + first cell : encodes the static I2C address. Should be 0 if the device does
91		 not have one (0 is not a valid I2C address).
92
93  + second and third cells: should encode the ProvisionalID. The second cell
94			    contains the manufacturer ID left-shifted by 1.
95			    The third cell contains ORing of the part ID
96			    left-shifted by 16, the instance ID left-shifted
97			    by 12 and the extra information. This encoding is
98			    following the PID definition provided by the I3C
99			    specification.
100
101Optional properties
102-------------------
103- assigned-address: dynamic address to be assigned to this device. This
104		    property is only valid if the I3C device has a static
105		    address (first cell of the reg property != 0).
106
107
108Example:
109
110	i3c-master@d040000 {
111		compatible = "cdns,i3c-master";
112		clocks = <&coreclock>, <&i3csysclock>;
113		clock-names = "pclk", "sysclk";
114		interrupts = <3 0>;
115		reg = <0x0d040000 0x1000>;
116		#address-cells = <3>;
117		#size-cells = <0>;
118		i2c-scl-hz = <100000>;
119
120		/* I2C device. */
121		nunchuk: nunchuk@52 {
122			compatible = "nintendo,nunchuk";
123			reg = <0x52 0x0 0x10>;
124		};
125
126		/* I3C device with a static I2C address. */
127		thermal_sensor: sensor@68,39200144004 {
128			reg = <0x68 0x392 0x144004>;
129			assigned-address = <0xa>;
130		};
131
132		/*
133		 * I3C device without a static I2C address but requiring
134		 * resources described in the DT.
135		 */
136		sensor@0,39200154004 {
137			reg = <0x0 0x392 0x154004>;
138			clocks = <&clock_provider 0>;
139		};
140	};
141