^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) Generic device tree bindings for I2C 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 which can be used to describe I2C
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) busses and their child devices 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 (per bus)
^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 <1>. 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 I2C bus controller
^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)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) The cells properties above define that an address of children of an I2C bus
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) are described by a single value.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) Optional properties (per bus)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) -----------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) These properties may not be supported by all drivers. However, if a driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) wants to support one of the below features, it should adapt these bindings.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) - clock-frequency
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) frequency of bus clock in Hz.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) - i2c-bus
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) For I2C adapters that have child nodes that are a mixture of both I2C
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) devices and non-I2C devices, the 'i2c-bus' subnode can be used for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) populating I2C devices. If the 'i2c-bus' subnode is present, only
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) subnodes of this will be considered as I2C slaves. The properties,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) '#address-cells' and '#size-cells' must be defined under this subnode
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) if present.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) - i2c-scl-falling-time-ns
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) Number of nanoseconds the SCL signal takes to fall; t(f) in the I2C
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) specification.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) - i2c-scl-internal-delay-ns
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) Number of nanoseconds the IP core additionally needs to setup SCL.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) - i2c-scl-rising-time-ns
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) Number of nanoseconds the SCL signal takes to rise; t(r) in the I2C
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) specification.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) - i2c-sda-falling-time-ns
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) Number of nanoseconds the SDA signal takes to fall; t(f) in the I2C
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) specification.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) - i2c-analog-filter
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) Enable analog filter for i2c lines.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) - i2c-digital-filter
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) Enable digital filter for i2c lines.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) - i2c-digital-filter-width-ns
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) Width of spikes which can be filtered by digital filter
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) (i2c-digital-filter). This width is specified in nanoseconds.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) - i2c-analog-filter-cutoff-frequency
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) Frequency that the analog filter (i2c-analog-filter) uses to distinguish
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) which signal to filter. Signal with higher frequency than specified will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) be filtered out. Only lower frequency will pass (this is applicable to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) a low-pass analog filter). Typical value should be above the normal
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) i2c bus clock frequency (clock-frequency).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) Specified in Hz.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) - multi-master
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) states that there is another master active on this bus. The OS can use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) this information to adapt power management to keep the arbitration awake
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) all the time, for example. Can not be combined with 'single-master'.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) - pinctrl
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) add extra pinctrl to configure SCL/SDA pins to GPIO function for bus
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) recovery, call it "gpio" or "recovery" (deprecated) state
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) - scl-gpios
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) specify the gpio related to SCL pin. Used for GPIO bus recovery.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) - sda-gpios
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) specify the gpio related to SDA pin. Optional for GPIO bus recovery.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) - single-master
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) states that there is no other master active on this bus. The OS can use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) this information to detect a stalled bus more reliably, for example.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) Can not be combined with 'multi-master'.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) - smbus
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) states that additional SMBus restrictions and features apply to this bus.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) Examples of features are SMBusHostNotify and SMBusAlert. Examples of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) restrictions are more reserved addresses and timeout definitions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) Required properties (per child device)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) --------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) - compatible
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) name of I2C slave device
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) - reg
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) One or many I2C slave addresses. These are usually a 7 bit addresses.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) However, flags can be attached to an address. I2C_TEN_BIT_ADDRESS is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) used to mark a 10 bit address. It is needed to avoid the ambiguity
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) between e.g. a 7 bit address of 0x50 and a 10 bit address of 0x050
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) which, in theory, can be on the same bus.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) Another flag is I2C_OWN_SLAVE_ADDRESS to mark addresses on which we
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) listen to be devices ourselves.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) Optional properties (per child device)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) --------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) These properties may not be supported by all drivers. However, if a driver
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114) wants to support one of the below features, it should adapt these bindings.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) - host-notify
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) device uses SMBus host notify protocol instead of interrupt line.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) - interrupts
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) interrupts used by the device.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) - interrupt-names
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) "irq", "wakeup" and "smbus_alert" names are recognized by I2C core,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) other names are left to individual drivers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) - reg-names
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) Names of map programmable addresses.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) It can contain any map needing another address than default one.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) - wakeup-source
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) device can be used as a wakeup source.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) Binding may contain optional "interrupts" property, describing interrupts
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) used by the device. I2C core will assign "irq" interrupt (or the very first
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) interrupt if not using interrupt names) as primary interrupt for the slave.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) Alternatively, devices supporting SMBus Host Notify, and connected to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) adapters that support this feature, may use "host-notify" property. I2C
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) core will create a virtual interrupt for Host Notify and assign it as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) primary interrupt for the slave.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) Also, if device is marked as a wakeup source, I2C core will set up "wakeup"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) interrupt for the device. If "wakeup" interrupt name is not present in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) binding, then primary interrupt will be used as wakeup interrupt.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags