mirror of
https://github.com/torvalds/linux.git
synced 2024-09-24 00:43:11 +00:00
i2c: Update and clean up writing-clients document
* Strip trailing white space. * Remove out-of-date or irrelevant parts. * Insist on the fact that command is deprecated. * Fix spelling mistakes and typos. * Reformat code examples and function prototypes to comply with the kernel coding style. Signed-off-by: Jean Delvare <khali@linux-fr.org>
This commit is contained in:
parent
c0589d4bc1
commit
0e47858da4
|
@ -13,7 +13,7 @@ Try to keep the kernel namespace as clean as possible. The best way to
|
||||||
do this is to use a unique prefix for all global symbols. This is
|
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
|
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
|
it for non-exported symbols too. We will use the prefix `foo_' in this
|
||||||
tutorial, and `FOO_' for preprocessor variables.
|
tutorial.
|
||||||
|
|
||||||
|
|
||||||
The driver structure
|
The driver structure
|
||||||
|
@ -49,7 +49,7 @@ static struct i2c_driver foo_driver = {
|
||||||
.shutdown = foo_shutdown, /* optional */
|
.shutdown = foo_shutdown, /* optional */
|
||||||
.suspend = foo_suspend, /* optional */
|
.suspend = foo_suspend, /* optional */
|
||||||
.resume = foo_resume, /* 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
|
The name field is the driver name, and must not contain spaces. It
|
||||||
|
@ -66,10 +66,7 @@ Extra client data
|
||||||
=================
|
=================
|
||||||
|
|
||||||
Each client structure has a special `data' field that can point to any
|
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,
|
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.
|
|
||||||
|
|
||||||
/* store the value */
|
/* store the value */
|
||||||
void i2c_set_clientdata(struct i2c_client *client, void *data);
|
void i2c_set_clientdata(struct i2c_client *client, void *data);
|
||||||
|
@ -77,35 +74,15 @@ be very useful.
|
||||||
/* retrieve the value */
|
/* retrieve the value */
|
||||||
void *i2c_get_clientdata(const struct i2c_client *client);
|
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
|
Accessing the client
|
||||||
====================
|
====================
|
||||||
|
|
||||||
Let's say we have a valid client structure. At some time, we will need
|
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
|
to gather information from the client, or write new information to the
|
||||||
client. How we will export this information to user-space is less
|
client.
|
||||||
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.
|
|
||||||
|
|
||||||
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,
|
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
|
but many chips have some kind of register-value idea that can easily
|
||||||
be encapsulated.
|
be encapsulated.
|
||||||
|
@ -123,8 +100,8 @@ literally.
|
||||||
|
|
||||||
int foo_write_value(struct i2c_client *client, u8 reg, u16 value)
|
int foo_write_value(struct i2c_client *client, u8 reg, u16 value)
|
||||||
{
|
{
|
||||||
if (reg == 0x10) /* Impossible to write - driver error! */ {
|
if (reg == 0x10) /* Impossible to write - driver error! */
|
||||||
return -1;
|
return -EINVAL;
|
||||||
else if (reg < 0x10) /* byte-sized register */
|
else if (reg < 0x10) /* byte-sized register */
|
||||||
return i2c_smbus_write_byte_data(client, reg, value);
|
return i2c_smbus_write_byte_data(client, reg, value);
|
||||||
else /* word-sized register */
|
else /* word-sized register */
|
||||||
|
@ -251,22 +228,16 @@ called automatically before the underlying I2C bus itself is removed, as a
|
||||||
device can't survive its parent in the device driver model.
|
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,
|
When the kernel is booted, or when your foo driver module is inserted,
|
||||||
you have to do some initializing. Fortunately, just attaching (registering)
|
you have to do some initializing. Fortunately, just registering the
|
||||||
the driver module is usually enough.
|
driver module is usually enough.
|
||||||
|
|
||||||
static int __init foo_init(void)
|
static int __init foo_init(void)
|
||||||
{
|
{
|
||||||
int res;
|
return i2c_add_driver(&foo_driver);
|
||||||
|
|
||||||
if ((res = i2c_add_driver(&foo_driver))) {
|
|
||||||
printk("foo: Driver registration failed, module not inserted.\n");
|
|
||||||
return res;
|
|
||||||
}
|
|
||||||
return 0;
|
|
||||||
}
|
}
|
||||||
|
|
||||||
static void __exit foo_cleanup(void)
|
static void __exit foo_cleanup(void)
|
||||||
|
@ -284,9 +255,10 @@ the driver module is usually enough.
|
||||||
module_init(foo_init);
|
module_init(foo_init);
|
||||||
module_exit(foo_cleanup);
|
module_exit(foo_cleanup);
|
||||||
|
|
||||||
Note that some functions are marked by `__init', and some data structures
|
Note that some functions are marked by `__init'. These functions can
|
||||||
by `__initdata'. These functions and structures can be removed after
|
be removed after kernel booting (or module loading) is completed.
|
||||||
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
|
Power Management
|
||||||
|
@ -321,32 +293,34 @@ Command function
|
||||||
|
|
||||||
A generic ioctl-like function call back is supported. You will seldom
|
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
|
need this, and its use is deprecated anyway, so newer design should not
|
||||||
use it. Set it to NULL.
|
use it.
|
||||||
|
|
||||||
|
|
||||||
Sending and receiving
|
Sending and receiving
|
||||||
=====================
|
=====================
|
||||||
|
|
||||||
If you want to communicate with your device, there are several functions
|
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
|
If you can choose between plain I2C communication and SMBus level
|
||||||
communication, please use the last. All adapters understand SMBus level
|
communication, please use the latter. All adapters understand SMBus level
|
||||||
commands, but only some of them understand plain i2c!
|
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);
|
int i2c_master_send(struct i2c_client *client, const char *buf,
|
||||||
extern int i2c_master_recv(struct i2c_client *,char* ,int);
|
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
|
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
|
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
|
parameter contains the bytes to read/write, the third the number of bytes
|
||||||
buffer. Returned is the actual number of bytes read/written.
|
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);
|
int num);
|
||||||
|
|
||||||
This sends a series of messages. Each message can be a read or write,
|
This sends a series of messages. Each message can be a read or write,
|
||||||
|
@ -356,49 +330,45 @@ for each message the client address, the number of bytes of the message
|
||||||
and the message data itself.
|
and the message data itself.
|
||||||
|
|
||||||
You can read the file `i2c-protocol' for more information about the
|
You can read the file `i2c-protocol' for more information about the
|
||||||
actual i2c protocol.
|
actual I2C protocol.
|
||||||
|
|
||||||
|
|
||||||
SMBus communication
|
SMBus communication
|
||||||
-------------------
|
-------------------
|
||||||
|
|
||||||
extern s32 i2c_smbus_xfer (struct i2c_adapter * adapter, u16 addr,
|
s32 i2c_smbus_xfer(struct i2c_adapter *adapter, u16 addr,
|
||||||
unsigned short flags,
|
unsigned short flags, char read_write, u8 command,
|
||||||
char read_write, u8 command, int size,
|
int size, union i2c_smbus_data *data);
|
||||||
union i2c_smbus_data * data);
|
|
||||||
|
|
||||||
This is the generic SMBus function. All functions below are implemented
|
This is the generic SMBus function. All functions below are implemented
|
||||||
in terms of it. Never use this function directly!
|
in terms of it. Never use this function directly!
|
||||||
|
|
||||||
|
s32 i2c_smbus_read_byte(struct i2c_client *client);
|
||||||
extern s32 i2c_smbus_read_byte(struct i2c_client * client);
|
s32 i2c_smbus_write_byte(struct i2c_client *client, u8 value);
|
||||||
extern s32 i2c_smbus_write_byte(struct i2c_client * client, u8 value);
|
s32 i2c_smbus_read_byte_data(struct i2c_client *client, u8 command);
|
||||||
extern s32 i2c_smbus_read_byte_data(struct i2c_client * client, u8 command);
|
s32 i2c_smbus_write_byte_data(struct i2c_client *client,
|
||||||
extern s32 i2c_smbus_write_byte_data(struct i2c_client * client,
|
|
||||||
u8 command, u8 value);
|
u8 command, u8 value);
|
||||||
extern s32 i2c_smbus_read_word_data(struct i2c_client * client, u8 command);
|
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_write_word_data(struct i2c_client *client,
|
||||||
u8 command, u16 value);
|
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);
|
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);
|
u8 command, u8 *values);
|
||||||
extern s32 i2c_smbus_write_block_data(struct i2c_client * client,
|
s32 i2c_smbus_write_block_data(struct i2c_client *client,
|
||||||
u8 command, u8 length,
|
u8 command, u8 length, const u8 *values);
|
||||||
u8 *values);
|
s32 i2c_smbus_read_i2c_block_data(struct i2c_client *client,
|
||||||
extern s32 i2c_smbus_read_i2c_block_data(struct i2c_client * client,
|
|
||||||
u8 command, u8 length, u8 *values);
|
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 command, u8 length,
|
||||||
u8 *values);
|
const u8 *values);
|
||||||
|
|
||||||
These ones were removed from i2c-core because they had no users, but could
|
These ones were removed from i2c-core because they had no users, but could
|
||||||
be added back later if needed:
|
be added back later if needed:
|
||||||
|
|
||||||
extern s32 i2c_smbus_write_quick(struct i2c_client * client, u8 value);
|
s32 i2c_smbus_write_quick(struct i2c_client *client, u8 value);
|
||||||
extern s32 i2c_smbus_block_process_call(struct i2c_client *client,
|
s32 i2c_smbus_block_process_call(struct i2c_client *client,
|
||||||
u8 command, u8 length,
|
u8 command, u8 length, u8 *values);
|
||||||
u8 *values)
|
|
||||||
|
|
||||||
All these transactions return a negative errno value on failure. The 'write'
|
All these transactions return a negative errno value on failure. The 'write'
|
||||||
transactions return 0 on success; the 'read' transactions return the read
|
transactions return 0 on success; the 'read' transactions return the read
|
||||||
|
@ -415,7 +385,5 @@ General purpose routines
|
||||||
Below all general purpose routines are listed, that were not mentioned
|
Below all general purpose routines are listed, that were not mentioned
|
||||||
before.
|
before.
|
||||||
|
|
||||||
/* This call returns a unique low identifier for each registered adapter.
|
/* Return the adapter number for a specific adapter */
|
||||||
*/
|
int i2c_adapter_id(struct i2c_adapter *adap);
|
||||||
extern int i2c_adapter_id(struct i2c_adapter *adap);
|
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue
Block a user