[i2c] [patch 2.6.21-git] i2c kerneldoc

[David Brownell]

On Monday 14 May 2007, Jean Delvare wrote:
> 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.

Yes, but that's not kerneldoc... that's part of what makes that a
good small project.


> > --- 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.

Fixed.  Too much time looking at schematics for one chip
which merges SPI and I2C in one controller.  :)


> > +	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)

Typo, fixed.

 
> > +	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

That's correct as is.  (Two kinds) of driver.  (Attorneys) General.
Or:  "two driver types" etc.


> > +	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.

"Representing each I2C bus segment it manages", then.

   
> > +	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.

Compliant is a tighter requirement; one talks about "compliance testing"
as part of licensing/branding.  Conformance is a looser notion, more to
do with corresponding shape/appearance than anything deeper ... one might
conform to unwritten social laws, but be a rebel at heart.


> > +	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?

Normally such things are taken care of by blanket disclaimers at the
beginning of documentation, not in-line.  Linux should probably get one
of those.  FWIW my copy of the SMBus 2.0 spec has no such declarations ...


> > --- 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.

Typo, fixed.


> > --- 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

> > @@ -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.

Typo, fixed.

Update patch in next email ...


> 
> Thanks,
> -- 
> Jean Delvare
>