[i2c] Documentation/i2c/dev-interface

[Jean Delvare]

Hi David,

On Tue, 11 Sep 2007 10:06:25 -0700, David Brownell wrote:
> > >Where are those defined?  Such functions don't seem to exist
> > >in in a library on any of my Linux distros.
> >
> > These are inline functions defined in i2c-dev.h. This header file (which
> > is different from the one in the kernel tree) is currently distributed
> > with the lm-sensors package, for historical reasons. This is explained
> > at the beginning of $SUBJECT.
> 
> Well, not quite at the beginning.  It's clearly wrong to have that
> in a <linux/i2c-dev.h> file that's not provided by Linux!  Not just
> counter to expectations, but counter to standard policy ... :(

Again, reasons are historical. Originally, there was a single i2c-dev.h
file, containing both kernel stuff (protected by "#ifdef KERNEL" or
some such) and definitions for user-space. However, several years ago,
we were told that "user-space should never include kernel headers" and
were forced to split i2c-dev.h into two different files, which we had to
maintain in parallel. It's only recently that it was finally admitted
that this rule was broken and that headers for user-space should be
generated from kernel headers. It's in place now as far as I can see,
but i2c-dev.h isn't yet integrated into the new model.

> > Soon we'll have a dedicated i2c-tools package and that header file will
> > be part of it:
> > http://www.lm-sensors.org/browser/i2c-tools/trunk/include/linux/i2c-dev.h
> 
> That shouldn't be a <linux/...> file at all, and it should be
> including the relevant linux headers (i2c.h, i2c-dev.h) rather
> than replicating any of their contents.

Correct. See above for why that's not the case.

> For that matter, the ioctl numbers belong in i2c-dev.h not i2c.h!
> (Probably not awkward to fix, since anything using i2c-dev.h must
> also include the other.)

I welcome patches, I just do not have the time to work on this myself.

> (...)
> > It can be argued that the rest of the file should be generated or
> > extracted from the i2c kernel headers themselves, now that we have a
> > clean way to do this.
> 
> Nope.  It should be argued that the kernel files and the userspace
> files should be entirely separate.  In fact, I'm surprised to hear
> you argue anything else ...

You're right.

> > >Also, a clear omission is the SMBus "block write-block read
> > >process call" primitive...
> >
> > Most probably because nobody uses it ;) I2C block read and write
> > functions are missing as well. Care to submit a patch?
> 
> I had one a while back, let me see if I still have a copy.  For
> portability I ended up avoiding the block proc call; it was just
> needed for some fixed-size transfers, and the important one could
> be handled with the (more widely supported) regular proc call.

Note that most modern SMBus controllers can go block process call, it's
just that the implementation is missing at the driver level. Shouldn't
be too hard to add if you need it.

-- 
Jean Delvare