mirror of
https://github.com/edk2-porting/linux-next.git
synced 2024-12-23 04:34:11 +08:00
24867481b8
Pull i2c updates from Wolfram Sang: "Highlights: - new drivers for Mediatek I2C, APM X-Gene, Broadcom Settop - major updates to at91, davinci - bugfixes to the mux infrastructure when dealing with the new quirk mechanism - more users for the bus recovery feature - further improvements to the slave framework Plus the usual bunch of smaller driver and core improvements and fixes. There is one patch removing old code from an ARM platform. This has been acked by the sh_mobile maintainer Simon Horman" * 'i2c/for-4.2' of git://git.kernel.org/pub/scm/linux/kernel/git/wsa/linux: (48 commits) i2c: busses: i2c-bcm2835: limits cdiv to allowed values i2c: sh_mobile: use proper type for timeout i2c: sh_mobile: use adapter default for timeout i2c: rcar: use proper type for timeout i2c: rcar: use adapter default for timeout i2c: designware: Make sure the device is suspended before disabling runtime PM i2c: tegra: apply size limit quirk i2c: tegra: don't advertise SMBUS_QUICK i2c: octeon: remove unused signal handling i2c: davinci: Optimize SCL generation i2c: mux: pca954x: Use __i2c_transfer because of quirks i2c: mux: Use __i2c_transfer() instead of calling parent's master_xfer() i2c: use parent adapter quirks in mux i2c: bcm2835: clear reserved bits in S-Register ARM: shmobile: r8a7740: remove I2C errata handling i2c: sh_mobile: add errata workaround i2c: at91: fix code checker warnings i2c: busses: xgene-slimpro: fix incorrect __init declation for probe i2c: davinci: Avoid sending to own address i2c: davinci: Refactor i2c_davinci_wait_bus_not_busy() ...
185 lines
7.1 KiB
Plaintext
185 lines
7.1 KiB
Plaintext
Linux I2C slave interface description
|
|
=====================================
|
|
|
|
by Wolfram Sang <wsa@sang-engineering.com> in 2014-15
|
|
|
|
Linux can also be an I2C slave if the I2C controller in use has slave
|
|
functionality. For that to work, one needs slave support in the bus driver plus
|
|
a hardware independent software backend providing the actual functionality. An
|
|
example for the latter is the slave-eeprom driver, which acts as a dual memory
|
|
driver. While another I2C master on the bus can access it like a regular
|
|
EEPROM, the Linux I2C slave can access the content via sysfs and handle data as
|
|
needed. The backend driver and the I2C bus driver communicate via events. Here
|
|
is a small graph visualizing the data flow and the means by which data is
|
|
transported. The dotted line marks only one example. The backend could also
|
|
use a character device, be in-kernel only, or something completely different:
|
|
|
|
|
|
e.g. sysfs I2C slave events I/O registers
|
|
+-----------+ v +---------+ v +--------+ v +------------+
|
|
| Userspace +........+ Backend +-----------+ Driver +-----+ Controller |
|
|
+-----------+ +---------+ +--------+ +------------+
|
|
| |
|
|
----------------------------------------------------------------+-- I2C
|
|
--------------------------------------------------------------+---- Bus
|
|
|
|
Note: Technically, there is also the I2C core between the backend and the
|
|
driver. However, at this time of writing, the layer is transparent.
|
|
|
|
|
|
User manual
|
|
===========
|
|
|
|
I2C slave backends behave like standard I2C clients. So, you can instantiate
|
|
them as described in the document 'instantiating-devices'. A quick example for
|
|
instantiating the slave-eeprom driver from userspace at address 0x64 on bus 1:
|
|
|
|
# echo slave-24c02 0x64 > /sys/bus/i2c/devices/i2c-1/new_device
|
|
|
|
Each backend should come with separate documentation to describe its specific
|
|
behaviour and setup.
|
|
|
|
|
|
Developer manual
|
|
================
|
|
|
|
First, the events which are used by the bus driver and the backend will be
|
|
described in detail. After that, some implementation hints for extending bus
|
|
drivers and writing backends will be given.
|
|
|
|
|
|
I2C slave events
|
|
----------------
|
|
|
|
The bus driver sends an event to the backend using the following function:
|
|
|
|
ret = i2c_slave_event(client, event, &val)
|
|
|
|
'client' describes the i2c slave device. 'event' is one of the special event
|
|
types described hereafter. 'val' holds an u8 value for the data byte to be
|
|
read/written and is thus bidirectional. The pointer to val must always be
|
|
provided even if val is not used for an event, i.e. don't use NULL here. 'ret'
|
|
is the return value from the backend. Mandatory events must be provided by the
|
|
bus drivers and must be checked for by backend drivers.
|
|
|
|
Event types:
|
|
|
|
* I2C_SLAVE_WRITE_REQUESTED (mandatory)
|
|
|
|
'val': unused
|
|
'ret': always 0
|
|
|
|
Another I2C master wants to write data to us. This event should be sent once
|
|
our own address and the write bit was detected. The data did not arrive yet, so
|
|
there is nothing to process or return. Wakeup or initialization probably needs
|
|
to be done, though.
|
|
|
|
* I2C_SLAVE_READ_REQUESTED (mandatory)
|
|
|
|
'val': backend returns first byte to be sent
|
|
'ret': always 0
|
|
|
|
Another I2C master wants to read data from us. This event should be sent once
|
|
our own address and the read bit was detected. After returning, the bus driver
|
|
should transmit the first byte.
|
|
|
|
* I2C_SLAVE_WRITE_RECEIVED (mandatory)
|
|
|
|
'val': bus driver delivers received byte
|
|
'ret': 0 if the byte should be acked, some errno if the byte should be nacked
|
|
|
|
Another I2C master has sent a byte to us which needs to be set in 'val'. If 'ret'
|
|
is zero, the bus driver should ack this byte. If 'ret' is an errno, then the byte
|
|
should be nacked.
|
|
|
|
* I2C_SLAVE_READ_PROCESSED (mandatory)
|
|
|
|
'val': backend returns next byte to be sent
|
|
'ret': always 0
|
|
|
|
The bus driver requests the next byte to be sent to another I2C master in
|
|
'val'. Important: This does not mean that the previous byte has been acked, it
|
|
only means that the previous byte is shifted out to the bus! To ensure seamless
|
|
transmission, most hardware requests the next byte when the previous one is
|
|
still shifted out. If the master sends NACK and stops reading after the byte
|
|
currently shifted out, this byte requested here is never used. It very likely
|
|
needs to be sent again on the next I2C_SLAVE_READ_REQUEST, depending a bit on
|
|
your backend, though.
|
|
|
|
* I2C_SLAVE_STOP (mandatory)
|
|
|
|
'val': unused
|
|
'ret': always 0
|
|
|
|
A stop condition was received. This can happen anytime and the backend should
|
|
reset its state machine for I2C transfers to be able to receive new requests.
|
|
|
|
|
|
Software backends
|
|
-----------------
|
|
|
|
If you want to write a software backend:
|
|
|
|
* use a standard i2c_driver and its matching mechanisms
|
|
* write the slave_callback which handles the above slave events
|
|
(best using a state machine)
|
|
* register this callback via i2c_slave_register()
|
|
|
|
Check the i2c-slave-eeprom driver as an example.
|
|
|
|
|
|
Bus driver support
|
|
------------------
|
|
|
|
If you want to add slave support to the bus driver:
|
|
|
|
* implement calls to register/unregister the slave and add those to the
|
|
struct i2c_algorithm. When registering, you probably need to set the i2c
|
|
slave address and enable slave specific interrupts. If you use runtime pm, you
|
|
should use pm_runtime_forbid() because your device usually needs to be powered
|
|
on always to be able to detect its slave address. When unregistering, do the
|
|
inverse of the above.
|
|
|
|
* Catch the slave interrupts and send appropriate i2c_slave_events to the backend.
|
|
|
|
Check the i2c-rcar driver as an example.
|
|
|
|
|
|
About ACK/NACK
|
|
--------------
|
|
|
|
It is good behaviour to always ACK the address phase, so the master knows if a
|
|
device is basically present or if it mysteriously disappeared. Using NACK to
|
|
state being busy is troublesome. SMBus demands to always ACK the address phase,
|
|
while the I2C specification is more loose on that. Most I2C controllers also
|
|
automatically ACK when detecting their slave addresses, so there is no option
|
|
to NACK them. For those reasons, this API does not support NACK in the address
|
|
phase.
|
|
|
|
Currently, there is no slave event to report if the master did ACK or NACK a
|
|
byte when it reads from us. We could make this an optional event if the need
|
|
arises. However, cases should be extremely rare because the master is expected
|
|
to send STOP after that and we have an event for that. Also, keep in mind not
|
|
all I2C controllers have the possibility to report that event.
|
|
|
|
|
|
About buffers
|
|
-------------
|
|
|
|
During development of this API, the question of using buffers instead of just
|
|
bytes came up. Such an extension might be possible, usefulness is unclear at
|
|
this time of writing. Some points to keep in mind when using buffers:
|
|
|
|
* Buffers should be opt-in and slave drivers will always have to support
|
|
byte-based transactions as the ultimate fallback because this is how the
|
|
majority of HW works.
|
|
|
|
* For backends simulating hardware registers, buffers are not helpful because
|
|
on writes an action should be immediately triggered. For reads, the data in
|
|
the buffer might get stale.
|
|
|
|
* A master can send STOP at any time. For partially transferred buffers, this
|
|
means additional code to handle this exception. Such code tends to be
|
|
error-prone.
|
|
|