Documentation/devicetree/bindings/i3c/i3c.txt

   1 Generic device tree bindings for I3C busses
   2 ===========================================
   3
   4 This document describes generic bindings that should be used to describe I3C
   5 busses in a device tree.
   6
   7 Required 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
  14 For other required properties e.g. to describe register sets,
  15 clocks, etc. check the binding documentation of the specific driver.
  16 The node describing an I3C bus should be named i3c-master.
  17
  18 Optional properties
  19 -------------------
  20
  21 These properties may not be supported by all I3C master drivers. Each I3C
  22 master 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
  32 I2C devices
  33 ===========
  34
  35 Each I2C device connected to the bus should be described in a subnode. All
  36 properties described in Documentation/devicetree/bindings/i2c/i2c.txt are
  37 valid here, but several new properties have been added.
  38
  39 New 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
  65 The I2C node unit-address should always match the first cell of the reg
  66 property: <device-type>@<i2c-address>.
  67
  68 I3C devices
  69 ===========
  70
  71 All I3C devices are supposed to support DAA (Dynamic Address Assignment), and
  72 are thus discoverable. So, by default, I3C devices do not have to be described
  73 in the device tree.
  74 This being said, one might want to attach extra resources to these devices,
  75 and those resources may have to be described in the device tree, which in turn
  76 means we have to describe I3C devices.
  77
  78 Another use case for describing an I3C device in the device tree is when this
  79 I3C device has a static I2C address and we want to assign it a specific I3C
  80 dynamic address before the DAA takes place (so that other devices on the bus
  81 can't take this dynamic address).
  82
  83 The I3C device should be names <device-type>@<static-i2c-address>,<i3c-pid>,
  84 where device-type is describing the type of device connected on the bus
  85 (gpio-controller, sensor, ...).
  86
  87 Required 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
 101 Optional 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
 108 Example:
 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         };