i2c: Update and clean up writing-clients document

do this is to use a unique prefix for all global symbols. This is

especially important for exported symbols, but it is a good idea to do

it for non-exported symbols too. We will use the prefix `foo_' in this

tutorial, and `FOO_' for preprocessor variables.

tutorial.

The driver structure

	.shutdown	= foo_shutdown,	/* optional */

	.suspend	= foo_suspend,	/* optional */

	.resume		= foo_resume,	/* optional */

	.command	= foo_command,	/* optional */

	.command	= foo_command,	/* optional, deprecated */

}

The name field is the driver name, and must not contain spaces.  It

=================

Each client structure has a special `data' field that can point to any

structure at all.  You should use this to keep device-specific data,

especially in drivers that handle multiple I2C or SMBUS devices.  You

do not always need this, but especially for `sensors' drivers, it can

be very useful.

structure at all.  You should use this to keep device-specific data.

	/* store the value */

	void i2c_set_clientdata(struct i2c_client *client, void *data);

	/* retrieve the value */

	void *i2c_get_clientdata(const struct i2c_client *client);

An example structure is below.

  struct foo_data {

    struct i2c_client *client;

    enum chips type;       /* To keep the chips type for `sensors' drivers. */

    /* Because the i2c bus is slow, it is often useful to cache the read

       information of a chip for some time (for example, 1 or 2 seconds).

       It depends of course on the device whether this is really worthwhile

       or even sensible. */

    struct mutex update_lock;     /* When we are reading lots of information,

                                     another process should not update the

                                     below information */

    char valid;                   /* != 0 if the following fields are valid. */

    unsigned long last_updated;   /* In jiffies */

    /* Add the read information here too */

  };

Accessing the client

====================

Let's say we have a valid client structure. At some time, we will need

to gather information from the client, or write new information to the

client. How we will export this information to user-space is less 

important at this moment (perhaps we do not need to do this at all for

some obscure clients). But we need generic reading and writing routines.

client.

I have found it useful to define foo_read and foo_write function for this.

I have found it useful to define foo_read and foo_write functions for this.

For some cases, it will be easier to call the i2c functions directly,

but many chips have some kind of register-value idea that can easily

be encapsulated.

int foo_write_value(struct i2c_client *client, u8 reg, u16 value)

