X-Git-Url: http://git.onelab.eu/?a=blobdiff_plain;f=Documentation%2Fi2c%2Fwriting-clients;h=3a057c8e5507c4d1ef8620b93fff8bfe1f208702;hb=43bc926fffd92024b46cafaf7350d669ba9ca884;hp=ad27511e3c7d7c463f5fdb4ce02ea2d96bd4f0ce;hpb=cee37fe97739d85991964371c1f3a745c00dd236;p=linux-2.6.git diff --git a/Documentation/i2c/writing-clients b/Documentation/i2c/writing-clients index ad27511e3..3a057c8e5 100644 --- a/Documentation/i2c/writing-clients +++ b/Documentation/i2c/writing-clients @@ -25,34 +25,20 @@ routines, a client structure specific information like the actual I2C address. static struct i2c_driver foo_driver = { - .owner = THIS_MODULE, - .name = "Foo version 2.3 driver", - .id = I2C_DRIVERID_FOO, /* from i2c-id.h, optional */ - .flags = I2C_DF_NOTIFY, + .driver = { + .name = "foo", + }, .attach_adapter = &foo_attach_adapter, .detach_client = &foo_detach_client, .command = &foo_command /* may be NULL */ } -The name can be chosen freely, and may be upto 40 characters long. Please -use something descriptive here. - -If used, the id should be a unique ID. The range 0xf000 to 0xffff is -reserved for local use, and you can use one of those until you start -distributing the driver, at which time you should contact the i2c authors -to get your own ID(s). Note that most of the time you don't need an ID -at all so you can just omit it. - -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 must match the driver name, including the case. It must not +contain spaces, and may be up to 31 characters long. 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 ================= @@ -65,6 +51,7 @@ be very useful. 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. */ @@ -155,15 +142,15 @@ are defined in i2c.h to help you support them, as well as a generic detection algorithm. You do not have to use this parameter interface; but don't try to use -function i2c_probe() (or i2c_detect()) if you don't. +function i2c_probe() if you don't. NOTE: If you want to write a `sensors' driver, the interface is slightly different! See below. -Probing classes (i2c) ---------------------- +Probing classes +--------------- All parameters are given as lists of unsigned 16-bit integers. Lists are terminated by I2C_CLIENT_END. @@ -171,124 +158,43 @@ The following lists are used internally: normal_i2c: filled in by the module writer. A list of I2C addresses which should normally be examined. - normal_i2c_range: filled in by the module writer. - A list of pairs of I2C addresses, each pair being an inclusive range of - addresses which should normally be examined. probe: insmod parameter. A list of pairs. The first value is a bus number (-1 for any I2C bus), the second is the address. These addresses are also probed, as if they were in the 'normal' list. - probe_range: insmod parameter. - A list of triples. The first value is a bus number (-1 for any I2C bus), - the second and third are addresses. These form an inclusive range of - addresses that are also probed, as if they were in the 'normal' list. ignore: insmod parameter. A list of pairs. The first value is a bus number (-1 for any I2C bus), the second is the I2C address. These addresses are never probed. - This parameter overrules 'normal' and 'probe', but not the 'force' lists. - ignore_range: insmod parameter. - A list of triples. The first value is a bus number (-1 for any I2C bus), - the second and third are addresses. These form an inclusive range of - I2C addresses that are never probed. - This parameter overrules 'normal' and 'probe', but not the 'force' lists. + This parameter overrules the 'normal_i2c' list only. force: insmod parameter. A list of pairs. The first value is a bus number (-1 for any I2C bus), the second is the I2C address. A device is blindly assumed to be on the given address, no probing is done. -Fortunately, as a module writer, you just have to define the `normal' -and/or `normal_range' parameters. The complete declaration could look -like this: +Additionally, kind-specific force lists may optionally be defined if +the driver supports several chip kinds. They are grouped in a +NULL-terminated list of pointers named forces, those first element if the +generic force list mentioned above. Each additional list correspond to an +insmod parameter of the form force_. + +Fortunately, as a module writer, you just have to define the `normal_i2c' +parameter. The complete declaration could look like this: - /* Scan 0x20 to 0x2f, 0x37, and 0x40 to 0x4f */ - static unsigned short normal_i2c[] = { 0x37,I2C_CLIENT_END }; - static unsigned short normal_i2c_range[] = { 0x20, 0x2f, 0x40, 0x4f, - I2C_CLIENT_END }; + /* Scan 0x37, and 0x48 to 0x4f */ + static unsigned short normal_i2c[] = { 0x37, 0x48, 0x49, 0x4a, 0x4b, 0x4c, + 0x4d, 0x4e, 0x4f, I2C_CLIENT_END }; /* Magic definition of all other variables and things */ I2C_CLIENT_INSMOD; + /* Or, if your driver supports, say, 2 kind of devices: */ + I2C_CLIENT_INSMOD_2(foo, bar); -Note that you *have* to call the two defined variables `normal_i2c' and -`normal_i2c_range', without any prefix! - - -Probing classes (sensors) -------------------------- - -If you write a `sensors' driver, you use a slightly different interface. -As well as I2C addresses, we have to cope with ISA addresses. Also, we -use a enum of chip types. Don't forget to include `sensors.h'. +If you use the multi-kind form, an enum will be defined for you: + enum chips { any_chip, foo, bar, ... } +You can then (and certainly should) use it in the driver code. -The following lists are used internally. They are all lists of integers. - - normal_i2c: filled in by the module writer. Terminated by SENSORS_I2C_END. - A list of I2C addresses which should normally be examined. - normal_i2c_range: filled in by the module writer. Terminated by - SENSORS_I2C_END - A list of pairs of I2C addresses, each pair being an inclusive range of - addresses which should normally be examined. - normal_isa: filled in by the module writer. Terminated by SENSORS_ISA_END. - A list of ISA addresses which should normally be examined. - normal_isa_range: filled in by the module writer. Terminated by - SENSORS_ISA_END - A list of triples. The first two elements are ISA addresses, being an - range of addresses which should normally be examined. The third is the - modulo parameter: only addresses which are 0 module this value relative - to the first address of the range are actually considered. - probe: insmod parameter. Initialize this list with SENSORS_I2C_END values. - A list of pairs. The first value is a bus number (SENSORS_ISA_BUS for - the ISA bus, -1 for any I2C bus), the second is the address. These - addresses are also probed, as if they were in the 'normal' list. - probe_range: insmod parameter. Initialize this list with SENSORS_I2C_END - values. - A list of triples. The first value is a bus number (SENSORS_ISA_BUS for - the ISA bus, -1 for any I2C bus), the second and third are addresses. - These form an inclusive range of addresses that are also probed, as - if they were in the 'normal' list. - ignore: insmod parameter. Initialize this list with SENSORS_I2C_END values. - A list of pairs. The first value is a bus number (SENSORS_ISA_BUS for - the ISA bus, -1 for any I2C bus), the second is the I2C address. These - addresses are never probed. This parameter overrules 'normal' and - 'probe', but not the 'force' lists. - ignore_range: insmod parameter. Initialize this list with SENSORS_I2C_END - values. - A list of triples. The first value is a bus number (SENSORS_ISA_BUS for - the ISA bus, -1 for any I2C bus), the second and third are addresses. - These form an inclusive range of I2C addresses that are never probed. - This parameter overrules 'normal' and 'probe', but not the 'force' lists. - -Also used is a list of pointers to sensors_force_data structures: - force_data: insmod parameters. A list, ending with an element of which - the force field is NULL. - Each element contains the type of chip and a list of pairs. - The first value is a bus number (SENSORS_ISA_BUS for the ISA bus, - -1 for any I2C bus), the second is the address. - These are automatically translated to insmod variables of the form - force_foo. - -So we have a generic insmod variabled `force', and chip-specific variables -`force_CHIPNAME'. - -Fortunately, as a module writer, you just have to define the `normal' -and/or `normal_range' parameters, and define what chip names are used. -The complete declaration could look like this: - /* Scan i2c addresses 0x20 to 0x2f, 0x37, and 0x40 to 0x4f - static unsigned short normal_i2c[] = {0x37,SENSORS_I2C_END}; - static unsigned short normal_i2c_range[] = {0x20,0x2f,0x40,0x4f, - SENSORS_I2C_END}; - /* Scan ISA address 0x290 */ - static unsigned int normal_isa[] = {0x0290,SENSORS_ISA_END}; - static unsigned int normal_isa_range[] = {SENSORS_ISA_END}; - - /* Define chips foo and bar, as well as all module parameters and things */ - SENSORS_INSMOD_2(foo,bar); - -If you have one chip, you use macro SENSORS_INSMOD_1(chip), if you have 2 -you use macro SENSORS_INSMOD_2(chip1,chip2), etc. If you do not want to -bother with chip types, you can use SENSORS_INSMOD_0. - -A enum is automatically defined as follows: - enum chips { any_chip, chip1, chip2, ... } +Note that you *have* to call the defined variable `normal_i2c', +without any prefix! Attaching to an adapter @@ -309,17 +215,10 @@ detected at a specific address, another callback is called. return i2c_probe(adapter,&addr_data,&foo_detect_client); } -For `sensors' drivers, use the i2c_detect function instead: - - int foo_attach_adapter(struct i2c_adapter *adapter) - { - return i2c_detect(adapter,&addr_data,&foo_detect_client); - } - Remember, structure `addr_data' is defined by the macros explained above, so you do not have to define it yourself. -The i2c_probe or i2c_detect function will call the foo_detect_client +The i2c_probe function will call the foo_detect_client function only for those i2c addresses that actually have a device on them (unless a `force' parameter was used). In addition, addresses that are already in use (by some other registered client) are skipped. @@ -328,19 +227,18 @@ are already in use (by some other registered client) are skipped. The detect client function -------------------------- -The detect client function is called by i2c_probe or i2c_detect. -The `kind' parameter contains 0 if this call is due to a `force' -parameter, and -1 otherwise (for i2c_detect, it contains 0 if -this call is due to the generic `force' parameter, and the chip type -number if it is due to a specific `force' parameter). +The detect client function is called by i2c_probe. The `kind' parameter +contains -1 for a probed detection, 0 for a forced detection, or a positive +number for a forced detection with a chip type forced. Below, some things are only needed if this is a `sensors' driver. Those parts are between /* SENSORS ONLY START */ and /* SENSORS ONLY END */ markers. -This function should only return an error (any value != 0) if there is -some reason why no more detection should be done anymore. If the -detection just fails for this address, return 0. +Returning an error different from -ENODEV in a detect function will cause +the detection to stop: other addresses and adapters won't be scanned. +This should only be done on fatal or internal errors, such as a memory +shortage or i2c_attach_client failing. For now, you can ignore the `flags' parameter. It is there for future use. @@ -365,13 +263,13 @@ For now, you can ignore the `flags' parameter. It is there for future use. const char *type_name = ""; int is_isa = i2c_is_isa_adapter(adapter); - if (is_isa) { + /* Do this only if the chip can additionally be found on the ISA bus + (hybrid chip). */ - /* If this client can't be on the ISA bus at all, we can stop now - (call `goto ERROR0'). But for kicks, we will assume it is all - right. */ + 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; @@ -407,22 +305,15 @@ For now, you can ignore the `flags' parameter. It is there for future use. 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; @@ -517,7 +408,7 @@ For now, you can ignore the `flags' parameter. It is there for future use. release_region(address,FOO_EXTENT); /* SENSORS ONLY END */ ERROR1: - kfree(new_client); + kfree(data); ERROR0: return err; } @@ -540,17 +431,15 @@ much simpler than the attachment code, fortunately! /* SENSORS ONLY END */ /* Try to detach the client from i2c space */ - if ((err = i2c_detach_client(client))) { - printk("foo.o: Client deregistration failed, client not detached.\n"); + if ((err = i2c_detach_client(client))) return err; - } - /* SENSORS ONLY START */ + /* HYBRID SENSORS CHIP ONLY START */ if i2c_is_isa_client(client) release_region(client->addr,LM78_EXTENT); - /* SENSORS ONLY END */ + /* HYBRID SENSORS CHIP ONLY END */ - kfree(client); /* Frees client data too, if allocated at the same time */ + kfree(i2c_get_clientdata(client)); return 0; } @@ -603,17 +492,13 @@ Note that some functions are marked by `__init', and some data structures by `__init_data'. Hose functions and structures can be removed after kernel booting (or module loading) is completed. + 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 @@ -675,12 +560,12 @@ SMBus communication 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,