===============
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
it for non-exported symbols too. We will use the prefix `foo_' in this
-tutorial, and `FOO_' for preprocessor variables.
+tutorial.
The driver structure
====================
Usually, you will implement a single driver structure, and instantiate
-all clients from it. Remember, a driver structure contains general access
+all clients from it. Remember, a driver structure contains general access
routines, and should be zero-initialized except for fields with data you
provide. A client structure holds device-specific information like the
driver model device node, and its I2C address.
.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
should match the module name (if the driver can be compiled as a module),
although you can use MODULE_ALIAS (passing "foo" in this example) to add
another name for the module. If the driver name doesn't match the module
name, the module won't be automatically loaded (hotplug/coldplug).
-All other fields are for call-back functions which will be explained
+All other fields are for call-back functions which will be explained
below.
=================
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.
The below functions are simple examples, and should not be copied
literally.
- int foo_read_value(struct i2c_client *client, u8 reg)
- {
- if (reg < 0x10) /* byte-sized register */
- return i2c_smbus_read_byte_data(client,reg);
- else /* word-sized register */
- return i2c_smbus_read_word_data(client,reg);
- }
-
- int foo_write_value(struct i2c_client *client, u8 reg, u16 value)
- {
- if (reg == 0x10) /* Impossible to write - driver error! */ {
- return -1;
- else if (reg < 0x10) /* byte-sized register */
- return i2c_smbus_write_byte_data(client,reg,value);
- else /* word-sized register */
- return i2c_smbus_write_word_data(client,reg,value);
- }
+int foo_read_value(struct i2c_client *client, u8 reg)
+{
+ if (reg < 0x10) /* byte-sized register */
+ return i2c_smbus_read_byte_data(client, reg);
+ else /* word-sized register */
+ return i2c_smbus_read_word_data(client, reg);
+}
+
+int foo_write_value(struct i2c_client *client, u8 reg, u16 value)
+{
+ 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 */
+ return i2c_smbus_write_word_data(client, reg, value);
+}
Probing and attaching
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.
+When the kernel is booted, or when your foo driver module is inserted,
+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;
- }
+static int __init foo_init(void)
+{
+ return i2c_add_driver(&foo_driver);
+}
- static void __exit foo_cleanup(void)
- {
- i2c_del_driver(&foo_driver);
- }
+static void __exit foo_cleanup(void)
+{
+ i2c_del_driver(&foo_driver);
+}
- /* Substitute your own name and email address */
- MODULE_AUTHOR("Frodo Looijaard <frodol@dds.nl>"
- MODULE_DESCRIPTION("Driver for Barf Inc. Foo I2C devices");
+/* Substitute your own name and email address */
+MODULE_AUTHOR("Frodo Looijaard <frodol@dds.nl>"
+MODULE_DESCRIPTION("Driver for Barf Inc. Foo I2C devices");
- /* a few non-GPL license types are also allowed */
- MODULE_LICENSE("GPL");
+/* a few non-GPL license types are also allowed */
+MODULE_LICENSE("GPL");
- module_init(foo_init);
- module_exit(foo_cleanup);
+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.
-
- extern int i2c_transfer(struct i2c_adapter *adap, struct i2c_msg *msg,
- int num);
+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.
+
+ 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 they can be mixed in any way. The transactions are combined: no
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);
-
- 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,
- 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,
- u8 command, u16 value);
- extern s32 i2c_smbus_process_call(struct i2c_client *client,
- u8 command, u16 value);
- extern 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,
- u8 command, u8 length, u8 *values);
- extern s32 i2c_smbus_write_i2c_block_data(struct i2c_client * client,
- u8 command, u8 length,
- u8 *values);
+ 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!
+
+ 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);
+ 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);
+ s32 i2c_smbus_process_call(struct i2c_client *client,
+ u8 command, u16 value);
+ s32 i2c_smbus_read_block_data(struct i2c_client *client,
+ u8 command, u8 *values);
+ 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);
+ s32 i2c_smbus_write_i2c_block_data(struct i2c_client *client,
+ u8 command, u8 length,
+ 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);
git://ftp.safe.ca / safe / jmp / linux-2.6 / commitdiff