Documentation/i2c/slave-interface

   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'. A quick example for
  35 instantiating 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
  39 Each backend should come with separate documentation to describe its specific
  40 behaviour and setup.
  41
  42
  43 Developer manual
  44 ================
  45
  46 First, the events which are used by the bus driver and the backend will be
  47 described in detail. After that, some implementation hints for extending bus
  48 drivers and writing backends will be given.
  49
  50
  51 I2C slave events
  52 ----------------
  53
  54 The 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
  59 types described hereafter. 'val' holds an u8 value for the data byte to be
  60 read/written and is thus bidirectional. The pointer to val must always be
  61 provided even if val is not used for an event, i.e. don't use NULL here. 'ret'
  62 is the return value from the backend. Mandatory events must be provided by the
  63 bus drivers and must be checked for by backend drivers.
  64
  65 Event types:
  66
  67 * I2C_SLAVE_WRITE_REQUESTED (mandatory)
  68
  69 'val': unused
  70 'ret': always 0
  71
  72 Another I2C master wants to write data to us. This event should be sent once
  73 our own address and the write bit was detected. The data did not arrive yet, so
  74 there is nothing to process or return. Wakeup or initialization probably needs
  75 to 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
  82 Another I2C master wants to read data from us. This event should be sent once
  83 our own address and the read bit was detected. After returning, the bus driver
  84 should 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
  91 Another I2C master has sent a byte to us which needs to be set in 'val'. If 'ret'
  92 is zero, the bus driver should ack this byte. If 'ret' is an errno, then the byte
  93 should be nacked.
  94
  95 * I2C_SLAVE_READ_PROCESSED (mandatory)
  96
  97 'val': backend returns next byte to be sent
  98 'ret': always 0
  99
 100 The 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
 102 only means that the previous byte is shifted out to the bus! To ensure seamless
 103 transmission, most hardware requests the next byte when the previous one is
 104 still shifted out. If the master sends NACK and stops reading after the byte
 105 currently shifted out, this byte requested here is never used. It very likely
 106 needs to be sent again on the next I2C_SLAVE_READ_REQUEST, depending a bit on
 107 your backend, though.
 108
 109 * I2C_SLAVE_STOP (mandatory)
 110
 111 'val': unused
 112 'ret': always 0
 113
 114 A stop condition was received. This can happen anytime and the backend should
 115 reset its state machine for I2C transfers to be able to receive new requests.
 116
 117
 118 Software backends
 119 -----------------
 120
 121 If 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
 128 Check the i2c-slave-eeprom driver as an example.
 129
 130
 131 Bus driver support
 132 ------------------
 133
 134 If 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
 145 Check the i2c-rcar driver as an example.
 146
 147
 148 About ACK/NACK
 149 --------------
 150
 151 It is good behaviour to always ACK the address phase, so the master knows if a
 152 device is basically present or if it mysteriously disappeared. Using NACK to
 153 state being busy is troublesome. SMBus demands to always ACK the address phase,
 154 while the I2C specification is more loose on that. Most I2C controllers also
 155 automatically ACK when detecting their slave addresses, so there is no option
 156 to NACK them. For those reasons, this API does not support NACK in the address
 157 phase.
 158
 159 Currently, there is no slave event to report if the master did ACK or NACK a
 160 byte when it reads from us. We could make this an optional event if the need
 161 arises. However, cases should be extremely rare because the master is expected
 162 to send STOP after that and we have an event for that. Also, keep in mind not
 163 all I2C controllers have the possibility to report that event.
 164
 165
 166 About buffers
 167 -------------
 168
 169 During development of this API, the question of using buffers instead of just
 170 bytes came up. Such an extension might be possible, usefulness is unclear at
 171 this 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