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'. The only difference 36is that i2c slave backends have their own address space. So, you have to add 370x1000 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': always 0 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. Wakeup or initialization probably needs 80to be done, though. 81 82* I2C_SLAVE_READ_REQUESTED (mandatory) 83 84 'val': backend returns first byte to be sent 85 86 'ret': always 0 87 88Another I2C master wants to read data from us. This event should be sent once 89our own address and the read bit was detected. After returning, the bus driver 90should transmit the first byte. 91 92* I2C_SLAVE_WRITE_RECEIVED (mandatory) 93 94 'val': bus driver delivers received byte 95 96 'ret': 0 if the byte should be acked, some errno if the byte should be nacked 97 98Another I2C master has sent a byte to us which needs to be set in 'val'. If 'ret' 99is zero, the bus driver should ack this byte. If 'ret' is an errno, then the byte 100should be nacked. 101 102* I2C_SLAVE_READ_PROCESSED (mandatory) 103 104 'val': backend returns next byte to be sent 105 106 'ret': always 0 107 108The bus driver requests the next byte to be sent to another I2C master in 109'val'. Important: This does not mean that the previous byte has been acked, it 110only means that the previous byte is shifted out to the bus! To ensure seamless 111transmission, most hardware requests the next byte when the previous one is 112still shifted out. If the master sends NACK and stops reading after the byte 113currently shifted out, this byte requested here is never used. It very likely 114needs to be sent again on the next I2C_SLAVE_READ_REQUEST, depending a bit on 115your backend, though. 116 117* I2C_SLAVE_STOP (mandatory) 118 119 'val': unused 120 121 'ret': always 0 122 123A stop condition was received. This can happen anytime and the backend should 124reset its state machine for I2C transfers to be able to receive new requests. 125 126 127Software backends 128----------------- 129 130If you want to write a software backend: 131 132* use a standard i2c_driver and its matching mechanisms 133* write the slave_callback which handles the above slave events 134 (best using a state machine) 135* register this callback via i2c_slave_register() 136 137Check the i2c-slave-eeprom driver as an example. 138 139 140Bus driver support 141------------------ 142 143If you want to add slave support to the bus driver: 144 145* implement calls to register/unregister the slave and add those to the 146 struct i2c_algorithm. When registering, you probably need to set the I2C 147 slave address and enable slave specific interrupts. If you use runtime pm, you 148 should use pm_runtime_get_sync() because your device usually needs to be 149 powered on always to be able to detect its slave address. When unregistering, 150 do the inverse of the above. 151 152* Catch the slave interrupts and send appropriate i2c_slave_events to the backend. 153 154Note that most hardware supports being master _and_ slave on the same bus. So, 155if you extend a bus driver, please make sure that the driver supports that as 156well. In almost all cases, slave support does not need to disable the master 157functionality. 158 159Check the i2c-rcar driver as an example. 160 161 162About ACK/NACK 163-------------- 164 165It is good behaviour to always ACK the address phase, so the master knows if a 166device is basically present or if it mysteriously disappeared. Using NACK to 167state being busy is troublesome. SMBus demands to always ACK the address phase, 168while the I2C specification is more loose on that. Most I2C controllers also 169automatically ACK when detecting their slave addresses, so there is no option 170to NACK them. For those reasons, this API does not support NACK in the address 171phase. 172 173Currently, there is no slave event to report if the master did ACK or NACK a 174byte when it reads from us. We could make this an optional event if the need 175arises. However, cases should be extremely rare because the master is expected 176to send STOP after that and we have an event for that. Also, keep in mind not 177all I2C controllers have the possibility to report that event. 178 179 180About buffers 181------------- 182 183During development of this API, the question of using buffers instead of just 184bytes came up. Such an extension might be possible, usefulness is unclear at 185this time of writing. Some points to keep in mind when using buffers: 186 187* Buffers should be opt-in and backend drivers will always have to support 188 byte-based transactions as the ultimate fallback anyhow because this is how 189 the majority of HW works. 190 191* For backends simulating hardware registers, buffers are largely not helpful 192 because after each byte written an action should be immediately triggered. 193 For reads, the data kept in the buffer might get stale if the backend just 194 updated a register because of internal processing. 195 196* A master can send STOP at any time. For partially transferred buffers, this 197 means additional code to handle this exception. Such code tends to be 198 error-prone. 199