[i2c] [patch 2.6.21-git] i2c kerneldoc
Jean Delvare
khali at linux-fr.org
Mon May 14 16:18:37 CEST 2007
Hi David,
On Tue, 8 May 2007 13:17:38 -0700, David Brownell wrote:
> 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. :)
FWIW, these are already described in Documentation/i2c/smbus-protocol.
> Signed-off-by: David Brownell <dbrownell at users.sourceforge.net>
>
> ---
> Documentation/DocBook/kernel-api.tmpl | 55 ++++++++++++++++++++++++++++++++++
> drivers/i2c/i2c-core.c | 13 ++++++++
> include/linux/i2c.h | 11 ++++--
> 3 files changed, 76 insertions(+), 3 deletions(-)
>
> --- g26.orig/Documentation/DocBook/kernel-api.tmpl 2007-05-06 12:08:18.000000000 -0700
> +++ g26/Documentation/DocBook/kernel-api.tmpl 2007-05-08 08:10:18.000000000 -0700
> @@ -639,4 +639,59 @@ 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 (SCK for clock, SDA for data), conserving
The clock line is usually named SCL, not SCK.
> + 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
kHz (small z)
> + 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,
drivers
> + and two kinds of device.
devices
> + 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
> + an I2C bus segment.
It exposes one or more struct i2c_adapter - there are a couple
multi-bus devices out there.
> + 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
compliant? "conformant" isn't in my English dictionary.
> + 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>
Aren't you supposed to write somewhere that I2C is a Philips trademark
and SMBus an Intel trademark?
> +
> +!Iinclude/linux/i2c.h
> +!Fdrivers/i2c/i2c-boardinfo.c i2c_register_board_info
> +!Edrivers/i2c/i2c-core.c
> + </chapter>
> +
> +
> </book>
> --- g26.orig/include/linux/i2c.h 2007-05-06 12:07:39.000000000 -0700
> +++ g26/include/linux/i2c.h 2007-05-06 12:08:19.000000000 -0700
> @@ -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
I2C or i2c, but don't mix.
> * @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 (s
> * @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 (s
> * 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.
> */
> --- g26.orig/drivers/i2c/i2c-core.c 2007-05-06 12:07:39.000000000 -0700
> +++ g26/drivers/i2c/i2c-core.c 2007-05-08 12:30:48.000000000 -0700
> @@ -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 driver being unregistered
Hmm, no, a struct i2c_adapter represents a device, not a driver.
> + * 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)
> {
>
Thanks,
--
Jean Delvare
More information about the i2c
mailing list