aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/i2c/writing-clients
diff options
context:
space:
mode:
authorJean Delvare <khali@linux-fr.org>2008-10-22 14:21:31 -0400
committerJean Delvare <khali@linux-fr.org>2008-10-22 14:21:31 -0400
commite313353dd4fcb1ab568ab20339380063307ebec9 (patch)
tree8ad0f6021b5a234290bceffc43c43086d7a22afa /Documentation/i2c/writing-clients
parent7d1d8999b4bec0ba09f935e648a688bb25596d06 (diff)
i2c: Delete legacy model documentation
The legacy i2c binding model is deprecated and will be removed soon, so we no longer need to document it. Signed-off-by: Jean Delvare <khali@linux-fr.org>
Diffstat (limited to 'Documentation/i2c/writing-clients')
-rw-r--r--Documentation/i2c/writing-clients255
1 files changed, 14 insertions, 241 deletions
diff --git a/Documentation/i2c/writing-clients b/Documentation/i2c/writing-clients
index 3b01350c149c..c3e188577687 100644
--- a/Documentation/i2c/writing-clients
+++ b/Documentation/i2c/writing-clients
@@ -25,8 +25,6 @@ routines, and should be zero-initialized except for fields with data you
25provide. A client structure holds device-specific information like the 25provide. A client structure holds device-specific information like the
26driver model device node, and its I2C address. 26driver model device node, and its I2C address.
27 27
28/* iff driver uses driver model ("new style") binding model: */
29
30static struct i2c_device_id foo_idtable[] = { 28static struct i2c_device_id foo_idtable[] = {
31 { "foo", my_id_for_foo }, 29 { "foo", my_id_for_foo },
32 { "bar", my_id_for_bar }, 30 { "bar", my_id_for_bar },
@@ -40,7 +38,6 @@ static struct i2c_driver foo_driver = {
40 .name = "foo", 38 .name = "foo",
41 }, 39 },
42 40
43 /* iff driver uses driver model ("new style") binding model: */
44 .id_table = foo_ids, 41 .id_table = foo_ids,
45 .probe = foo_probe, 42 .probe = foo_probe,
46 .remove = foo_remove, 43 .remove = foo_remove,
@@ -49,11 +46,6 @@ static struct i2c_driver foo_driver = {
49 .detect = foo_detect, 46 .detect = foo_detect,
50 .address_data = &addr_data, 47 .address_data = &addr_data,
51 48
52 /* else, driver uses "legacy" binding model: */
53 .attach_adapter = foo_attach_adapter,
54 .detach_client = foo_detach_client,
55
56 /* these may be used regardless of the driver binding model */
57 .shutdown = foo_shutdown, /* optional */ 49 .shutdown = foo_shutdown, /* optional */
58 .suspend = foo_suspend, /* optional */ 50 .suspend = foo_suspend, /* optional */
59 .resume = foo_resume, /* optional */ 51 .resume = foo_resume, /* optional */
@@ -88,7 +80,7 @@ be very useful.
88An example structure is below. 80An example structure is below.
89 81
90 struct foo_data { 82 struct foo_data {
91 struct i2c_client client; 83 struct i2c_client *client;
92 enum chips type; /* To keep the chips type for `sensors' drivers. */ 84 enum chips type; /* To keep the chips type for `sensors' drivers. */
93 85
94 /* Because the i2c bus is slow, it is often useful to cache the read 86 /* Because the i2c bus is slow, it is often useful to cache the read
@@ -144,10 +136,10 @@ Probing and attaching
144===================== 136=====================
145 137
146The Linux I2C stack was originally written to support access to hardware 138The Linux I2C stack was originally written to support access to hardware
147monitoring chips on PC motherboards, and thus it embeds some assumptions 139monitoring chips on PC motherboards, and thus used to embed some assumptions
148that are more appropriate to SMBus (and PCs) than to I2C. One of these 140that were more appropriate to SMBus (and PCs) than to I2C. One of these
149assumptions is that most adapters and devices drivers support the SMBUS_QUICK 141assumptions was that most adapters and devices drivers support the SMBUS_QUICK
150protocol to probe device presence. Another is that devices and their drivers 142protocol to probe device presence. Another was that devices and their drivers
151can be sufficiently configured using only such probe primitives. 143can be sufficiently configured using only such probe primitives.
152 144
153As Linux and its I2C stack became more widely used in embedded systems 145As Linux and its I2C stack became more widely used in embedded systems
@@ -164,6 +156,9 @@ since the "legacy" model requires drivers to create "i2c_client" device
164objects after SMBus style probing, while the Linux driver model expects 156objects after SMBus style probing, while the Linux driver model expects
165drivers to be given such device objects in their probe() routines. 157drivers to be given such device objects in their probe() routines.
166 158
159The legacy model is deprecated now and will soon be removed, so we no
160longer document it here.
161
167 162
168Standard Driver Model Binding ("New Style") 163Standard Driver Model Binding ("New Style")
169------------------------------------------- 164-------------------------------------------
@@ -193,8 +188,8 @@ matches the device's name. It is passed the entry that was matched so
193the driver knows which one in the table matched. 188the driver knows which one in the table matched.
194 189
195 190
196Device Creation (Standard driver model) 191Device Creation
197--------------------------------------- 192---------------
198 193
199If you know for a fact that an I2C device is connected to a given I2C bus, 194If you know for a fact that an I2C device is connected to a given I2C bus,
200you can instantiate that device by simply filling an i2c_board_info 195you can instantiate that device by simply filling an i2c_board_info
@@ -221,8 +216,8 @@ in the I2C bus driver. You may want to save the returned i2c_client
221reference for later use. 216reference for later use.
222 217
223 218
224Device Detection (Standard driver model) 219Device Detection
225---------------------------------------- 220----------------
226 221
227Sometimes you do not know in advance which I2C devices are connected to 222Sometimes you do not know in advance which I2C devices are connected to
228a given I2C bus. This is for example the case of hardware monitoring 223a given I2C bus. This is for example the case of hardware monitoring
@@ -246,8 +241,8 @@ otherwise misdetections are likely to occur and things can get wrong
246quickly. 241quickly.
247 242
248 243
249Device Deletion (Standard driver model) 244Device Deletion
250--------------------------------------- 245---------------
251 246
252Each I2C device which has been created using i2c_new_device() or 247Each I2C device which has been created using i2c_new_device() or
253i2c_new_probed_device() can be unregistered by calling 248i2c_new_probed_device() can be unregistered by calling
@@ -256,228 +251,6 @@ called automatically before the underlying I2C bus itself is removed, as a
256device can't survive its parent in the device driver model. 251device can't survive its parent in the device driver model.
257 252
258 253
259Legacy Driver Binding Model
260---------------------------
261
262Most i2c devices can be present on several i2c addresses; for some this
263is determined in hardware (by soldering some chip pins to Vcc or Ground),
264for others this can be changed in software (by writing to specific client
265registers). Some devices are usually on a specific address, but not always;
266and some are even more tricky. So you will probably need to scan several
267i2c addresses for your clients, and do some sort of detection to see
268whether it is actually a device supported by your driver.
269
270To give the user a maximum of possibilities, some default module parameters
271are defined to help determine what addresses are scanned. Several macros
272are defined in i2c.h to help you support them, as well as a generic
273detection algorithm.
274
275You do not have to use this parameter interface; but don't try to use
276function i2c_probe() if you don't.
277
278
279Probing classes (Legacy model)
280------------------------------
281
282All parameters are given as lists of unsigned 16-bit integers. Lists are
283terminated by I2C_CLIENT_END.
284The following lists are used internally:
285
286 normal_i2c: filled in by the module writer.
287 A list of I2C addresses which should normally be examined.
288 probe: insmod parameter.
289 A list of pairs. The first value is a bus number (-1 for any I2C bus),
290 the second is the address. These addresses are also probed, as if they
291 were in the 'normal' list.
292 ignore: insmod parameter.
293 A list of pairs. The first value is a bus number (-1 for any I2C bus),
294 the second is the I2C address. These addresses are never probed.
295 This parameter overrules the 'normal_i2c' list only.
296 force: insmod parameter.
297 A list of pairs. The first value is a bus number (-1 for any I2C bus),
298 the second is the I2C address. A device is blindly assumed to be on
299 the given address, no probing is done.
300
301Additionally, kind-specific force lists may optionally be defined if
302the driver supports several chip kinds. They are grouped in a
303NULL-terminated list of pointers named forces, those first element if the
304generic force list mentioned above. Each additional list correspond to an
305insmod parameter of the form force_<kind>.
306
307Fortunately, as a module writer, you just have to define the `normal_i2c'
308parameter. The complete declaration could look like this:
309
310 /* Scan 0x4c to 0x4f */
311 static const unsigned short normal_i2c[] = { 0x4c, 0x4d, 0x4e, 0x4f,
312 I2C_CLIENT_END };
313
314 /* Magic definition of all other variables and things */
315 I2C_CLIENT_INSMOD;
316 /* Or, if your driver supports, say, 2 kind of devices: */
317 I2C_CLIENT_INSMOD_2(foo, bar);
318
319If you use the multi-kind form, an enum will be defined for you:
320 enum chips { any_chip, foo, bar, ... }
321You can then (and certainly should) use it in the driver code.
322
323Note that you *have* to call the defined variable `normal_i2c',
324without any prefix!
325
326
327Attaching to an adapter (Legacy model)
328--------------------------------------
329
330Whenever a new adapter is inserted, or for all adapters if the driver is
331being registered, the callback attach_adapter() is called. Now is the
332time to determine what devices are present on the adapter, and to register
333a client for each of them.
334
335The attach_adapter callback is really easy: we just call the generic
336detection function. This function will scan the bus for us, using the
337information as defined in the lists explained above. If a device is
338detected at a specific address, another callback is called.
339
340 int foo_attach_adapter(struct i2c_adapter *adapter)
341 {
342 return i2c_probe(adapter,&addr_data,&foo_detect_client);
343 }
344
345Remember, structure `addr_data' is defined by the macros explained above,
346so you do not have to define it yourself.
347
348The i2c_probe function will call the foo_detect_client
349function only for those i2c addresses that actually have a device on
350them (unless a `force' parameter was used). In addition, addresses that
351are already in use (by some other registered client) are skipped.
352
353
354The detect client function (Legacy model)
355-----------------------------------------
356
357The detect client function is called by i2c_probe. The `kind' parameter
358contains -1 for a probed detection, 0 for a forced detection, or a positive
359number for a forced detection with a chip type forced.
360
361Returning an error different from -ENODEV in a detect function will cause
362the detection to stop: other addresses and adapters won't be scanned.
363This should only be done on fatal or internal errors, such as a memory
364shortage or i2c_attach_client failing.
365
366For now, you can ignore the `flags' parameter. It is there for future use.
367
368 int foo_detect_client(struct i2c_adapter *adapter, int address,
369 int kind)
370 {
371 int err = 0;
372 int i;
373 struct i2c_client *client;
374 struct foo_data *data;
375 const char *name = "";
376
377 /* Let's see whether this adapter can support what we need.
378 Please substitute the things you need here! */
379 if (!i2c_check_functionality(adapter,I2C_FUNC_SMBUS_WORD_DATA |
380 I2C_FUNC_SMBUS_WRITE_BYTE))
381 goto ERROR0;
382
383 /* OK. For now, we presume we have a valid client. We now create the
384 client structure, even though we cannot fill it completely yet.
385 But it allows us to access several i2c functions safely */
386
387 if (!(data = kzalloc(sizeof(struct foo_data), GFP_KERNEL))) {
388 err = -ENOMEM;
389 goto ERROR0;
390 }
391
392 client = &data->client;
393 i2c_set_clientdata(client, data);
394
395 client->addr = address;
396 client->adapter = adapter;
397 client->driver = &foo_driver;
398
399 /* Now, we do the remaining detection. If no `force' parameter is used. */
400
401 /* First, the generic detection (if any), that is skipped if any force
402 parameter was used. */
403 if (kind < 0) {
404 /* The below is of course bogus */
405 if (foo_read(client, FOO_REG_GENERIC) != FOO_GENERIC_VALUE)
406 goto ERROR1;
407 }
408
409 /* Next, specific detection. This is especially important for `sensors'
410 devices. */
411
412 /* Determine the chip type. Not needed if a `force_CHIPTYPE' parameter
413 was used. */
414 if (kind <= 0) {
415 i = foo_read(client, FOO_REG_CHIPTYPE);
416 if (i == FOO_TYPE_1)
417 kind = chip1; /* As defined in the enum */
418 else if (i == FOO_TYPE_2)
419 kind = chip2;
420 else {
421 printk("foo: Ignoring 'force' parameter for unknown chip at "
422 "adapter %d, address 0x%02x\n",i2c_adapter_id(adapter),address);
423 goto ERROR1;
424 }
425 }
426
427 /* Now set the type and chip names */
428 if (kind == chip1) {
429 name = "chip1";
430 } else if (kind == chip2) {
431 name = "chip2";
432 }
433
434 /* Fill in the remaining client fields. */
435 strlcpy(client->name, name, I2C_NAME_SIZE);
436 data->type = kind;
437 mutex_init(&data->update_lock); /* Only if you use this field */
438
439 /* Any other initializations in data must be done here too. */
440
441 /* This function can write default values to the client registers, if
442 needed. */
443 foo_init_client(client);
444
445 /* Tell the i2c layer a new client has arrived */
446 if ((err = i2c_attach_client(client)))
447 goto ERROR1;
448
449 return 0;
450
451 /* OK, this is not exactly good programming practice, usually. But it is
452 very code-efficient in this case. */
453
454 ERROR1:
455 kfree(data);
456 ERROR0:
457 return err;
458 }
459
460
461Removing the client (Legacy model)
462==================================
463
464The detach_client call back function is called when a client should be
465removed. It may actually fail, but only when panicking. This code is
466much simpler than the attachment code, fortunately!
467
468 int foo_detach_client(struct i2c_client *client)
469 {
470 int err;
471
472 /* Try to detach the client from i2c space */
473 if ((err = i2c_detach_client(client)))
474 return err;
475
476 kfree(i2c_get_clientdata(client));
477 return 0;
478 }
479
480
481Initializing the module or kernel 254Initializing the module or kernel
482================================= 255=================================
483 256