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