Documentation/i2c/dev-interface.rst

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

File Facts

System
Linux kernel
Corpus path
Documentation/i2c/dev-interface.rst
Extension
.rst
Size
8986 bytes
Lines
222
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

struct i2c_rdwr_ioctl_data {
      struct i2c_msg *msgs;  /* ptr to array of simple messages */
      int nmsgs;             /* number of messages to exchange */
    }

  The msgs[] themselves contain further pointers into data buffers.
  The function will write or read data to or from that buffers depending
  on whether the I2C_M_RD flag is set in a particular message or not.
  The slave address and whether to use ten bit address mode has to be
  set in each message, overriding the values set with the above ioctl's.

``ioctl(file, I2C_SMBUS, struct i2c_smbus_ioctl_data *args)``
  If possible, use the provided ``i2c_smbus_*`` methods described below instead
  of issuing direct ioctls.

You can do plain I2C transactions by using read(2) and write(2) calls.
You do not need to pass the address byte; instead, set it through
ioctl I2C_SLAVE before you try to access the device.

You can do SMBus level transactions (see documentation file smbus-protocol.rst
for details) through the following functions::

  __s32 i2c_smbus_write_quick(int file, __u8 value);
  __s32 i2c_smbus_read_byte(int file);
  __s32 i2c_smbus_write_byte(int file, __u8 value);
  __s32 i2c_smbus_read_byte_data(int file, __u8 command);
  __s32 i2c_smbus_write_byte_data(int file, __u8 command, __u8 value);
  __s32 i2c_smbus_read_word_data(int file, __u8 command);
  __s32 i2c_smbus_write_word_data(int file, __u8 command, __u16 value);
  __s32 i2c_smbus_process_call(int file, __u8 command, __u16 value);
  __s32 i2c_smbus_block_process_call(int file, __u8 command, __u8 length,
                                     __u8 *values);
  __s32 i2c_smbus_read_block_data(int file, __u8 command, __u8 *values);
  __s32 i2c_smbus_write_block_data(int file, __u8 command, __u8 length,
                                   __u8 *values);

All these transactions return -1 on failure; you can read errno to see
what happened. The 'write' transactions return 0 on success; the
'read' transactions return the read value, except for read_block, which
returns the number of values read. The block buffers need not be longer
than 32 bytes.

The above functions are made available by linking against the libi2c library,
which is provided by the i2c-tools project.  See:
https://git.kernel.org/pub/scm/utils/i2c-tools/i2c-tools.git/.


Implementation details
======================

For the interested, here's the code flow which happens inside the kernel
when you use the /dev interface to I2C:

1) Your program opens /dev/i2c-N and calls ioctl() on it, as described in
   section "C example" above.

2) These open() and ioctl() calls are handled by the i2c-dev kernel
   driver: see i2c-dev.c:i2cdev_open() and i2c-dev.c:i2cdev_ioctl(),
   respectively. You can think of i2c-dev as a generic I2C chip driver
   that can be programmed from user-space.

3) Some ioctl() calls are for administrative tasks and are handled by
   i2c-dev directly. Examples include I2C_SLAVE (set the address of the
   device you want to access) and I2C_PEC (enable or disable SMBus error
   checking on future transactions.)

4) Other ioctl() calls are converted to in-kernel function calls by
   i2c-dev. Examples include I2C_FUNCS, which queries the I2C adapter
   functionality using i2c.h:i2c_get_functionality(), and I2C_SMBUS, which
   performs an SMBus transaction using i2c-core-smbus.c:i2c_smbus_xfer().

Annotation

Implementation Notes