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