diff options
Diffstat (limited to 'Documentation/i2c/writing-clients')
| -rw-r--r-- | Documentation/i2c/writing-clients | 76 |
1 files changed, 45 insertions, 31 deletions
diff --git a/Documentation/i2c/writing-clients b/Documentation/i2c/writing-clients index 6b9af7d479c..6b344b516bf 100644 --- a/Documentation/i2c/writing-clients +++ b/Documentation/i2c/writing-clients @@ -38,13 +38,13 @@ static struct i2c_driver foo_driver = { .name = "foo", }, - .id_table = foo_ids, + .id_table = foo_idtable, .probe = foo_probe, .remove = foo_remove, /* if device autodetection is needed: */ .class = I2C_CLASS_SOMETHING, .detect = foo_detect, - .address_data = &addr_data, + .address_list = normal_i2c, .shutdown = foo_shutdown, /* optional */ .suspend = foo_suspend, /* optional */ @@ -74,6 +74,11 @@ structure at all. You should use this to keep device-specific data. /* retrieve the value */ void *i2c_get_clientdata(const struct i2c_client *client); +Note that starting with kernel 2.6.34, you don't have to set the `data' field +to NULL in remove() or if probe() failed anymore. The i2c-core does this +automatically on these occasions. Those are also the only times the core will +touch this field. + Accessing the client ==================== @@ -126,19 +131,9 @@ different) configuration information, as do drivers handling chip variants that can't be distinguished by protocol probing, or which need some board specific information to operate correctly. -Accordingly, the I2C stack now has two models for associating I2C devices -with their drivers: the original "legacy" model, and a newer one that's -fully compatible with the Linux 2.6 driver model. These models do not mix, -since the "legacy" model requires drivers to create "i2c_client" device -objects after SMBus style probing, while the Linux driver model expects -drivers to be given such device objects in their probe() routines. - -The legacy model is deprecated now and will soon be removed, so we no -longer document it here. - -Standard Driver Model Binding ("New Style") -------------------------------------------- +Device/Driver Binding +--------------------- System infrastructure, typically board-specific initialization code or boot firmware, reports what I2C devices exist. For example, there may be @@ -201,21 +196,32 @@ a given I2C bus. This is for example the case of hardware monitoring devices on a PC's SMBus. In that case, you may want to let your driver detect supported devices automatically. This is how the legacy model was working, and is now available as an extension to the standard -driver model (so that we can finally get rid of the legacy model.) +driver model. You simply have to define a detect callback which will attempt to identify supported devices (returning 0 for supported ones and -ENODEV for unsupported ones), a list of addresses to probe, and a device type (or class) so that only I2C buses which may have that type of device -connected (and not otherwise enumerated) will be probed. The i2c -core will then call you back as needed and will instantiate a device -for you for every successful detection. +connected (and not otherwise enumerated) will be probed. For example, +a driver for a hardware monitoring chip for which auto-detection is +needed would set its class to I2C_CLASS_HWMON, and only I2C adapters +with a class including I2C_CLASS_HWMON would be probed by this driver. +Note that the absence of matching classes does not prevent the use of +a device of that type on the given I2C adapter. All it prevents is +auto-detection; explicit instantiation of devices is still possible. Note that this mechanism is purely optional and not suitable for all devices. You need some reliable way to identify the supported devices (typically using device-specific, dedicated identification registers), otherwise misdetections are likely to occur and things can get wrong -quickly. +quickly. Keep in mind that the I2C protocol doesn't include any +standard way to detect the presence of a chip at a given address, let +alone a standard way to identify devices. Even worse is the lack of +semantics associated to bus transfers, which means that the same +transfer can be seen as a read operation by a chip and as a write +operation by another chip. For these reasons, explicit device +instantiation should always be preferred to auto-detection where +possible. Device Deletion @@ -239,21 +245,17 @@ static int __init foo_init(void) { return i2c_add_driver(&foo_driver); } +module_init(foo_init); static void __exit foo_cleanup(void) { i2c_del_driver(&foo_driver); } +module_exit(foo_cleanup); -/* 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"); +The module_i2c_driver() macro can be used to reduce above code. -module_init(foo_init); -module_exit(foo_cleanup); +module_i2c_driver(foo_driver); Note that some functions are marked by `__init'. These functions can be removed after kernel booting (or module loading) is completed. @@ -261,6 +263,17 @@ Likewise, functions marked by `__exit' are dropped by the compiler when the code is built into the kernel, as they would never be called. +Driver Information +================== + +/* 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"); + + Power Management ================ @@ -317,8 +330,9 @@ Plain I2C communication 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 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. +to read/write (must be less than the length of the buffer, also should be +less than 64k since msg.len is u16.) Returned is the actual number of bytes +read/written. int i2c_transfer(struct i2c_adapter *adap, struct i2c_msg *msg, int num); @@ -351,8 +365,6 @@ in terms of it. Never use this function directly! 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, @@ -367,6 +379,8 @@ These ones were removed from i2c-core because they had no users, but could be added back later if needed: s32 i2c_smbus_write_quick(struct i2c_client *client, u8 value); + s32 i2c_smbus_process_call(struct i2c_client *client, + u8 command, u16 value); s32 i2c_smbus_block_process_call(struct i2c_client *client, u8 command, u8 length, u8 *values); |