[PATCH 2/2] docs: i2c: dev-interface: document the actual implementation

[Jean Delvare <jdelvare@suse.de>]

The old i2c-dev API based on inline functions is long gone, we have
libi2c now which implements the same as real functions and comes with
complete API documentation. Update the dev-interface documentation
file accordingly to only mention what can be done without the
library, and redirect the reader to the libi2c manual page for the
rest.

Signed-off-by: Jean Delvare <jdelvare@suse.de>
Reported-by: Lei YU <mine260309@gmail.com>
Cc: Wolfram Sang <wsa@the-dreams.de>
Cc: Luca Ceresoli <luca@lucaceresoli.net>
---
 Documentation/i2c/dev-interface.rst |   67 ++++++++++++++++--------------------
 1 file changed, 30 insertions(+), 37 deletions(-)

--- linux-5.4.orig/Documentation/i2c/dev-interface.rst	2020-01-16 10:32:18.436175325 +0100
+++ linux-5.4/Documentation/i2c/dev-interface.rst	2020-01-16 10:32:25.205247017 +0100
@@ -22,10 +22,11 @@ C example
 =========
 
 So let's say you want to access an I2C adapter from a C program.
-First, you need to include these two headers::
+First, you need to include these three header files::
 
+  #include <linux/i2c.h>
   #include <linux/i2c-dev.h>
-  #include <i2c/smbus.h>
+  #include <sys/ioctl.h>
 
 Now, you have to decide which adapter you want to access. You should
 inspect /sys/class/i2c-dev/ or run "i2cdetect -l" to decide this.
@@ -62,19 +63,23 @@ I2C to communicate with your device. SMB
   __u8 reg = 0x10; /* Device register to access */
   __s32 res;
   char buf[10];
+  struct i2c_smbus_ioctl_data args;
+  union i2c_smbus_data data;
 
   /* Using SMBus commands */
-  res = i2c_smbus_read_word_data(file, reg);
+  args.read_write = I2C_SMBUS_READ;
+  args.command = reg;
+  args.size = I2C_SMBUS_WORD_DATA;
+  args.data = &data;
+
+  res = ioctl(file, I2C_SMBUS, &args);
   if (res < 0) {
     /* ERROR HANDLING: I2C transaction failed */
   } else {
-    /* res contains the read word */
+    /* data contains the read word */
   }
 
-  /*
-   * Using I2C Write, equivalent of
-   * i2c_smbus_write_word_data(file, reg, 0x6543)
-   */
+  /* Using I2C Write */
   buf[0] = reg;
   buf[1] = 0x43;
   buf[2] = 0x65;
@@ -82,7 +87,7 @@ I2C to communicate with your device. SMB
     /* ERROR HANDLING: I2C transaction failed */
   }
 
-  /* Using I2C Read, equivalent of i2c_smbus_read_byte(file) */
+  /* Using I2C Read */
   if (read(file, buf, 1) != 1) {
     /* ERROR HANDLING: I2C transaction failed */
   } else {
@@ -93,10 +98,8 @@ Note that only a subset of the I2C and S
 the means of read() and write() calls. In particular, so-called combined
 transactions (mixing read and write messages in the same transaction)
 aren't supported. For this reason, this interface is almost never used by
-user-space programs.
-
-IMPORTANT: because of the use of inline functions, you *have* to use
-'-O' or some variation when you compile your program!
+user-space programs. See the I2C_RDWR ioctl below for combined transaction
+support.
 
 
 Full interface description
@@ -107,7 +110,11 @@ Full interface description
 ``ioctl(file, I2C_SLAVE, long addr)``
   Change slave address. The address is passed in the 7 lower bits of the
   argument (except for 10 bit addresses, passed in the 10 lower bits in this
-  case).
+  case). Fails if the address is already busy.
+
+``ioctl(file, I2C_SLAVE_FORCE, long addr)``
+  Same as I2C_SLAVE but succeeds even if the address was already busy.
+  Dangerous, don't use.
 
 ``ioctl(file, I2C_TENBIT, long select)``
   Selects ten bit addresses if select not equals 0, selects normal 7 bit
@@ -148,30 +155,16 @@ You can do plain I2C transactions by usi
 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
-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_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/.
+C Library
+=========
+
+For SMBus level transactions you will want to use libi2c which offers a
+much nicer API similar to the in-kernel API. See the libi2c(3) manual page
+for details. The library is part of i2c-tools:
+https://git.kernel.org/pub/scm/utils/i2c-tools/i2c-tools.git/
+
+Python bindings are also available for libi2c, in the same project.
 
 
 Implementation details


-- 
Jean Delvare
SUSE L3 Support