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