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