0001 Generic device tree bindings for I2C busses
0002 ===========================================
0003
0004 This document describes generic bindings which can be used to describe I2C
0005 busses and their child devices in a device tree.
0006
0007 Required properties (per bus)
0008 -----------------------------
0009
0010 - #address-cells - should be <1>. Read more about addresses below.
0011 - #size-cells - should be <0>.
0012 - compatible - name of I2C bus controller
0013
0014 For other required properties e.g. to describe register sets,
0015 clocks, etc. check the binding documentation of the specific driver.
0016
0017 The cells properties above define that an address of children of an I2C bus
0018 are described by a single value.
0019
0020 Optional properties (per bus)
0021 -----------------------------
0022
0023 These properties may not be supported by all drivers. However, if a driver
0024 wants to support one of the below features, it should adapt these bindings.
0025
0026 - clock-frequency
0027 frequency of bus clock in Hz.
0028
0029 - i2c-bus
0030 For I2C adapters that have child nodes that are a mixture of both I2C
0031 devices and non-I2C devices, the 'i2c-bus' subnode can be used for
0032 populating I2C devices. If the 'i2c-bus' subnode is present, only
0033 subnodes of this will be considered as I2C slaves. The properties,
0034 '#address-cells' and '#size-cells' must be defined under this subnode
0035 if present.
0036
0037 - i2c-scl-falling-time-ns
0038 Number of nanoseconds the SCL signal takes to fall; t(f) in the I2C
0039 specification.
0040
0041 - i2c-scl-internal-delay-ns
0042 Number of nanoseconds the IP core additionally needs to setup SCL.
0043
0044 - i2c-scl-rising-time-ns
0045 Number of nanoseconds the SCL signal takes to rise; t(r) in the I2C
0046 specification.
0047
0048 - i2c-sda-falling-time-ns
0049 Number of nanoseconds the SDA signal takes to fall; t(f) in the I2C
0050 specification.
0051
0052 - i2c-analog-filter
0053 Enable analog filter for i2c lines.
0054
0055 - i2c-digital-filter
0056 Enable digital filter for i2c lines.
0057
0058 - i2c-digital-filter-width-ns
0059 Width of spikes which can be filtered by digital filter
0060 (i2c-digital-filter). This width is specified in nanoseconds.
0061
0062 - i2c-analog-filter-cutoff-frequency
0063 Frequency that the analog filter (i2c-analog-filter) uses to distinguish
0064 which signal to filter. Signal with higher frequency than specified will
0065 be filtered out. Only lower frequency will pass (this is applicable to
0066 a low-pass analog filter). Typical value should be above the normal
0067 i2c bus clock frequency (clock-frequency).
0068 Specified in Hz.
0069
0070 - multi-master
0071 states that there is another master active on this bus. The OS can use
0072 this information to adapt power management to keep the arbitration awake
0073 all the time, for example. Can not be combined with 'single-master'.
0074
0075 - pinctrl
0076 add extra pinctrl to configure SCL/SDA pins to GPIO function for bus
0077 recovery, call it "gpio" or "recovery" (deprecated) state
0078
0079 - scl-gpios
0080 specify the gpio related to SCL pin. Used for GPIO bus recovery.
0081
0082 - sda-gpios
0083 specify the gpio related to SDA pin. Optional for GPIO bus recovery.
0084
0085 - single-master
0086 states that there is no other master active on this bus. The OS can use
0087 this information to detect a stalled bus more reliably, for example.
0088 Can not be combined with 'multi-master'.
0089
0090 - smbus
0091 states that additional SMBus restrictions and features apply to this bus.
0092 An example of feature is SMBusHostNotify. Examples of restrictions are
0093 more reserved addresses and timeout definitions.
0094
0095 - smbus-alert
0096 states that the optional SMBus-Alert feature apply to this bus.
0097
0098 - mctp-controller
0099 indicates that the system is accessible via this bus as an endpoint for
0100 MCTP over I2C transport.
0101
0102 Required properties (per child device)
0103 --------------------------------------
0104
0105 - compatible
0106 name of I2C slave device
0107
0108 - reg
0109 One or many I2C slave addresses. These are usually a 7 bit addresses.
0110 However, flags can be attached to an address. I2C_TEN_BIT_ADDRESS is
0111 used to mark a 10 bit address. It is needed to avoid the ambiguity
0112 between e.g. a 7 bit address of 0x50 and a 10 bit address of 0x050
0113 which, in theory, can be on the same bus.
0114 Another flag is I2C_OWN_SLAVE_ADDRESS to mark addresses on which we
0115 listen to be devices ourselves.
0116
0117 Optional properties (per child device)
0118 --------------------------------------
0119
0120 These properties may not be supported by all drivers. However, if a driver
0121 wants to support one of the below features, it should adapt these bindings.
0122
0123 - host-notify
0124 device uses SMBus host notify protocol instead of interrupt line.
0125
0126 - interrupts
0127 interrupts used by the device.
0128
0129 - interrupt-names
0130 "irq", "wakeup" and "smbus_alert" names are recognized by I2C core,
0131 other names are left to individual drivers.
0132
0133 - reg-names
0134 Names of map programmable addresses.
0135 It can contain any map needing another address than default one.
0136
0137 - wakeup-source
0138 device can be used as a wakeup source.
0139
0140 Binding may contain optional "interrupts" property, describing interrupts
0141 used by the device. I2C core will assign "irq" interrupt (or the very first
0142 interrupt if not using interrupt names) as primary interrupt for the slave.
0143
0144 Alternatively, devices supporting SMBus Host Notify, and connected to
0145 adapters that support this feature, may use "host-notify" property. I2C
0146 core will create a virtual interrupt for Host Notify and assign it as
0147 primary interrupt for the slave.
0148
0149 Also, if device is marked as a wakeup source, I2C core will set up "wakeup"
0150 interrupt for the device. If "wakeup" interrupt name is not present in the
0151 binding, then primary interrupt will be used as wakeup interrupt.
