Documentation/devicetree/bindings/i2c/i2c.txt

   1 Generic device tree bindings for I2C busses
   2 ===========================================
   3
   4 This document describes generic bindings which can be used to describe I2C
   5 busses and their child devices in a device tree.
   6
   7 Required 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
  14 For other required properties e.g. to describe register sets,
  15 clocks, etc. check the binding documentation of the specific driver.
  16
  17 The cells properties above define that an address of children of an I2C bus
  18 are described by a single value.
  19
  20 Optional properties (per bus)
  21 -----------------------------
  22
  23 These properties may not be supported by all drivers. However, if a driver
  24 wants 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
 102 Required 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
 117 Optional properties (per child device)
 118 --------------------------------------
 119
 120 These properties may not be supported by all drivers. However, if a driver
 121 wants 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
 140 Binding may contain optional "interrupts" property, describing interrupts
 141 used by the device. I2C core will assign "irq" interrupt (or the very first
 142 interrupt if not using interrupt names) as primary interrupt for the slave.
 143
 144 Alternatively, devices supporting SMBus Host Notify, and connected to
 145 adapters that support this feature, may use "host-notify" property. I2C
 146 core will create a virtual interrupt for Host Notify and assign it as
 147 primary interrupt for the slave.
 148
 149 Also, if device is marked as a wakeup source, I2C core will set up "wakeup"
 150 interrupt for the device. If "wakeup" interrupt name is not present in the
 151 binding, then primary interrupt will be used as wakeup interrupt.