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