Documentation/i2c/writing-clients

   1 This is a small guide for those who want to write kernel drivers for I2C
   2 or SMBus devices.
   3
   4 To set up a driver, you need to do several things. Some are optional, and
   5 some things can be done slightly or completely different. Use this as a
   6 guide, not as a rule book!
   7
   8
   9 General remarks
  10 ===============
  11
  12 Try to keep the kernel namespace as clean as possible. The best way to
  13 do this is to use a unique prefix for all global symbols. This is
  14 especially important for exported symbols, but it is a good idea to do
  15 it for non-exported symbols too. We will use the prefix `foo_' in this
  16 tutorial, and `FOO_' for preprocessor variables.
  17
  18
  19 The driver structure
  20 ====================
  21
  22 Usually, you will implement a single driver structure, and instantiate
  23 all clients from it. Remember, a driver structure contains general access
  24 routines, a client structure specific information like the actual I2C
  25 address.
  26
  27   static struct i2c_driver foo_driver = {
  28     .owner          = THIS_MODULE,
  29     .name           = "Foo version 2.3 driver",
  30     .id             = I2C_DRIVERID_FOO, /* usually from i2c-id.h */
  31     .flags          = I2C_DF_NOTIFY,
  32     .attach_adapter = &foo_attach_adapter,
  33     .detach_client  = &foo_detach_client,
  34     .command        = &foo_command /* may be NULL */
  35   }
  36
  37 The name can be chosen freely, and may be upto 40 characters long. Please
  38 use something descriptive here.
  39
  40 The id should be a unique ID. The range 0xf000 to 0xffff is reserved for
  41 local use, and you can use one of those until you start distributing the
  42 driver. Before you do that, contact the i2c authors to get your own ID(s).
  43
  44 Don't worry about the flags field; just put I2C_DF_NOTIFY into it. This
  45 means that your driver will be notified when new adapters are found.
  46 This is almost always what you want.
  47
  48 All other fields are for call-back functions which will be explained
  49 below.
  50
  51 There use to be two additional fields in this structure, inc_use et dec_use,
  52 for module usage count, but these fields were obsoleted and removed.
  53
  54
  55 Extra client data
  56 =================
  57
  58 The client structure has a special `data' field that can point to any
  59 structure at all. You can use this to keep client-specific data. You
  60 do not always need this, but especially for `sensors' drivers, it can
  61 be very useful.
  62
  63 An example structure is below.
  64
  65   struct foo_data {
  66     struct semaphore lock; /* For ISA access in `sensors' drivers. */
  67     int sysctl_id;         /* To keep the /proc directory entry for
  68                               `sensors' drivers. */
  69     enum chips type;       /* To keep the chips type for `sensors' drivers. */
  70
  71     /* Because the i2c bus is slow, it is often useful to cache the read
  72        information of a chip for some time (for example, 1 or 2 seconds).
  73        It depends of course on the device whether this is really worthwhile
  74        or even sensible. */
  75     struct semaphore update_lock; /* When we are reading lots of information,
  76                                      another process should not update the
  77                                      below information */
  78     char valid;                   /* != 0 if the following fields are valid. */
  79     unsigned long last_updated;   /* In jiffies */
  80     /* Add the read information here too */
  81   };
  82
  83
  84 Accessing the client
  85 ====================
  86
  87 Let's say we have a valid client structure. At some time, we will need
  88 to gather information from the client, or write new information to the
  89 client. How we will export this information to user-space is less
  90 important at this moment (perhaps we do not need to do this at all for
  91 some obscure clients). But we need generic reading and writing routines.
  92
  93 I have found it useful to define foo_read and foo_write function for this.
  94 For some cases, it will be easier to call the i2c functions directly,
  95 but many chips have some kind of register-value idea that can easily
  96 be encapsulated. Also, some chips have both ISA and I2C interfaces, and
  97 it useful to abstract from this (only for `sensors' drivers).
  98
  99 The below functions are simple examples, and should not be copied
 100 literally.
 101
 102   int foo_read_value(struct i2c_client *client, u8 reg)
 103   {
 104     if (reg < 0x10) /* byte-sized register */
 105       return i2c_smbus_read_byte_data(client,reg);
 106     else /* word-sized register */
 107       return i2c_smbus_read_word_data(client,reg);
 108   }
 109
 110   int foo_write_value(struct i2c_client *client, u8 reg, u16 value)
 111   {
 112     if (reg == 0x10) /* Impossible to write - driver error! */ {
 113       return -1;
 114     else if (reg < 0x10) /* byte-sized register */
 115       return i2c_smbus_write_byte_data(client,reg,value);
 116     else /* word-sized register */
 117       return i2c_smbus_write_word_data(client,reg,value);
 118   }
 119
 120 For sensors code, you may have to cope with ISA registers too. Something
 121 like the below often works. Note the locking!
 122
 123   int foo_read_value(struct i2c_client *client, u8 reg)
 124   {
 125     int res;
 126     if (i2c_is_isa_client(client)) {
 127       down(&(((struct foo_data *) (client->data)) -> lock));
 128       outb_p(reg,client->addr + FOO_ADDR_REG_OFFSET);
 129       res = inb_p(client->addr + FOO_DATA_REG_OFFSET);
 130       up(&(((struct foo_data *) (client->data)) -> lock));
 131       return res;
 132     } else
 133       return i2c_smbus_read_byte_data(client,reg);
 134   }
 135
 136 Writing is done the same way.
 137
 138
 139 Probing and attaching
 140 =====================
 141
 142 Most i2c devices can be present on several i2c addresses; for some this
 143 is determined in hardware (by soldering some chip pins to Vcc or Ground),
 144 for others this can be changed in software (by writing to specific client
 145 registers). Some devices are usually on a specific address, but not always;
 146 and some are even more tricky. So you will probably need to scan several
 147 i2c addresses for your clients, and do some sort of detection to see
 148 whether it is actually a device supported by your driver.
 149
 150 To give the user a maximum of possibilities, some default module parameters
 151 are defined to help determine what addresses are scanned. Several macros
 152 are defined in i2c.h to help you support them, as well as a generic
 153 detection algorithm.
 154
 155 You do not have to use this parameter interface; but don't try to use
 156 function i2c_probe() (or i2c_detect()) if you don't.
 157
 158 NOTE: If you want to write a `sensors' driver, the interface is slightly
 159       different! See below.
 160
 161
 162
 163 Probing classes (i2c)
 164 ---------------------
 165
 166 All parameters are given as lists of unsigned 16-bit integers. Lists are
 167 terminated by I2C_CLIENT_END.
 168 The following lists are used internally:
 169
 170   normal_i2c: filled in by the module writer.
 171      A list of I2C addresses which should normally be examined.
 172    normal_i2c_range: filled in by the module writer.
 173      A list of pairs of I2C addresses, each pair being an inclusive range of
 174      addresses which should normally be examined.
 175    probe: insmod parameter.
 176      A list of pairs. The first value is a bus number (-1 for any I2C bus),
 177      the second is the address. These addresses are also probed, as if they
 178      were in the 'normal' list.
 179    probe_range: insmod parameter.
 180      A list of triples. The first value is a bus number (-1 for any I2C bus),
 181      the second and third are addresses.  These form an inclusive range of
 182      addresses that are also probed, as if they were in the 'normal' list.
 183    ignore: insmod parameter.
 184      A list of pairs. The first value is a bus number (-1 for any I2C bus),
 185      the second is the I2C address. These addresses are never probed.
 186      This parameter overrules 'normal' and 'probe', but not the 'force' lists.
 187    ignore_range: insmod parameter.
 188      A list of triples. The first value is a bus number (-1 for any I2C bus),
 189      the second and third are addresses. These form an inclusive range of
 190      I2C addresses that are never probed.
 191      This parameter overrules 'normal' and 'probe', but not the 'force' lists.
 192    force: insmod parameter.
 193      A list of pairs. The first value is a bus number (-1 for any I2C bus),
 194      the second is the I2C address. A device is blindly assumed to be on
 195      the given address, no probing is done.
 196
 197 Fortunately, as a module writer, you just have to define the `normal'
 198 and/or `normal_range' parameters. The complete declaration could look
 199 like this:
 200
 201   /* Scan 0x20 to 0x2f, 0x37, and 0x40 to 0x4f */
 202   static unsigned short normal_i2c[] = { 0x37,I2C_CLIENT_END };
 203   static unsigned short normal_i2c_range[] = { 0x20, 0x2f, 0x40, 0x4f,
 204                                                I2C_CLIENT_END };
 205
 206   /* Magic definition of all other variables and things */
 207   I2C_CLIENT_INSMOD;
 208
 209 Note that you *have* to call the two defined variables `normal_i2c' and
 210 `normal_i2c_range', without any prefix!
 211
 212
 213 Probing classes (sensors)
 214 -------------------------
 215
 216 If you write a `sensors' driver, you use a slightly different interface.
 217 As well as I2C addresses, we have to cope with ISA addresses. Also, we
 218 use a enum of chip types. Don't forget to include `sensors.h'.
 219
 220 The following lists are used internally. They are all lists of integers.
 221
 222    normal_i2c: filled in by the module writer. Terminated by SENSORS_I2C_END.
 223      A list of I2C addresses which should normally be examined.
 224    normal_i2c_range: filled in by the module writer. Terminated by
 225      SENSORS_I2C_END
 226      A list of pairs of I2C addresses, each pair being an inclusive range of
 227      addresses which should normally be examined.
 228    normal_isa: filled in by the module writer. Terminated by SENSORS_ISA_END.
 229      A list of ISA addresses which should normally be examined.
 230    normal_isa_range: filled in by the module writer. Terminated by
 231      SENSORS_ISA_END
 232      A list of triples. The first two elements are ISA addresses, being an
 233      range of addresses which should normally be examined. The third is the
 234      modulo parameter: only addresses which are 0 module this value relative
 235      to the first address of the range are actually considered.
 236    probe: insmod parameter. Initialize this list with SENSORS_I2C_END values.
 237      A list of pairs. The first value is a bus number (SENSORS_ISA_BUS for
 238      the ISA bus, -1 for any I2C bus), the second is the address. These
 239      addresses are also probed, as if they were in the 'normal' list.
 240    probe_range: insmod parameter. Initialize this list with SENSORS_I2C_END
 241      values.
 242      A list of triples. The first value is a bus number (SENSORS_ISA_BUS for
 243      the ISA bus, -1 for any I2C bus), the second and third are addresses.
 244      These form an inclusive range of addresses that are also probed, as
 245      if they were in the 'normal' list.
 246    ignore: insmod parameter. Initialize this list with SENSORS_I2C_END values.
 247      A list of pairs. The first value is a bus number (SENSORS_ISA_BUS for
 248      the ISA bus, -1 for any I2C bus), the second is the I2C address. These
 249      addresses are never probed. This parameter overrules 'normal' and
 250      'probe', but not the 'force' lists.
 251    ignore_range: insmod parameter. Initialize this list with SENSORS_I2C_END
 252       values.
 253      A list of triples. The first value is a bus number (SENSORS_ISA_BUS for
 254      the ISA bus, -1 for any I2C bus), the second and third are addresses.
 255      These form an inclusive range of I2C addresses that are never probed.
 256      This parameter overrules 'normal' and 'probe', but not the 'force' lists.
 257
 258 Also used is a list of pointers to sensors_force_data structures:
 259    force_data: insmod parameters. A list, ending with an element of which
 260      the force field is NULL.
 261      Each element contains the type of chip and a list of pairs.
 262      The first value is a bus number (SENSORS_ISA_BUS for the ISA bus,
 263      -1 for any I2C bus), the second is the address.
 264      These are automatically translated to insmod variables of the form
 265      force_foo.
 266
 267 So we have a generic insmod variabled `force', and chip-specific variables
 268 `force_CHIPNAME'.
 269
 270 Fortunately, as a module writer, you just have to define the `normal'
 271 and/or `normal_range' parameters, and define what chip names are used.
 272 The complete declaration could look like this:
 273   /* Scan i2c addresses 0x20 to 0x2f, 0x37, and 0x40 to 0x4f
 274   static unsigned short normal_i2c[] = {0x37,SENSORS_I2C_END};
 275   static unsigned short normal_i2c_range[] = {0x20,0x2f,0x40,0x4f,
 276                                               SENSORS_I2C_END};
 277   /* Scan ISA address 0x290 */
 278   static unsigned int normal_isa[] = {0x0290,SENSORS_ISA_END};
 279   static unsigned int normal_isa_range[] = {SENSORS_ISA_END};
 280
 281   /* Define chips foo and bar, as well as all module parameters and things */
 282   SENSORS_INSMOD_2(foo,bar);
 283
 284 If you have one chip, you use macro SENSORS_INSMOD_1(chip), if you have 2
 285 you use macro SENSORS_INSMOD_2(chip1,chip2), etc. If you do not want to
 286 bother with chip types, you can use SENSORS_INSMOD_0.
 287
 288 A enum is automatically defined as follows:
 289   enum chips { any_chip, chip1, chip2, ... }
 290
 291
 292 Attaching to an adapter
 293 -----------------------
 294
 295 Whenever a new adapter is inserted, or for all adapters if the driver is
 296 being registered, the callback attach_adapter() is called. Now is the
 297 time to determine what devices are present on the adapter, and to register
 298 a client for each of them.
 299
 300 The attach_adapter callback is really easy: we just call the generic
 301 detection function. This function will scan the bus for us, using the
 302 information as defined in the lists explained above. If a device is
 303 detected at a specific address, another callback is called.
 304
 305   int foo_attach_adapter(struct i2c_adapter *adapter)
 306   {
 307     return i2c_probe(adapter,&addr_data,&foo_detect_client);
 308   }
 309
 310 For `sensors' drivers, use the i2c_detect function instead:
 311
 312   int foo_attach_adapter(struct i2c_adapter *adapter)
 313   {
 314     return i2c_detect(adapter,&addr_data,&foo_detect_client);
 315   }
 316
 317 Remember, structure `addr_data' is defined by the macros explained above,
 318 so you do not have to define it yourself.
 319
 320 The i2c_probe or i2c_detect function will call the foo_detect_client
 321 function only for those i2c addresses that actually have a device on
 322 them (unless a `force' parameter was used). In addition, addresses that
 323 are already in use (by some other registered client) are skipped.
 324
 325
 326 The detect client function
 327 --------------------------
 328
 329 The detect client function is called by i2c_probe or i2c_detect.
 330 The `kind' parameter contains 0 if this call is due to a `force'
 331 parameter, and -1 otherwise (for i2c_detect, it contains 0 if
 332 this call is due to the generic `force' parameter, and the chip type
 333 number if it is due to a specific `force' parameter).
 334
 335 Below, some things are only needed if this is a `sensors' driver. Those
 336 parts are between /* SENSORS ONLY START */ and /* SENSORS ONLY END */
 337 markers.
 338
 339 This function should only return an error (any value != 0) if there is
 340 some reason why no more detection should be done anymore. If the
 341 detection just fails for this address, return 0.
 342
 343 For now, you can ignore the `flags' parameter. It is there for future use.
 344
 345   /* Unique ID allocation */
 346   static int foo_id = 0;
 347
 348   int foo_detect_client(struct i2c_adapter *adapter, int address,
 349                         unsigned short flags, int kind)
 350   {
 351     int err = 0;
 352     int i;
 353     struct i2c_client *new_client;
 354     struct foo_data *data;
 355     const char *client_name = ""; /* For non-`sensors' drivers, put the real
 356                                      name here! */
 357
 358     /* Let's see whether this adapter can support what we need.
 359        Please substitute the things you need here!
 360        For `sensors' drivers, add `! is_isa &&' to the if statement */
 361     if (!i2c_check_functionality(adapter,I2C_FUNC_SMBUS_WORD_DATA |
 362                                         I2C_FUNC_SMBUS_WRITE_BYTE))
 363        goto ERROR0;
 364
 365     /* SENSORS ONLY START */
 366     const char *type_name = "";
 367     int is_isa = i2c_is_isa_adapter(adapter);
 368
 369     if (is_isa) {
 370
 371       /* If this client can't be on the ISA bus at all, we can stop now
 372          (call `goto ERROR0'). But for kicks, we will assume it is all
 373          right. */
 374
 375       /* Discard immediately if this ISA range is already used */
 376       if (check_region(address,FOO_EXTENT))
 377         goto ERROR0;
 378
 379       /* Probe whether there is anything on this address.
 380          Some example code is below, but you will have to adapt this
 381          for your own driver */
 382
 383       if (kind < 0) /* Only if no force parameter was used */ {
 384         /* We may need long timeouts at least for some chips. */
 385         #define REALLY_SLOW_IO
 386         i = inb_p(address + 1);
 387         if (inb_p(address + 2) != i)
 388           goto ERROR0;
 389         if (inb_p(address + 3) != i)
 390           goto ERROR0;
 391         if (inb_p(address + 7) != i)
 392           goto ERROR0;
 393         #undef REALLY_SLOW_IO
 394
 395         /* Let's just hope nothing breaks here */
 396         i = inb_p(address + 5) & 0x7f;
 397         outb_p(~i & 0x7f,address+5);
 398         if ((inb_p(address + 5) & 0x7f) != (~i & 0x7f)) {
 399           outb_p(i,address+5);
 400           return 0;
 401         }
 402       }
 403     }
 404
 405     /* SENSORS ONLY END */
 406
 407     /* OK. For now, we presume we have a valid client. We now create the
 408        client structure, even though we cannot fill it completely yet.
 409        But it allows us to access several i2c functions safely */
 410
 411     /* Note that we reserve some space for foo_data too. If you don't
 412        need it, remove it. We do it here to help to lessen memory
 413        fragmentation. */
 414     if (! (new_client = kmalloc(sizeof(struct i2c_client) +
 415                                 sizeof(struct foo_data),
 416                                 GFP_KERNEL))) {
 417       err = -ENOMEM;
 418       goto ERROR0;
 419     }
 420
 421     /* This is tricky, but it will set the data to the right value. */
 422     client->data = new_client + 1;
 423     data = (struct foo_data *) (client->data);
 424
 425     new_client->addr = address;
 426     new_client->data = data;
 427     new_client->adapter = adapter;
 428     new_client->driver = &foo_driver;
 429     new_client->flags = 0;
 430
 431     /* Now, we do the remaining detection. If no `force' parameter is used. */
 432
 433     /* First, the generic detection (if any), that is skipped if any force
 434        parameter was used. */
 435     if (kind < 0) {
 436       /* The below is of course bogus */
 437       if (foo_read(new_client,FOO_REG_GENERIC) != FOO_GENERIC_VALUE)
 438          goto ERROR1;
 439     }
 440
 441     /* SENSORS ONLY START */
 442
 443     /* Next, specific detection. This is especially important for `sensors'
 444        devices. */
 445
 446     /* Determine the chip type. Not needed if a `force_CHIPTYPE' parameter
 447        was used. */
 448     if (kind <= 0) {
 449       i = foo_read(new_client,FOO_REG_CHIPTYPE);
 450       if (i == FOO_TYPE_1)
 451         kind = chip1; /* As defined in the enum */
 452       else if (i == FOO_TYPE_2)
 453         kind = chip2;
 454       else {
 455         printk("foo: Ignoring 'force' parameter for unknown chip at "
 456                "adapter %d, address 0x%02x\n",i2c_adapter_id(adapter),address);
 457         goto ERROR1;
 458       }
 459     }
 460
 461     /* Now set the type and chip names */
 462     if (kind == chip1) {
 463       type_name = "chip1"; /* For /proc entry */
 464       client_name = "CHIP 1";
 465     } else if (kind == chip2) {
 466       type_name = "chip2"; /* For /proc entry */
 467       client_name = "CHIP 2";
 468     }
 469
 470     /* Reserve the ISA region */
 471     if (is_isa)
 472       request_region(address,FOO_EXTENT,type_name);
 473
 474     /* SENSORS ONLY END */
 475
 476     /* Fill in the remaining client fields. */
 477     strcpy(new_client->name,client_name);
 478
 479     /* SENSORS ONLY BEGIN */
 480     data->type = kind;
 481     /* SENSORS ONLY END */
 482
 483     new_client->id = foo_id++; /* Automatically unique */
 484     data->valid = 0; /* Only if you use this field */
 485     init_MUTEX(&data->update_lock); /* Only if you use this field */
 486
 487     /* Any other initializations in data must be done here too. */
 488
 489     /* Tell the i2c layer a new client has arrived */
 490     if ((err = i2c_attach_client(new_client)))
 491       goto ERROR3;
 492
 493     /* SENSORS ONLY BEGIN */
 494     /* Register a new directory entry with module sensors. See below for
 495        the `template' structure. */
 496     if ((i = i2c_register_entry(new_client, type_name,
 497                                     foo_dir_table_template,THIS_MODULE)) < 0) {
 498       err = i;
 499       goto ERROR4;
 500     }
 501     data->sysctl_id = i;
 502
 503     /* SENSORS ONLY END */
 504
 505     /* This function can write default values to the client registers, if
 506        needed. */
 507     foo_init_client(new_client);
 508     return 0;
 509
 510     /* OK, this is not exactly good programming practice, usually. But it is
 511        very code-efficient in this case. */
 512
 513     ERROR4:
 514       i2c_detach_client(new_client);
 515     ERROR3:
 516     ERROR2:
 517     /* SENSORS ONLY START */
 518       if (is_isa)
 519         release_region(address,FOO_EXTENT);
 520     /* SENSORS ONLY END */
 521     ERROR1:
 522       kfree(new_client);
 523     ERROR0:
 524       return err;
 525   }
 526
 527
 528 Removing the client
 529 ===================
 530
 531 The detach_client call back function is called when a client should be
 532 removed. It may actually fail, but only when panicking. This code is
 533 much simpler than the attachment code, fortunately!
 534
 535   int foo_detach_client(struct i2c_client *client)
 536   {
 537     int err,i;
 538
 539     /* SENSORS ONLY START */
 540     /* Deregister with the `i2c-proc' module. */
 541     i2c_deregister_entry(((struct lm78_data *)(client->data))->sysctl_id);
 542     /* SENSORS ONLY END */
 543
 544     /* Try to detach the client from i2c space */
 545     if ((err = i2c_detach_client(client))) {
 546       printk("foo.o: Client deregistration failed, client not detached.\n");
 547       return err;
 548     }
 549
 550     /* SENSORS ONLY START */
 551     if i2c_is_isa_client(client)
 552       release_region(client->addr,LM78_EXTENT);
 553     /* SENSORS ONLY END */
 554
 555     kfree(client); /* Frees client data too, if allocated at the same time */
 556     return 0;
 557   }
 558
 559
 560 Initializing the module or kernel
 561 =================================
 562
 563 When the kernel is booted, or when your foo driver module is inserted,
 564 you have to do some initializing. Fortunately, just attaching (registering)
 565 the driver module is usually enough.
 566
 567   /* Keep track of how far we got in the initialization process. If several
 568      things have to initialized, and we fail halfway, only those things
 569      have to be cleaned up! */
 570   static int __initdata foo_initialized = 0;
 571
 572   int __init foo_init(void)
 573   {
 574     int res;
 575     printk("foo version %s (%s)\n",FOO_VERSION,FOO_DATE);
 576
 577     if ((res = i2c_add_driver(&foo_driver))) {
 578       printk("foo: Driver registration failed, module not inserted.\n");
 579       foo_cleanup();
 580       return res;
 581     }
 582     foo_initialized ++;
 583     return 0;
 584   }
 585
 586   int __init foo_cleanup(void)
 587   {
 588     int res;
 589     if (foo_initialized == 1) {
 590       if ((res = i2c_del_driver(&foo_driver))) {
 591         printk("foo: Driver registration failed, module not removed.\n");
 592         return res;
 593       }
 594       foo_initialized --;
 595     }
 596     return 0;
 597   }
 598
 599   #ifdef MODULE
 600
 601   /* Substitute your own name and email address */
 602   MODULE_AUTHOR("Frodo Looijaard <frodol@dds.nl>"
 603   MODULE_DESCRIPTION("Driver for Barf Inc. Foo I2C devices");
 604
 605   int init_module(void)
 606   {
 607     return foo_init();
 608   }
 609
 610   int cleanup_module(void)
 611   {
 612     return foo_cleanup();
 613   }
 614
 615   #endif /* def MODULE */
 616
 617 Note that some functions are marked by `__init', and some data structures
 618 by `__init_data'. If this driver is compiled as part of the kernel (instead
 619 of as a module), those functions and structures can be removed after
 620 kernel booting is completed.
 621
 622 Command function
 623 ================
 624
 625 A generic ioctl-like function call back is supported. You will seldom
 626 need this. You may even set it to NULL.
 627
 628   /* No commands defined */
 629   int foo_command(struct i2c_client *client, unsigned int cmd, void *arg)
 630   {
 631     return 0;
 632   }
 633
 634
 635 Sending and receiving
 636 =====================
 637
 638 If you want to communicate with your device, there are several functions
 639 to do this. You can find all of them in i2c.h.
 640
 641 If you can choose between plain i2c communication and SMBus level
 642 communication, please use the last. All adapters understand SMBus level
 643 commands, but only some of them understand plain i2c!
 644
 645
 646 Plain i2c communication
 647 -----------------------
 648
 649   extern int i2c_master_send(struct i2c_client *,const char* ,int);
 650   extern int i2c_master_recv(struct i2c_client *,char* ,int);
 651
 652 These routines read and write some bytes from/to a client. The client
 653 contains the i2c address, so you do not have to include it. The second
 654 parameter contains the bytes the read/write, the third the length of the
 655 buffer. Returned is the actual number of bytes read/written.
 656
 657   extern int i2c_transfer(struct i2c_adapter *adap, struct i2c_msg msg[],
 658                           int num);
 659
 660 This sends a series of messages. Each message can be a read or write,
 661 and they can be mixed in any way. The transactions are combined: no
 662 stop bit is sent between transaction. The i2c_msg structure contains
 663 for each message the client address, the number of bytes of the message
 664 and the message data itself.
 665
 666 You can read the file `i2c-protocol' for more information about the
 667 actual i2c protocol.
 668
 669
 670 SMBus communication
 671 -------------------
 672
 673   extern s32 i2c_smbus_xfer (struct i2c_adapter * adapter, u16 addr,
 674                              unsigned short flags,
 675                              char read_write, u8 command, int size,
 676                              union i2c_smbus_data * data);
 677
 678   This is the generic SMBus function. All functions below are implemented
 679   in terms of it. Never use this function directly!
 680
 681
 682   extern s32 i2c_smbus_write_quick(struct i2c_client * client, u8 value);
 683   extern s32 i2c_smbus_read_byte(struct i2c_client * client);
 684   extern s32 i2c_smbus_write_byte(struct i2c_client * client, u8 value);
 685   extern s32 i2c_smbus_read_byte_data(struct i2c_client * client, u8 command);
 686   extern s32 i2c_smbus_write_byte_data(struct i2c_client * client,
 687                                        u8 command, u8 value);
 688   extern s32 i2c_smbus_read_word_data(struct i2c_client * client, u8 command);
 689   extern s32 i2c_smbus_write_word_data(struct i2c_client * client,
 690                                        u8 command, u16 value);
 691   extern s32 i2c_smbus_process_call(struct i2c_client * client,
 692                                     u8 command, u16 value);
 693   extern s32 i2c_smbus_read_block_data(struct i2c_client * client,
 694                                        u8 command, u8 *values);
 695   extern s32 i2c_smbus_write_block_data(struct i2c_client * client,
 696                                         u8 command, u8 length,
 697                                         u8 *values);
 698
 699 All these transactions return -1 on failure. The 'write' transactions
 700 return 0 on success; the 'read' transactions return the read value, except
 701 for read_block, which returns the number of values read. The block buffers
 702 need not be longer than 32 bytes.
 703
 704 You can read the file `smbus-protocol' for more information about the
 705 actual SMBus protocol.
 706
 707
 708 General purpose routines
 709 ========================
 710
 711 Below all general purpose routines are listed, that were not mentioned
 712 before.
 713
 714   /* This call returns a unique low identifier for each registered adapter,
 715    * or -1 if the adapter was not registered.
 716    */
 717   extern int i2c_adapter_id(struct i2c_adapter *adap);
 718
 719
 720 The sensors sysctl/proc interface
 721 =================================
 722
 723 This section only applies if you write `sensors' drivers.
 724
 725 Each sensors driver creates a directory in /proc/sys/dev/sensors for each
 726 registered client. The directory is called something like foo-i2c-4-65.
 727 The sensors module helps you to do this as easily as possible.
 728
 729 The template
 730 ------------
 731
 732 You will need to define a ctl_table template. This template will automatically
 733 be copied to a newly allocated structure and filled in where necessary when
 734 you call sensors_register_entry.
 735
 736 First, I will give an example definition.
 737   static ctl_table foo_dir_table_template[] = {
 738     { FOO_SYSCTL_FUNC1, "func1", NULL, 0, 0644, NULL, &i2c_proc_real,
 739       &i2c_sysctl_real,NULL,&foo_func },
 740     { FOO_SYSCTL_FUNC2, "func2", NULL, 0, 0644, NULL, &i2c_proc_real,
 741       &i2c_sysctl_real,NULL,&foo_func },
 742     { FOO_SYSCTL_DATA, "data", NULL, 0, 0644, NULL, &i2c_proc_real,
 743       &i2c_sysctl_real,NULL,&foo_data },
 744     { 0 }
 745   };
 746
 747 In the above example, three entries are defined. They can either be
 748 accessed through the /proc interface, in the /proc/sys/dev/sensors/*
 749 directories, as files named func1, func2 and data, or alternatively
 750 through the sysctl interface, in the appropriate table, with identifiers
 751 FOO_SYSCTL_FUNC1, FOO_SYSCTL_FUNC2 and FOO_SYSCTL_DATA.
 752
 753 The third, sixth and ninth parameters should always be NULL, and the
 754 fourth should always be 0. The fifth is the mode of the /proc file;
 755 0644 is safe, as the file will be owned by root:root.
 756
 757 The seventh and eighth parameters should be &i2c_proc_real and
 758 &i2c_sysctl_real if you want to export lists of reals (scaled
 759 integers). You can also use your own function for them, as usual.
 760 Finally, the last parameter is the call-back to gather the data
 761 (see below) if you use the *_proc_real functions.
 762
 763
 764 Gathering the data
 765 ------------------
 766
 767 The call back functions (foo_func and foo_data in the above example)
 768 can be called in several ways; the operation parameter determines
 769 what should be done:
 770
 771   * If operation == SENSORS_PROC_REAL_INFO, you must return the
 772     magnitude (scaling) in nrels_mag;
 773   * If operation == SENSORS_PROC_REAL_READ, you must read information
 774     from the chip and return it in results. The number of integers
 775     to display should be put in nrels_mag;
 776   * If operation == SENSORS_PROC_REAL_WRITE, you must write the
 777     supplied information to the chip. nrels_mag will contain the number
 778     of integers, results the integers themselves.
 779
 780 The *_proc_real functions will display the elements as reals for the
 781 /proc interface. If you set the magnitude to 2, and supply 345 for
 782 SENSORS_PROC_REAL_READ, it would display 3.45; and if the user would
 783 write 45.6 to the /proc file, it would be returned as 4560 for
 784 SENSORS_PROC_REAL_WRITE. A magnitude may even be negative!
 785
 786 An example function:
 787
 788   /* FOO_FROM_REG and FOO_TO_REG translate between scaled values and
 789      register values. Note the use of the read cache. */
 790   void foo_in(struct i2c_client *client, int operation, int ctl_name,
 791               int *nrels_mag, long *results)
 792   {
 793     struct foo_data *data = client->data;
 794     int nr = ctl_name - FOO_SYSCTL_FUNC1; /* reduce to 0 upwards */
 795
 796     if (operation == SENSORS_PROC_REAL_INFO)
 797       *nrels_mag = 2;
 798     else if (operation == SENSORS_PROC_REAL_READ) {
 799       /* Update the readings cache (if necessary) */
 800       foo_update_client(client);
 801       /* Get the readings from the cache */
 802       results[0] = FOO_FROM_REG(data->foo_func_base[nr]);
 803       results[1] = FOO_FROM_REG(data->foo_func_more[nr]);
 804       results[2] = FOO_FROM_REG(data->foo_func_readonly[nr]);
 805       *nrels_mag = 2;
 806     } else if (operation == SENSORS_PROC_REAL_WRITE) {
 807       if (*nrels_mag >= 1) {
 808         /* Update the cache */
 809         data->foo_base[nr] = FOO_TO_REG(results[0]);
 810         /* Update the chip */
 811         foo_write_value(client,FOO_REG_FUNC_BASE(nr),data->foo_base[nr]);
 812       }
 813       if (*nrels_mag >= 2) {
 814         /* Update the cache */
 815         data->foo_more[nr] = FOO_TO_REG(results[1]);
 816         /* Update the chip */
 817         foo_write_value(client,FOO_REG_FUNC_MORE(nr),data->foo_more[nr]);
 818       }
 819     }
 820   }