{

    if (reg == 0x10) /* Impossible to write - driver error! */ {

      return -1;

	if (reg == 0x10)	/* Impossible to write - driver error! */

		return -EINVAL;

	else if (reg < 0x10)	/* byte-sized register */

		return i2c_smbus_write_byte_data(client, reg, value);

	else			/* word-sized register */

device can't survive its parent in the device driver model.

Initializing the module or kernel

=================================

Initializing the driver

=======================

When the kernel is booted, or when your foo driver module is inserted,

you have to do some initializing. Fortunately, just attaching (registering)

the driver module is usually enough.

you have to do some initializing. Fortunately, just registering the

driver module is usually enough.

static int __init foo_init(void)

{

    int res;

    if ((res = i2c_add_driver(&foo_driver))) {

      printk("foo: Driver registration failed, module not inserted.\n");

      return res;

    }

    return 0;

	return i2c_add_driver(&foo_driver);

}

static void __exit foo_cleanup(void)

module_init(foo_init);

module_exit(foo_cleanup);

Note that some functions are marked by `__init', and some data structures

by `__initdata'.  These functions and structures can be removed after

kernel booting (or module loading) is completed.

Note that some functions are marked by `__init'.  These functions can

be removed after kernel booting (or module loading) is completed.

Likewise, functions marked by `__exit' are dropped by the compiler when

the code is built into the kernel, as they would never be called.

Power Management

A generic ioctl-like function call back is supported. You will seldom

need this, and its use is deprecated anyway, so newer design should not

use it. Set it to NULL.

use it.

Sending and receiving

=====================

If you want to communicate with your device, there are several functions

to do this. You can find all of them in i2c.h.

to do this. You can find all of them in <linux/i2c.h>.

If you can choose between plain i2c communication and SMBus level

communication, please use the last. All adapters understand SMBus level

commands, but only some of them understand plain i2c!

If you can choose between plain I2C communication and SMBus level

communication, please use the latter. All adapters understand SMBus level

commands, but only some of them understand plain I2C!

Plain i2c communication

Plain I2C communication

-----------------------

  extern int i2c_master_send(struct i2c_client *,const char* ,int);

  extern int i2c_master_recv(struct i2c_client *,char* ,int);

	int i2c_master_send(struct i2c_client *client, const char *buf,

			    int count);

	int i2c_master_recv(struct i2c_client *client, char *buf, int count);

These routines read and write some bytes from/to a client. The client

contains the i2c address, so you do not have to include it. The second

parameter contains the bytes the read/write, the third the length of the

buffer. Returned is the actual number of bytes read/written.

parameter contains the bytes to read/write, the third the number of bytes

to read/write (must be less than the length of the buffer.) Returned is

the actual number of bytes read/written.

  extern int i2c_transfer(struct i2c_adapter *adap, struct i2c_msg *msg,

	int i2c_transfer(struct i2c_adapter *adap, struct i2c_msg *msg,

			 int num);

This sends a series of messages. Each message can be a read or write,

and the message data itself.

You can read the file `i2c-protocol' for more information about the

actual i2c protocol.

actual I2C protocol.

SMBus communication

-------------------

  extern s32 i2c_smbus_xfer (struct i2c_adapter * adapter, u16 addr, 

                             unsigned short flags,

                             char read_write, u8 command, int size,

                             union i2c_smbus_data * data);

	s32 i2c_smbus_xfer(struct i2c_adapter *adapter, u16 addr,

			   unsigned short flags, char read_write, u8 command,

			   int size, union i2c_smbus_data *data);

This is the generic SMBus function. All functions below are implemented

in terms of it. Never use this function directly!

  extern s32 i2c_smbus_read_byte(struct i2c_client * client);

  extern s32 i2c_smbus_write_byte(struct i2c_client * client, u8 value);

  extern s32 i2c_smbus_read_byte_data(struct i2c_client * client, u8 command);

  extern s32 i2c_smbus_write_byte_data(struct i2c_client * client,

	s32 i2c_smbus_read_byte(struct i2c_client *client);

	s32 i2c_smbus_write_byte(struct i2c_client *client, u8 value);

	s32 i2c_smbus_read_byte_data(struct i2c_client *client, u8 command);

	s32 i2c_smbus_write_byte_data(struct i2c_client *client,

				      u8 command, u8 value);

  extern s32 i2c_smbus_read_word_data(struct i2c_client * client, u8 command);

  extern s32 i2c_smbus_write_word_data(struct i2c_client * client,

	s32 i2c_smbus_read_word_data(struct i2c_client *client, u8 command);

	s32 i2c_smbus_write_word_data(struct i2c_client *client,

				      u8 command, u16 value);

  extern s32 i2c_smbus_process_call(struct i2c_client *client,

	s32 i2c_smbus_process_call(struct i2c_client *client,

				   u8 command, u16 value);

  extern s32 i2c_smbus_read_block_data(struct i2c_client * client,

	s32 i2c_smbus_read_block_data(struct i2c_client *client,

				      u8 command, u8 *values);

  extern s32 i2c_smbus_write_block_data(struct i2c_client * client,

                                        u8 command, u8 length,

                                        u8 *values);

  extern s32 i2c_smbus_read_i2c_block_data(struct i2c_client * client,

	s32 i2c_smbus_write_block_data(struct i2c_client *client,

				       u8 command, u8 length, const u8 *values);

	s32 i2c_smbus_read_i2c_block_data(struct i2c_client *client,

					  u8 command, u8 length, u8 *values);

  extern s32 i2c_smbus_write_i2c_block_data(struct i2c_client * client,

	s32 i2c_smbus_write_i2c_block_data(struct i2c_client *client,

					   u8 command, u8 length,

                                            u8 *values);

					   const u8 *values);

These ones were removed from i2c-core because they had no users, but could

be added back later if needed:

  extern s32 i2c_smbus_write_quick(struct i2c_client * client, u8 value);

  extern s32 i2c_smbus_block_process_call(struct i2c_client *client,

                                          u8 command, u8 length,

                                          u8 *values)

	s32 i2c_smbus_write_quick(struct i2c_client *client, u8 value);

	s32 i2c_smbus_block_process_call(struct i2c_client *client,

					 u8 command, u8 length, u8 *values);

All these transactions return a negative errno value on failure. The 'write'

transactions return 0 on success; the 'read' transactions return the read

Below all general purpose routines are listed, that were not mentioned

before.

  /* This call returns a unique low identifier for each registered adapter.

   */

  extern int i2c_adapter_id(struct i2c_adapter *adap);

	/* Return the adapter number for a specific adapter */

	int i2c_adapter_id(struct i2c_adapter *adap);