About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / i2c / slave-interface


Based on kernel version 4.16.1. Page generated on 2018-04-09 11:53 EST.

1	Linux I2C slave interface description
2	=====================================
3	
4	by Wolfram Sang <wsa@sang-engineering.com> in 2014-15
5	
6	Linux can also be an I2C slave if the I2C controller in use has slave
7	functionality. For that to work, one needs slave support in the bus driver plus
8	a hardware independent software backend providing the actual functionality. An
9	example for the latter is the slave-eeprom driver, which acts as a dual memory
10	driver. While another I2C master on the bus can access it like a regular
11	EEPROM, the Linux I2C slave can access the content via sysfs and handle data as
12	needed. The backend driver and the I2C bus driver communicate via events. Here
13	is a small graph visualizing the data flow and the means by which data is
14	transported. The dotted line marks only one example. The backend could also
15	use a character device, be in-kernel only, or something completely different:
16	
17	
18	              e.g. sysfs        I2C slave events        I/O registers
19	  +-----------+   v    +---------+     v     +--------+  v  +------------+
20	  | Userspace +........+ Backend +-----------+ Driver +-----+ Controller |
21	  +-----------+        +---------+           +--------+     +------------+
22	                                                                | |
23	  ----------------------------------------------------------------+--  I2C
24	  --------------------------------------------------------------+----  Bus
25	
26	Note: Technically, there is also the I2C core between the backend and the
27	driver. However, at this time of writing, the layer is transparent.
28	
29	
30	User manual
31	===========
32	
33	I2C slave backends behave like standard I2C clients. So, you can instantiate
34	them as described in the document 'instantiating-devices'. The only difference
35	is that i2c slave backends have their own address space. So, you have to add
36	0x1000 to the address you would originally request. An example for
37	instantiating the slave-eeprom driver from userspace at the 7 bit address 0x64
38	on bus 1:
39	
40	  # echo slave-24c02 0x1064 > /sys/bus/i2c/devices/i2c-1/new_device
41	
42	Each backend should come with separate documentation to describe its specific
43	behaviour and setup.
44	
45	
46	Developer manual
47	================
48	
49	First, the events which are used by the bus driver and the backend will be
50	described in detail. After that, some implementation hints for extending bus
51	drivers and writing backends will be given.
52	
53	
54	I2C slave events
55	----------------
56	
57	The bus driver sends an event to the backend using the following function:
58	
59		ret = i2c_slave_event(client, event, &val)
60	
61	'client' describes the i2c slave device. 'event' is one of the special event
62	types described hereafter. 'val' holds an u8 value for the data byte to be
63	read/written and is thus bidirectional. The pointer to val must always be
64	provided even if val is not used for an event, i.e. don't use NULL here. 'ret'
65	is the return value from the backend. Mandatory events must be provided by the
66	bus drivers and must be checked for by backend drivers.
67	
68	Event types:
69	
70	* I2C_SLAVE_WRITE_REQUESTED (mandatory)
71	
72	'val': unused
73	'ret': always 0
74	
75	Another I2C master wants to write data to us. This event should be sent once
76	our own address and the write bit was detected. The data did not arrive yet, so
77	there is nothing to process or return. Wakeup or initialization probably needs
78	to be done, though.
79	
80	* I2C_SLAVE_READ_REQUESTED (mandatory)
81	
82	'val': backend returns first byte to be sent
83	'ret': always 0
84	
85	Another I2C master wants to read data from us. This event should be sent once
86	our own address and the read bit was detected. After returning, the bus driver
87	should transmit the first byte.
88	
89	* I2C_SLAVE_WRITE_RECEIVED (mandatory)
90	
91	'val': bus driver delivers received byte
92	'ret': 0 if the byte should be acked, some errno if the byte should be nacked
93	
94	Another I2C master has sent a byte to us which needs to be set in 'val'. If 'ret'
95	is zero, the bus driver should ack this byte. If 'ret' is an errno, then the byte
96	should be nacked.
97	
98	* I2C_SLAVE_READ_PROCESSED (mandatory)
99	
100	'val': backend returns next byte to be sent
101	'ret': always 0
102	
103	The bus driver requests the next byte to be sent to another I2C master in
104	'val'. Important: This does not mean that the previous byte has been acked, it
105	only means that the previous byte is shifted out to the bus! To ensure seamless
106	transmission, most hardware requests the next byte when the previous one is
107	still shifted out. If the master sends NACK and stops reading after the byte
108	currently shifted out, this byte requested here is never used. It very likely
109	needs to be sent again on the next I2C_SLAVE_READ_REQUEST, depending a bit on
110	your backend, though.
111	
112	* I2C_SLAVE_STOP (mandatory)
113	
114	'val': unused
115	'ret': always 0
116	
117	A stop condition was received. This can happen anytime and the backend should
118	reset its state machine for I2C transfers to be able to receive new requests.
119	
120	
121	Software backends
122	-----------------
123	
124	If you want to write a software backend:
125	
126	* use a standard i2c_driver and its matching mechanisms
127	* write the slave_callback which handles the above slave events
128	  (best using a state machine)
129	* register this callback via i2c_slave_register()
130	
131	Check the i2c-slave-eeprom driver as an example.
132	
133	
134	Bus driver support
135	------------------
136	
137	If you want to add slave support to the bus driver:
138	
139	* implement calls to register/unregister the slave and add those to the
140	  struct i2c_algorithm. When registering, you probably need to set the i2c
141	  slave address and enable slave specific interrupts. If you use runtime pm, you
142	  should use pm_runtime_get_sync() because your device usually needs to be
143	  powered on always to be able to detect its slave address. When unregistering,
144	  do the inverse of the above.
145	
146	* Catch the slave interrupts and send appropriate i2c_slave_events to the backend.
147	
148	Note that most hardware supports being master _and_ slave on the same bus. So,
149	if you extend a bus driver, please make sure that the driver supports that as
150	well. In almost all cases, slave support does not need to disable the master
151	functionality.
152	
153	Check the i2c-rcar driver as an example.
154	
155	
156	About ACK/NACK
157	--------------
158	
159	It is good behaviour to always ACK the address phase, so the master knows if a
160	device is basically present or if it mysteriously disappeared. Using NACK to
161	state being busy is troublesome. SMBus demands to always ACK the address phase,
162	while the I2C specification is more loose on that. Most I2C controllers also
163	automatically ACK when detecting their slave addresses, so there is no option
164	to NACK them. For those reasons, this API does not support NACK in the address
165	phase.
166	
167	Currently, there is no slave event to report if the master did ACK or NACK a
168	byte when it reads from us. We could make this an optional event if the need
169	arises. However, cases should be extremely rare because the master is expected
170	to send STOP after that and we have an event for that. Also, keep in mind not
171	all I2C controllers have the possibility to report that event.
172	
173	
174	About buffers
175	-------------
176	
177	During development of this API, the question of using buffers instead of just
178	bytes came up. Such an extension might be possible, usefulness is unclear at
179	this time of writing. Some points to keep in mind when using buffers:
180	
181	* Buffers should be opt-in and backend drivers will always have to support
182	  byte-based transactions as the ultimate fallback anyhow because this is how
183	  the majority of HW works.
184	
185	* For backends simulating hardware registers, buffers are largely not helpful
186	  because after each byte written an action should be immediately triggered.
187	  For reads, the data kept in the buffer might get stale if the backend just
188	  updated a register because of internal processing.
189	
190	* A master can send STOP at any time. For partially transferred buffers, this
191	  means additional code to handle this exception. Such code tends to be
192	  error-prone.
Hide Line Numbers


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog