Commit d64f73be authored by David Brownell's avatar David Brownell Committed by Jean Delvare
Browse files

i2c: Add kernel documentation 



Generate I2C kerneldoc; fix various glitches and add "context" sections to
that documentation.  Most I2C and SMBus functions still have no kerneldoc.

Let me suggest providing kerneldoc for all the i2c_smbus_*() functions as
a small and mostly self-contained project for anyone so inclined.  :)

Signed-off-by: default avatarDavid Brownell <dbrownell@users.sourceforge.net>
Signed-off-by: default avatarJean Delvare <khali@linux-fr.org>
parent 4eb6bf6b

Documentation/DocBook/kernel-api.tmpl

+55 −0
Original line number Diff line number Diff line
@@ -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>

drivers/i2c/i2c-core.c

+13 −0
Original line number Diff line number Diff line
@@ -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)

{

include/linux/i2c.h

+8 −3
Original line number Diff line number Diff line
@@ -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.

 */

CRA Git | Maintained and supported by SUSTech CRA and CCSE