Documentation/devicetree/bindings/i3c/i3c.yaml

   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
   7 title: I3C bus
   8
   9 maintainers:
  10   - Alexandre Belloni <alexandre.belloni@bootlin.com>
  11   - Miquel Raynal <miquel.raynal@bootlin.com>
  12
  13 description: |
  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
  18 properties:
  19   $nodename:
  20     pattern: "^i3c@[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
  58   mctp-controller:
  59     type: boolean
  60     description: |
  61       Indicates that the system is accessible via this bus as an endpoint for
  62       MCTP over I3C transport.
  63
  64 required:
  65   - "#address-cells"
  66   - "#size-cells"
  67
  68 patternProperties:
  69   "@[0-9a-f]+$":
  70     type: object
  71     description: |
  72       I2C child, should be named: <device-type>@<i2c-address>
  73
  74       All properties described in dtschema schemas/i2c/i2c-controller.yaml
  75       are valid here, except the reg property whose content is changed.
  76
  77     properties:
  78       compatible:
  79         description:
  80           Compatible of the I2C device.
  81
  82       reg:
  83         items:
  84           - items:
  85               - description: |
  86                   I2C address. 10 bit addressing is not supported. Devices with
  87                   10-bit address can't be properly passed through DEFSLVS
  88                   command.
  89                 minimum: 0
  90                 maximum: 0x7f
  91               - const: 0
  92               - description: |
  93                   Shall encode the I3C LVR (Legacy Virtual Register):
  94                     bit[31:8]: unused/ignored
  95                     bit[7:5]: I2C device index. Possible values:
  96                       * 0: I2C device has a 50 ns spike filter
  97                       * 1: I2C device does not have a 50 ns spike filter but
  98                            supports high frequency on SCL
  99                       * 2: I2C device does not have a 50 ns spike filter and is
 100                            not tolerant to high frequencies
 101                       * 3-7: reserved
 102                     bit[4]: tell whether the device operates in FM (Fast Mode)
 103                             or FM+ mode:
 104                       * 0: FM+ mode
 105                       * 1: FM mode
 106                     bit[3:0]: device type
 107                       * 0-15: reserved
 108
 109     required:
 110       - compatible
 111       - reg
 112
 113   "@[0-9a-f]+,[0-9a-f]+$":
 114     type: object
 115     description: |
 116       I3C child, should be named: <device-type>@<static-i2c-address>,<i3c-pid>
 117
 118     properties:
 119       reg:
 120         items:
 121           - items:
 122               - description: |
 123                   Encodes the static I2C address. Should be 0 if the device does
 124                   not have one (0 is not a valid I2C address).
 125                 minimum: 0
 126                 maximum: 0x7f
 127               - description: |
 128                   First half of the Provisioned ID (following the PID
 129                   definition provided by the I3C specification).
 130
 131                   Contains the manufacturer ID left-shifted by 1.
 132               - description: |
 133                   Second half of the Provisioned ID (following the PID
 134                   definition provided by the I3C specification).
 135
 136                   Contains the ORing of the part ID left-shifted by 16,
 137                   the instance ID left-shifted by 12 and extra information.
 138
 139       assigned-address:
 140         $ref: /schemas/types.yaml#/definitions/uint32
 141         minimum: 0x1
 142         maximum: 0xff
 143         description: |
 144           Dynamic address to be assigned to this device. In case static address is
 145           present (first cell of the reg property != 0), this address is assigned
 146           through SETDASA. If static address is not present, this address is assigned
 147           through SETNEWDA after assigning a temporary address via ENTDAA.
 148
 149     required:
 150       - reg
 151
 152 additionalProperties: true
 153
 154 examples:
 155   - |
 156     i3c@d040000 {
 157         compatible = "cdns,i3c-master";
 158         clocks = <&coreclock>, <&i3csysclock>;
 159         clock-names = "pclk", "sysclk";
 160         interrupts = <3 0>;
 161         reg = <0x0d040000 0x1000>;
 162         #address-cells = <3>;
 163         #size-cells = <0>;
 164         i2c-scl-hz = <100000>;
 165
 166         /* I2C device. */
 167         eeprom@57 {
 168             compatible = "atmel,24c01";
 169             reg = <0x57 0x0 0x10>;
 170             pagesize = <0x8>;
 171         };
 172
 173         /* I3C device with a static I2C address and assigned address. */
 174         thermal_sensor: sensor@68,39200144004 {
 175             reg = <0x68 0x392 0x144004>;
 176             assigned-address = <0xa>;
 177         };
 178
 179         /* I3C device with only assigned address. */
 180         pressure_sensor: sensor@0,39200124004 {
 181             reg = <0x0 0x392 0x124000>;
 182             assigned-address = <0xc>;
 183         };
 184
 185         /*
 186          * I3C device without a static I2C address but requiring
 187          * resources described in the DT.
 188          */
 189         sensor@0,39200154004 {
 190             reg = <0x0 0x392 0x154004>;
 191             clocks = <&clock_provider 0>;
 192         };
 193     };