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