Commit 88fb09c4 authored by Wolfram Sang's avatar Wolfram Sang Committed by Wolfram Sang
Browse files

i2c: regroup documentation of bindings 



Some bindings are for the bus master, some are for the slaves.
Regroup them and give them separate headings to make it clear.
Also, remove references to "generic names" which is for nodes and not
for compatibles.

Signed-off-by: default avatarWolfram Sang <wsa+renesas@sang-engineering.com>
Reviewed-by: default avatarRob Herring <robh@kernel.org>
Signed-off-by: default avatarWolfram Sang <wsa@the-dreams.de>
parent 09cc9a3b

Documentation/devicetree/bindings/i2c/i2c.txt

+39 −27
Original line number Diff line number Diff line
@@ -2,32 +2,26 @@ Generic device tree bindings for I2C busses 
===========================================



This document describes generic bindings which can be used to describe I2C

busses in a device tree.

busses and their child devices in a device tree.



Required properties

-------------------

Required properties (per bus)

-----------------------------



- #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.

- compatible      - name of I2C bus controller



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.

are described by a single value.



Optional properties

-------------------

Optional properties (per bus)

-----------------------------



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.

wants to support one of the below features, it should adapt these bindings.



- clock-frequency

	frequency of bus clock in Hz.
@@ -73,31 +67,49 @@ wants to support one of the below features, it should adapt the bindings below. 
	i2c bus clock frequency (clock-frequency).

	Specified in Hz.



- interrupts

	interrupts used by the device.



- interrupt-names

	"irq", "wakeup" and "smbus_alert" 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.

Required properties (per child device)

--------------------------------------



- compatible

	name of I2C slave device



- reg

	I2C slave addresses

	One or many I2C slave addresses. These are usually a 7 bit addresses.

	However, flags can be attached to an 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 (per child device)

--------------------------------------



These properties may not be supported by all drivers. However, if a driver

wants to support one of the below features, it should adapt these bindings.



- host-notify

	device uses SMBus host notify protocol instead of interrupt line.



- interrupts

	interrupts used by the device.



- interrupt-names

	"irq", "wakeup" and "smbus_alert" names are recognized by I2C core,

	other names are	left to individual drivers.



- reg-names

	Names of map programmable addresses.

	It can contain any map needing another address than default one.



- wakeup-source

	device can be used as a wakeup source.



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.