diff options
| -rw-r--r-- | Documentation/DocBook/kernel-api.tmpl | 55 | ||||
| -rw-r--r-- | drivers/i2c/i2c-core.c | 13 | ||||
| -rw-r--r-- | include/linux/i2c.h | 11 |
3 files changed, 76 insertions, 3 deletions
diff --git a/Documentation/DocBook/kernel-api.tmpl b/Documentation/DocBook/kernel-api.tmpl index 8c5698a8c2e1..46bcff2849bd 100644 --- a/Documentation/DocBook/kernel-api.tmpl +++ b/Documentation/DocBook/kernel-api.tmpl @@ -643,6 +643,60 @@ X!Idrivers/video/console/fonts.c !Edrivers/spi/spi.c </chapter> + <chapter id="i2c"> + <title>I<superscript>2</superscript>C and SMBus Subsystem</title> + + <para> + I<superscript>2</superscript>C (or without fancy typography, "I2C") + is an acronym for the "Inter-IC" bus, a simple bus protocol which is + widely used where low data rate communications suffice. + Since it's also a licensed trademark, some vendors use another + name (such as "Two-Wire Interface", TWI) for the same bus. + I2C only needs two signals (SCL for clock, SDA for data), conserving + board real estate and minimizing signal quality issues. + Most I2C devices use seven bit addresses, and bus speeds of up + to 400 kHz; there's a high speed extension (3.4 MHz) that's not yet + found wide use. + I2C is a multi-master bus; open drain signaling is used to + arbitrate between masters, as well as to handshake and to + synchronize clocks from slower clients. + </para> + + <para> + The Linux I2C programming interfaces support only the master + side of bus interactions, not the slave side. + The programming interface is structured around two kinds of driver, + and two kinds of device. + An I2C "Adapter Driver" abstracts the controller hardware; it binds + to a physical device (perhaps a PCI device or platform_device) and + exposes a <structname>struct i2c_adapter</structname> representing + each I2C bus segment it manages. + On each I2C bus segment will be I2C devices represented by a + <structname>struct i2c_client</structname>. Those devices will + be bound to a <structname>struct i2c_driver</structname>, + which should follow the standard Linux driver model. + (At this writing, a legacy model is more widely used.) + There are functions to perform various I2C protocol operations; at + this writing all such functions are usable only from task context. + </para> + + <para> + The System Management Bus (SMBus) is a sibling protocol. Most SMBus + systems are also I2C conformant. The electrical constraints are + tighter for SMBus, and it standardizes particular protocol messages + and idioms. Controllers that support I2C can also support most + SMBus operations, but SMBus controllers don't support all the protocol + options that an I2C controller will. + There are functions to perform various SMBus protocol operations, + either using I2C primitives or by issuing SMBus commands to + i2c_adapter devices which don't support those I2C operations. + </para> + +!Iinclude/linux/i2c.h +!Fdrivers/i2c/i2c-boardinfo.c i2c_register_board_info +!Edrivers/i2c/i2c-core.c + </chapter> + <chapter id="splice"> <title>splice API</title> <para>) @@ -654,4 +708,5 @@ X!Idrivers/video/console/fonts.c !Ffs/splice.c </chapter> + </book> diff --git a/drivers/i2c/i2c-core.c b/drivers/i2c/i2c-core.c index 435925eba437..cccfa8678245 100644 --- a/drivers/i2c/i2c-core.c +++ b/drivers/i2c/i2c-core.c @@ -207,6 +207,7 @@ EXPORT_SYMBOL_GPL(i2c_bus_type); * i2c_new_device - instantiate an i2c device for use with a new style driver * @adap: the adapter managing the device * @info: describes one I2C device; bus_num is ignored + * Context: can sleep * * Create a device to work with a new style i2c driver, where binding is * handled through driver model probe()/remove() methods. This call is not @@ -255,6 +256,7 @@ EXPORT_SYMBOL_GPL(i2c_new_device); /** * i2c_unregister_device - reverse effect of i2c_new_device() * @client: value returned from i2c_new_device() + * Context: can sleep */ void i2c_unregister_device(struct i2c_client *client) { @@ -379,6 +381,7 @@ out_list: /** * i2c_add_adapter - declare i2c adapter, use dynamic bus number * @adapter: the adapter to add + * Context: can sleep * * This routine is used to declare an I2C adapter when its bus number * doesn't matter. Examples: for I2C adapters dynamically added by @@ -416,6 +419,7 @@ EXPORT_SYMBOL(i2c_add_adapter); /** * i2c_add_numbered_adapter - declare i2c adapter, use static bus number * @adap: the adapter to register (with adap->nr initialized) + * Context: can sleep * * This routine is used to declare an I2C adapter when its bus number * matters. Example: for I2C adapters from system-on-chip CPUs, or @@ -463,6 +467,14 @@ retry: } EXPORT_SYMBOL_GPL(i2c_add_numbered_adapter); +/** + * i2c_del_adapter - unregister I2C adapter + * @adap: the adapter being unregistered + * Context: can sleep + * + * This unregisters an I2C adapter which was previously registered + * by @i2c_add_adapter or @i2c_add_numbered_adapter. + */ int i2c_del_adapter(struct i2c_adapter *adap) { struct list_head *item, *_n; @@ -598,6 +610,7 @@ EXPORT_SYMBOL(i2c_register_driver); /** * i2c_del_driver - unregister I2C driver * @driver: the driver being unregistered + * Context: can sleep */ void i2c_del_driver(struct i2c_driver *driver) { diff --git a/include/linux/i2c.h b/include/linux/i2c.h index cae7d618030c..a24e267fd189 100644 --- a/include/linux/i2c.h +++ b/include/linux/i2c.h @@ -150,15 +150,20 @@ struct i2c_driver { /** * struct i2c_client - represent an I2C slave device + * @flags: I2C_CLIENT_TEN indicates the device uses a ten bit chip address; + * I2C_CLIENT_PEC indicates it uses SMBus Packet Error Checking * @addr: Address used on the I2C bus connected to the parent adapter. * @name: Indicates the type of the device, usually a chip name that's * generic enough to hide second-sourcing and compatible revisions. + * @adapter: manages the bus segment hosting this I2C device * @dev: Driver model device node for the slave. + * @irq: indicates the IRQ generated by this device (if any) * @driver_name: Identifies new-style driver used with this device; also * used as the module name for hotplug/coldplug modprobe support. * * An i2c_client identifies a single device (i.e. chip) connected to an - * i2c bus. The behaviour is defined by the routines of the driver. + * i2c bus. The behaviour exposed to Linux is defined by the driver + * managing the device. */ struct i2c_client { unsigned short flags; /* div., see below */ @@ -201,7 +206,7 @@ static inline void i2c_set_clientdata (struct i2c_client *dev, void *data) * @addr: stored in i2c_client.addr * @platform_data: stored in i2c_client.dev.platform_data * @irq: stored in i2c_client.irq - + * * I2C doesn't actually support hardware probing, although controllers and * devices may be able to use I2C_SMBUS_QUICK to tell whether or not there's * a device at a given address. Drivers commonly need more information than @@ -210,7 +215,7 @@ static inline void i2c_set_clientdata (struct i2c_client *dev, void *data) * i2c_board_info is used to build tables of information listing I2C devices * that are present. This information is used to grow the driver model tree * for "new style" I2C drivers. For mainboards this is done statically using - * i2c_register_board_info(), where @bus_num represents an adapter that isn't + * i2c_register_board_info(); bus numbers identify adapters that aren't * yet available. For add-on boards, i2c_new_device() does this dynamically * with the adapter already known. */ |