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