i2c: Improve the functionality documentation
Attempt to make the documentation about the I2C/SMBus functionality
checking API clearer.
Signed-off-by: Jean Delvare <khali@linux-fr.org>
diff --git a/Documentation/i2c/functionality b/Documentation/i2c/functionality
index 60cca24..42c17c1 100644
--- a/Documentation/i2c/functionality
+++ b/Documentation/i2c/functionality
@@ -51,26 +51,38 @@
the transparent emulation layer)
-ALGORITHM/ADAPTER IMPLEMENTATION
---------------------------------
+ADAPTER IMPLEMENTATION
+----------------------
-When you write a new algorithm driver, you will have to implement a
-function callback `functionality', that gets an i2c_adapter structure
-pointer as its only parameter:
+When you write a new adapter driver, you will have to implement a
+function callback `functionality'. Typical implementations are given
+below.
- struct i2c_algorithm {
- /* Many other things of course; check <linux/i2c.h>! */
- u32 (*functionality) (struct i2c_adapter *);
- }
+A typical SMBus-only adapter would list all the SMBus transactions it
+supports. This example comes from the i2c-piix4 driver:
-A typically implementation is given below, from i2c-algo-bit.c:
-
- static u32 bit_func(struct i2c_adapter *adap)
+ static u32 piix4_func(struct i2c_adapter *adapter)
{
- return I2C_FUNC_SMBUS_EMUL | I2C_FUNC_10BIT_ADDR |
- I2C_FUNC_PROTOCOL_MANGLING;
+ return I2C_FUNC_SMBUS_QUICK | I2C_FUNC_SMBUS_BYTE |
+ I2C_FUNC_SMBUS_BYTE_DATA | I2C_FUNC_SMBUS_WORD_DATA |
+ I2C_FUNC_SMBUS_BLOCK_DATA;
}
+A typical full-I2C adapter would use the following (from the i2c-pxa
+driver):
+
+ static u32 i2c_pxa_functionality(struct i2c_adapter *adap)
+ {
+ return I2C_FUNC_I2C | I2C_FUNC_SMBUS_EMUL;
+ }
+
+I2C_FUNC_SMBUS_EMUL includes all the SMBus transactions (with the
+addition of I2C block transactions) which i2c-core can emulate using
+I2C_FUNC_I2C without any help from the adapter driver. The idea is
+to let the client drivers check for the support of SMBus functions
+without having to care whether the said functions are implemented in
+hardware by the adapter, or emulated in software by i2c-core on top
+of an I2C adapter.
CLIENT CHECKING
@@ -78,36 +90,33 @@
Before a client tries to attach to an adapter, or even do tests to check
whether one of the devices it supports is present on an adapter, it should
-check whether the needed functionality is present. There are two functions
-defined which should be used instead of calling the functionality hook
-in the algorithm structure directly:
+check whether the needed functionality is present. The typical way to do
+this is (from the lm75 driver):
- /* Return the functionality mask */
- extern u32 i2c_get_functionality (struct i2c_adapter *adap);
-
- /* Return 1 if adapter supports everything we need, 0 if not. */
- extern int i2c_check_functionality (struct i2c_adapter *adap, u32 func);
-
-This is a typical way to use these functions (from the writing-clients
-document):
- int foo_detect_client(struct i2c_adapter *adapter, int address,
- unsigned short flags, int kind)
+ static int lm75_detect(...)
{
- /* Define needed variables */
-
- /* As the very first action, we check whether the adapter has the
- needed functionality: we need the SMBus read_word_data,
- write_word_data and write_byte functions in this example. */
- if (!i2c_check_functionality(adapter,I2C_FUNC_SMBUS_WORD_DATA |
- I2C_FUNC_SMBUS_WRITE_BYTE))
- goto ERROR0;
-
- /* Now we can do the real detection */
-
- ERROR0:
- /* Return an error */
+ (...)
+ if (!i2c_check_functionality(adapter, I2C_FUNC_SMBUS_BYTE_DATA |
+ I2C_FUNC_SMBUS_WORD_DATA))
+ goto exit;
+ (...)
}
+Here, the lm75 driver checks if the adapter can do both SMBus byte data
+and SMBus word data transactions. If not, then the driver won't work on
+this adapter and there's no point in going on. If the check above is
+successful, then the driver knows that it can call the following
+functions: i2c_smbus_read_byte_data(), i2c_smbus_write_byte_data(),
+i2c_smbus_read_word_data() and i2c_smbus_write_word_data(). As a rule of
+thumb, the functionality constants you test for with
+i2c_check_functionality() should match exactly the i2c_smbus_* functions
+which you driver is calling.
+
+Note that the check above doesn't tell whether the functionalities are
+implemented in hardware by the underlying adapter or emulated in
+software by i2c-core. Client drivers don't have to care about this, as
+i2c-core will transparently implement SMBus transactions on top of I2C
+adapters.
CHECKING THROUGH /DEV
@@ -116,19 +125,19 @@
If you try to access an adapter from a userspace program, you will have
to use the /dev interface. You will still have to check whether the
functionality you need is supported, of course. This is done using
-the I2C_FUNCS ioctl. An example, adapted from the lm_sensors i2cdetect
-program, is below:
+the I2C_FUNCS ioctl. An example, adapted from the i2cdetect program, is
+below:
int file;
- if (file = open("/dev/i2c-0",O_RDWR) < 0) {
+ if (file = open("/dev/i2c-0", O_RDWR) < 0) {
/* Some kind of error handling */
exit(1);
}
- if (ioctl(file,I2C_FUNCS,&funcs) < 0) {
+ if (ioctl(file, I2C_FUNCS, &funcs) < 0) {
/* Some kind of error handling */
exit(1);
}
- if (! (funcs & I2C_FUNC_SMBUS_QUICK)) {
+ if (!(funcs & I2C_FUNC_SMBUS_QUICK)) {
/* Oops, the needed functionality (SMBus write_quick function) is
not available! */
exit(1);