Usually, you will implement a single driver structure, and instantiate
all clients from it. Remember, a driver structure contains general access
-routines, a client structure specific information like the actual I2C
-address.
+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.
static struct i2c_driver foo_driver = {
- .owner = THIS_MODULE,
- .name = "Foo version 2.3 driver",
- .flags = I2C_DF_NOTIFY,
- .attach_adapter = &foo_attach_adapter,
- .detach_client = &foo_detach_client,
- .command = &foo_command /* may be NULL */
+ .driver = {
+ .name = "foo",
+ },
+ .attach_adapter = foo_attach_adapter,
+ .detach_client = foo_detach_client,
+ .shutdown = foo_shutdown, /* optional */
+ .suspend = foo_suspend, /* optional */
+ .resume = foo_resume, /* optional */
+ .command = foo_command, /* optional */
}
-The name can be chosen freely, and may be upto 40 characters long. Please
-use something descriptive here.
-
-Don't worry about the flags field; just put I2C_DF_NOTIFY into it. This
-means that your driver will be notified when new adapters are found.
-This is almost always what you want.
+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.
All other fields are for call-back functions which will be explained
below.
-There use to be two additional fields in this structure, inc_use et dec_use,
-for module usage count, but these fields were obsoleted and removed.
-
Extra client data
=================
-The client structure has a special `data' field that can point to any
-structure at all. You can use this to keep client-specific data. You
+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.
+ /* store the value */
+ void i2c_set_clientdata(struct i2c_client *client, void *data);
+
+ /* retrieve the value */
+ void *i2c_get_clientdata(struct i2c_client *client);
+
An example structure is below.
struct foo_data {
+ struct i2c_client client;
struct semaphore lock; /* For ISA access in `sensors' drivers. */
int sysctl_id; /* To keep the /proc directory entry for
`sensors' drivers. */
if (is_isa) {
/* Discard immediately if this ISA range is already used */
+ /* FIXME: never use check_region(), only request_region() */
if (check_region(address,FOO_EXTENT))
goto ERROR0;
client structure, even though we cannot fill it completely yet.
But it allows us to access several i2c functions safely */
- /* Note that we reserve some space for foo_data too. If you don't
- need it, remove it. We do it here to help to lessen memory
- fragmentation. */
- if (! (new_client = kmalloc(sizeof(struct i2c_client) +
- sizeof(struct foo_data),
- GFP_KERNEL))) {
+ if (!(data = kzalloc(sizeof(struct foo_data), GFP_KERNEL))) {
err = -ENOMEM;
goto ERROR0;
}
- /* This is tricky, but it will set the data to the right value. */
- client->data = new_client + 1;
- data = (struct foo_data *) (client->data);
+ new_client = &data->client;
+ i2c_set_clientdata(new_client, data);
new_client->addr = address;
- new_client->data = data;
new_client->adapter = adapter;
new_client->driver = &foo_driver;
new_client->flags = 0;
release_region(address,FOO_EXTENT);
/* SENSORS ONLY END */
ERROR1:
- kfree(new_client);
+ kfree(data);
ERROR0:
return err;
}
release_region(client->addr,LM78_EXTENT);
/* HYBRID SENSORS CHIP ONLY END */
- kfree(client); /* Frees client data too, if allocated at the same time */
+ kfree(i2c_get_clientdata(client));
return 0;
}
by `__init_data'. Hose functions and structures can be removed after
kernel booting (or module loading) is completed.
+
+Power Management
+================
+
+If your I2C device needs special handling when entering a system low
+power state -- like putting a transceiver into a low power mode, or
+activating a system wakeup mechanism -- do that in the suspend() method.
+The resume() method should reverse what the suspend() method does.
+
+These are standard driver model calls, and they work just like they
+would for any other driver stack. The calls can sleep, and can use
+I2C messaging to the device being suspended or resumed (since their
+parent I2C adapter is active when these calls are issued, and IRQs
+are still enabled).
+
+
+System Shutdown
+===============
+
+If your I2C device needs special handling when the system shuts down
+or reboots (including kexec) -- like turning something off -- use a
+shutdown() method.
+
+Again, this is a standard driver model call, working just like it
+would for any other driver stack: the calls can sleep, and can use
+I2C messaging.
+
+
Command function
================
A generic ioctl-like function call back is supported. You will seldom
-need this. You may even set it to NULL.
-
- /* No commands defined */
- int foo_command(struct i2c_client *client, unsigned int cmd, void *arg)
- {
- return 0;
- }
+need this, and its use is deprecated anyway, so newer design should not
+use it. Set it to NULL.
Sending and receiving
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 *values);
These ones were removed in Linux 2.6.10 because they had no users, but could
be added back later if needed:
- extern s32 i2c_smbus_read_i2c_block_data(struct i2c_client * client,
- u8 command, u8 *values);
extern s32 i2c_smbus_read_block_data(struct i2c_client * client,
u8 command, u8 *values);
extern s32 i2c_smbus_write_i2c_block_data(struct i2c_client * client,
projects / firefly-linux-kernel-4.4.55.git / blobdiff