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