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