0001 # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
0002 %YAML 1.2
0003 ---
0004 $id: http://devicetree.org/schemas/i3c/i3c.yaml#
0005 $schema: http://devicetree.org/meta-schemas/core.yaml#
0006
0007 title: I3C bus binding
0008
0009 maintainers:
0010 - Alexandre Belloni <alexandre.belloni@bootlin.com>
0011 - Miquel Raynal <miquel.raynal@bootlin.com>
0012
0013 description: |
0014 I3C busses can be described with a node for the primary I3C controller device
0015 and a set of child nodes for each I2C or I3C slave on the bus. Each of them
0016 may, during the life of the bus, request mastership.
0017
0018 properties:
0019 $nodename:
0020 pattern: "^i3c-master@[0-9a-f]+$"
0021
0022 "#address-cells":
0023 const: 3
0024 description: |
0025 Each I2C device connected to the bus should be described in a subnode.
0026
0027 All I3C devices are supposed to support DAA (Dynamic Address Assignment),
0028 and are thus discoverable. So, by default, I3C devices do not have to be
0029 described in the device tree. This being said, one might want to attach
0030 extra resources to these devices, and those resources may have to be
0031 described in the device tree, which in turn means we have to describe
0032 I3C devices.
0033
0034 Another use case for describing an I3C device in the device tree is when
0035 this I3C device has a static I2C address and we want to assign it a
0036 specific I3C dynamic address before the DAA takes place (so that other
0037 devices on the bus can't take this dynamic address).
0038
0039 "#size-cells":
0040 const: 0
0041
0042 i3c-scl-hz:
0043 description: |
0044 Frequency of the SCL signal used for I3C transfers. When undefined, the
0045 default value should be 12.5MHz.
0046
0047 May not be supported by all controllers.
0048
0049 i2c-scl-hz:
0050 description: |
0051 Frequency of the SCL signal used for I2C transfers. When undefined, the
0052 default should be to look at LVR (Legacy Virtual Register) values of
0053 I2C devices described in the device tree to determine the maximum I2C
0054 frequency.
0055
0056 May not be supported by all controllers.
0057
0058 required:
0059 - "#address-cells"
0060 - "#size-cells"
0061
0062 patternProperties:
0063 "@[0-9a-f]+$":
0064 type: object
0065 description: |
0066 I2C child, should be named: <device-type>@<i2c-address>
0067
0068 All properties described in Documentation/devicetree/bindings/i2c/i2c.txt
0069 are valid here, except the reg property whose content is changed.
0070
0071 properties:
0072 compatible:
0073 description:
0074 Compatible of the I2C device.
0075
0076 reg:
0077 items:
0078 - items:
0079 - description: |
0080 I2C address. 10 bit addressing is not supported. Devices with
0081 10-bit address can't be properly passed through DEFSLVS
0082 command.
0083 minimum: 0
0084 maximum: 0x7f
0085 - const: 0
0086 - description: |
0087 Shall encode the I3C LVR (Legacy Virtual Register):
0088 bit[31:8]: unused/ignored
0089 bit[7:5]: I2C device index. Possible values:
0090 * 0: I2C device has a 50 ns spike filter
0091 * 1: I2C device does not have a 50 ns spike filter but
0092 supports high frequency on SCL
0093 * 2: I2C device does not have a 50 ns spike filter and is
0094 not tolerant to high frequencies
0095 * 3-7: reserved
0096 bit[4]: tell whether the device operates in FM (Fast Mode)
0097 or FM+ mode:
0098 * 0: FM+ mode
0099 * 1: FM mode
0100 bit[3:0]: device type
0101 * 0-15: reserved
0102
0103 required:
0104 - compatible
0105 - reg
0106
0107 "@[0-9a-f]+,[0-9a-f]+$":
0108 type: object
0109 description: |
0110 I3C child, should be named: <device-type>@<static-i2c-address>,<i3c-pid>
0111
0112 properties:
0113 reg:
0114 items:
0115 - items:
0116 - description: |
0117 Encodes the static I2C address. Should be 0 if the device does
0118 not have one (0 is not a valid I2C address).
0119 minimum: 0
0120 maximum: 0x7f
0121 - description: |
0122 First half of the Provisional ID (following the PID
0123 definition provided by the I3C specification).
0124
0125 Contains the manufacturer ID left-shifted by 1.
0126 - description: |
0127 Second half of the Provisional ID (following the PID
0128 definition provided by the I3C specification).
0129
0130 Contains the ORing of the part ID left-shifted by 16,
0131 the instance ID left-shifted by 12 and extra information.
0132
0133 assigned-address:
0134 $ref: /schemas/types.yaml#/definitions/uint32
0135 minimum: 0x1
0136 maximum: 0xff
0137 description: |
0138 Dynamic address to be assigned to this device. This property is only
0139 valid if the I3C device has a static address (first cell of the reg
0140 property != 0).
0141
0142 required:
0143 - reg
0144
0145 additionalProperties: true
0146
0147 examples:
0148 - |
0149 i3c-master@d040000 {
0150 compatible = "cdns,i3c-master";
0151 clocks = <&coreclock>, <&i3csysclock>;
0152 clock-names = "pclk", "sysclk";
0153 interrupts = <3 0>;
0154 reg = <0x0d040000 0x1000>;
0155 #address-cells = <3>;
0156 #size-cells = <0>;
0157 i2c-scl-hz = <100000>;
0158
0159 /* I2C device. */
0160 eeprom@57 {
0161 compatible = "atmel,24c01";
0162 reg = <0x57 0x0 0x10>;
0163 pagesize = <0x8>;
0164 };
0165
0166 /* I3C device with a static I2C address. */
0167 thermal_sensor: sensor@68,39200144004 {
0168 reg = <0x68 0x392 0x144004>;
0169 assigned-address = <0xa>;
0170 };
0171
0172 /*
0173 * I3C device without a static I2C address but requiring
0174 * resources described in the DT.
0175 */
0176 sensor@0,39200154004 {
0177 reg = <0x0 0x392 0x154004>;
0178 clocks = <&clock_provider 0>;
0179 };
0180 };
