[linux-2.6-block.git] / Documentation / devicetree / bindings / i2c / i2c.txt

Generic device tree bindings for I2C busses
===========================================

This document describes generic bindings which can be used to describe I2C
busses in a device tree.

Required properties
-------------------

- #address-cells  - should be <1>. Read more about addresses below.
- #size-cells     - should be <0>.
- compatible      - name of I2C bus controller following generic names
		    recommended practice.

For other required properties e.g. to describe register sets,
clocks, etc. check the binding documentation of the specific driver.

The cells properties above define that an address of children of an I2C bus
are described by a single value. This is usually a 7 bit address. However,
flags can be attached to the address. I2C_TEN_BIT_ADDRESS is used to mark a 10
bit address. It is needed to avoid the ambiguity between e.g. a 7 bit address
of 0x50 and a 10 bit address of 0x050 which, in theory, can be on the same bus.
Another flag is I2C_OWN_SLAVE_ADDRESS to mark addresses on which we listen to
be devices ourselves.

Optional properties
-------------------

These properties may not be supported by all drivers. However, if a driver
wants to support one of the below features, it should adapt the bindings below.

- clock-frequency
	frequency of bus clock in Hz.

- i2c-bus
	For I2C adapters that have child nodes that are a mixture of both I2C
	devices and non-I2C devices, the 'i2c-bus' subnode can be used for
	populating I2C devices. If the 'i2c-bus' subnode is present, only
	subnodes of this will be considered as I2C slaves. The properties,
	'#address-cells' and '#size-cells' must be defined under this subnode
	if present.

- i2c-scl-falling-time-ns
	Number of nanoseconds the SCL signal takes to fall; t(f) in the I2C
	specification.

- i2c-scl-internal-delay-ns
	Number of nanoseconds the IP core additionally needs to setup SCL.

- i2c-scl-rising-time-ns
	Number of nanoseconds the SCL signal takes to rise; t(r) in the I2C
	specification.

- i2c-sda-falling-time-ns
	Number of nanoseconds the SDA signal takes to fall; t(f) in the I2C
	specification.

- interrupts
	interrupts used by the device.

- interrupt-names
	"irq" and "wakeup" names are recognized by I2C core, other names are
	left to individual drivers.

- host-notify
	device uses SMBus host notify protocol instead of interrupt line.

- multi-master
	states that there is another master active on this bus. The OS can use
	this information to adapt power management to keep the arbitration awake
	all the time, for example.

- wakeup-source
	device can be used as a wakeup source.

- reg
	I2C slave addresses

- reg-names
	Names of map programmable addresses.
	It can contain any map needing another address than default one.

Binding may contain optional "interrupts" property, describing interrupts
used by the device. I2C core will assign "irq" interrupt (or the very first
interrupt if not using interrupt names) as primary interrupt for the slave.

Alternatively, devices supporting SMbus Host Notify, and connected to
adapters that support this feature, may use "host-notify" property. I2C
core will create a virtual interrupt for Host Notify and assign it as
primary interrupt for the slave.

Also, if device is marked as a wakeup source, I2C core will set up "wakeup"
interrupt for the device. If "wakeup" interrupt name is not present in the
binding, then primary interrupt will be used as wakeup interrupt.
Commit	Line	Data
7a59b00a WS	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 in a device tree.
	6
	7	Required properties
	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 following generic names
	13	recommended practice.
	14
3fffd128	15	For other required properties e.g. to describe register sets,
7a59b00a WS	16	clocks, etc. check the binding documentation of the specific driver.
	17
	18	The cells properties above define that an address of children of an I2C bus
	19	are described by a single value. This is usually a 7 bit address. However,
	20	flags can be attached to the address. I2C_TEN_BIT_ADDRESS is used to mark a 10
	21	bit address. It is needed to avoid the ambiguity between e.g. a 7 bit address
	22	of 0x50 and a 10 bit address of 0x050 which, in theory, can be on the same bus.
	23	Another flag is I2C_OWN_SLAVE_ADDRESS to mark addresses on which we listen to
	24	be devices ourselves.
	25
	26	Optional properties
	27	-------------------
	28
	29	These properties may not be supported by all drivers. However, if a driver
	30	wants to support one of the below features, it should adapt the bindings below.
	31
99b809d7 WS	32	- clock-frequency
99b809d7 WS	33	frequency of bus clock in Hz.
3fffd128	34
98b00488 JH	35	- i2c-bus
	36	For I2C adapters that have child nodes that are a mixture of both I2C
	37	devices and non-I2C devices, the 'i2c-bus' subnode can be used for
	38	populating I2C devices. If the 'i2c-bus' subnode is present, only
	39	subnodes of this will be considered as I2C slaves. The properties,
	40	'#address-cells' and '#size-cells' must be defined under this subnode
	41	if present.
	42
99b809d7 WS	43	- i2c-scl-falling-time-ns
	44	Number of nanoseconds the SCL signal takes to fall; t(f) in the I2C
	45	specification.
	46
	47	- i2c-scl-internal-delay-ns
	48	Number of nanoseconds the IP core additionally needs to setup SCL.
	49
	50	- i2c-scl-rising-time-ns
	51	Number of nanoseconds the SCL signal takes to rise; t(r) in the I2C
	52	specification.
	53
	54	- i2c-sda-falling-time-ns
	55	Number of nanoseconds the SDA signal takes to fall; t(f) in the I2C
	56	specification.
	57
	58	- interrupts
	59	interrupts used by the device.
	60
	61	- interrupt-names
	62	"irq" and "wakeup" names are recognized by I2C core, other names are
	63	left to individual drivers.
	64
331c3425 DT	65	- host-notify
	66	device uses SMBus host notify protocol instead of interrupt line.
	67
0c739738 WS	68	- multi-master
	69	states that there is another master active on this bus. The OS can use
	70	this information to adapt power management to keep the arbitration awake
	71	all the time, for example.
	72
99b809d7 WS	73	- wakeup-source
99b809d7 WS	74	device can be used as a wakeup source.
3fffd128	75
0f614d83 JMH	76	- reg
	77	I2C slave addresses
	78
	79	- reg-names
	80	Names of map programmable addresses.
	81	It can contain any map needing another address than default one.
	82
3fffd128 DT	83	Binding may contain optional "interrupts" property, describing interrupts
	84	used by the device. I2C core will assign "irq" interrupt (or the very first
	85	interrupt if not using interrupt names) as primary interrupt for the slave.
	86
331c3425 DT	87	Alternatively, devices supporting SMbus Host Notify, and connected to
	88	adapters that support this feature, may use "host-notify" property. I2C
	89	core will create a virtual interrupt for Host Notify and assign it as
	90	primary interrupt for the slave.
	91
3fffd128 DT	92	Also, if device is marked as a wakeup source, I2C core will set up "wakeup"
	93	interrupt for the device. If "wakeup" interrupt name is not present in the
	94	binding, then primary interrupt will be used as wakeup interrupt.