Here is a description of the new i2c framework I will be checking in
shortly.

Eduardo

.\"	$NetBSD: mdoc.template,v 1.4 2000/08/28 16:58:58 kleink Exp $
.\"
.\" Copyright 2001 Wasabi Systems, Inc.
.\" All rights reserved.
.\"
.\" Written by Eduardo Horvath for Wasabi Systems, Inc.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"      This product includes software developed for the NetBSD Project by
.\"      Wasabi Systems, Inc.
.\" 4. The name of Wasabi Systems, Inc. may not be used to endorse
.\"    or promote products derived from this software without specific prior
.\"    written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY WASABI SYSTEMS, INC. ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL WASABI SYSTEMS, INC
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd February 15, 2002
.Dt I2C 9
.Os
.Sh NAME
.Nm i2c_cmd
.Nd i2c bus access framework
.Sh SYNOPSIS
.Fd #include <dev/i2c/i2c.h>
.Ft int
.Fn i2c_cmd "i2c_ctlr_t bus" "int16_t addr" "struct i2c_op *op" "int nops" "int flags"
.Sh DESCRIPTION
The i2c bus was developed by Phillips Semiconductor as a cheap, simple way
to communicate with small device that do not need any great bandwidth.  
The specification describes the bus, and how to transfer data on it, but 
does not provide any standard command set.  Each device may have its own
command set, and those are often extremely sensitive to individual bus 
phases.
.Pp
The
.Nx
.Em i2c 
bus framework is designed to allow target device drivers the ability
to control exactly what bus phases are used to communicate with a device,
while not overly constraining intelligent 
.Em i2c 
controllers that can handle
complete transactions or even DMA commands from memory themselves.
.Ss INITIALIZATION
An
.Em i2c
controller needs to allocate and initialize a
.Va struct i2c_ctlr,
setting the 
.Va ic_cmd 
field to point to the controller's command routine.  The
.Va void *ic_cookie
field is available to the controller driver for arbitrary data.
Drivers for intelligent controllers that are capable of cycling through
different bus phases in hardware will want to use their own command routine,
but dumb controllers that need software to cycle through the phases for
them can make use of the 
.Va i2c_bus 
infrastructure by allocating and initializing a
.Va struct _i2c_adapter,
putting the 
.Fn i2c_bus_cmd
routine in the 
.Va ic_cmd
field and a pointer to the 
.Va struct _i2c_adapter
in the 
.Va struct i2c_ctlr
it provides.  The driver should then fill out a
.Va struct i2cbus_attach_args,
pointing 
.Va char *i2a_busname
to the string 
.Li "i2c"
and placing a pointer to the driver's
.Va struct i2c_ctlr
in
.Va i2c_ctlr_t i2a_ctlr.
.Pp
The 
.Em i2c
infrastructure will then probe the entire
.Em i2c
bus attached to that controller to determine what devices exist on it,
calling each target driver's
.Fn probe
routine with a
.Va struct i2c_attach_args.
The 
.Em i2c
bus address being probed is in the 
.Va int16_t ia_addr
and 
.Va int	ia_10bit
is cleared if it is a 7-bit
.Em i2c
address.  The probe routine may use the passed 
.Va i2c_ctlr_t	ia_ctlr
to call
.Fn i2c_op
to transfer data to or from the device if needed.
.Ss OPERATION
.Em I2c 
commands are sent in a series of operations.  Each operation is a 
unidirectional transfer of an arbitrary number of bytes and is described
by a
.Va i2c_op
structure.  The structure is laid out as follows:
.Bd -literal
struct i2c_op {
	void	*io_data;	/* Pointer to data buffer */
	size_t	io_len;		/* Length of data to transfer */
	int	io_flags;	/* Flags describing transfer */
};
.Ed
.Pp
The 
.Em i2c_op
flag should be set to either
.Em I2CO_READ
if data is to be transferred from the target device or
.Em I2CO_WRITE
if data is to be transferred to the target device in that operation.
.Pp
An 
.Em i2c 
command consists of a sequence of bus operations to the same device.
They are completed atomically without sending a 
.Em STOP
command between bytes or operations, thus preventing other 
communications on that particular
.Em i2c
bus from interleaving with those operations, possibly causing data
corruption or mis-communication.  A
.Em STOP
phase is sent at the end of the command.
.Pp
An array of 
.Va i2c_op
structures are passed to 
.Fn i2c_cmd
in
.Va op
to dispatch a single command, along with the 
.Va nops
the number of operations.  The 
.Va i2c_ctlr_t bus
determines which 
.Em i2c
bus will be used, and 
.Va int16_t addr
is the address of the device to communicate with, or the reserved 
address
.Va I2C_GENERAL_CALL
to generate a general call.  The 
.Va flags
parameter may contain zero or any combination of:
.Bl -tag -width I2C_REPSTART -compact
.It Dv I2C_REPSTART
repeat a 
.Em START 
phase between each byte transferred.
.It Dv I2C_POLL
polled command, do not use interrupts.
.It Dv I2C_10BIT
use 10-bit addressing instead of 7-bit addressing.
.El
.Pp
.Fn i2c_cmd
returns only after command processing is complete.
.Sh RETURN VALUES
.Fn i2c_cmd
returns 0 on success or an error.
.Sh FILES
.Bl -tag -width sys/dev/i2c/i2c_bus.h
.It Pa sys/dev/i2c/i2c.h
header file for use by 
.Em i2c
target and controller drivers
.It Pa sys/dev/i2c/i2c_bus.h
header file for use by 
.Em i2c
controller drivers that use
.Fn i2c_bus_cmd
.El 
.Sh EXAMPLES
The best place to look for examples is in the kernel sources.
.Sh STANDARDS
The 
.Em i2c
standard is maintained by
.Em Phillips Semiconductors.
.Sh HISTORY
The 
.Nm 
interface appeared in
.Nx 1.6 .
.Sh AUTHORS
The 
.Nm 
interface was designed and implemented by Eduardo Horvath.