Documentation/i2c/slave-interface.rst

Source file repositories/reference/linux-study-clean/Documentation/i2c/slave-interface.rst

File Facts

System
Linux kernel
Corpus path
Documentation/i2c/slave-interface.rst
Extension
.rst
Size
8172 bytes
Lines
202
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

=====================================
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.rst. The only
difference is that i2c slave backends have their own address space. So, you
have to add 0x1000 to the address you would originally request. An example for
instantiating the slave-eeprom driver from userspace at the 7 bit address 0x64
on bus 1::

  # echo slave-24c02 0x1064 > /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:

Annotation

Implementation Notes