iic(4) and iic(9) man pages for I2C framework.

iic(9) page was written by Jason Thorpe but, surprisingly,
wasn't commited to NetBSD (r).

4 files changed, 434 insertions, 5 deletions

diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile
index 60d0f877fc3..93a745078ff 100644
--- a/share/man/man4/Makefile
+++ b/share/man/man4/Makefile
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile,v 1.261 2004/05/23 02:43:42 deraadt Exp $
+#	$OpenBSD: Makefile,v 1.262 2004/05/23 18:37:06 grange Exp $
 
 MAN=	aac.4 ac97.4 acphy.4 addcom.4 adv.4 aha.4 ahb.4 ahc.4 \
 	aic.4 amdpm.4 ami.4 amphy.4 an.4 aria.4 ast.4 atalk.4 \
@@ -12,7 +12,7 @@ MAN=	aac.4 ac97.4 acphy.4 addcom.4 adv.4 aha.4 ahb.4 ahc.4 \
 	faith.4 fd.4 fdc.4 fms.4 fpa.4 fxp.4 gdt.4 gem.4 gif.4 \
 	gpr.4 gre.4 gtp.4 hifn.4 hil.4 hilid.4 hilkbd.4 hilms.4 \
 	hme.4 hsq.4 icmp.4 icmp6.4 icsphy.4 idp.4 ifmedia.4 \
-	iha.4 inet.4 inet6.4 inphy.4 iop.4 iophy.4 ioprbs.4 \
+	iha.4 iic.4 inet.4 inet6.4 inphy.4 iop.4 iophy.4 ioprbs.4 \
 	iopsp.4 ip.4 ip6.4 ipcomp.4 ipsec.4 isa.4 isapnp.4 \
 	ises.4 iso.4 isp.4 it.4 ksyms.4 kue.4 lc.4 lge.4 lkm.4 \
 	lm.4 lmc.4 lo.4 lofn.4 lpt.4 lxtphy.4 maestro.4 midi.4 \
diff --git a/share/man/man4/iic.4 b/share/man/man4/iic.4
new file mode 100644
index 00000000000..b7eea64d61f
--- /dev/null
+++ b/share/man/man4/iic.4
@@ -0,0 +1,96 @@
+.\"	$OpenBSD: iic.4,v 1.1 2004/05/23 18:37:06 grange Exp $
+.\"
+.\" Copyright (c) 2004 Alexander Yurchenko <grange@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd May 15, 2004
+.Dt IIC 4
+.Os
+.Sh NAME
+.Nm iic
+.Nd Inter IC (I2C) bus
+.Sh SYNOPSIS
+.Cd "iic* at gscsio?"
+.Sh DESCRIPTION
+.Tn I2C
+is a two-wire bus developed by Philips used for connecting
+integrated circuits.
+It is commonly used for connecting devices such as EEPROMs,
+temperature sensors, fan controllers, real-time clocks, tuners,
+and other types of integrated circuits.
+.Pp
+The
+.Nm
+driver provides uniform programming interface layer between
+.Tn I2C
+master controllers and various
+.Tn I2C
+slave devices.
+Each
+.Tn I2C
+master controller attaches an
+.Xr iic 4
+framework, several slave devices can be attached then to the
+.Xr iic 4
+bus.
+.Pp
+All
+.Tn I2C
+slave devices are uniquely identified by the address on the bus.
+Master accesses particular slave device using its address.
+Device address should be specified in the kernel configuration file
+with the
+.Cd addr
+locator.
+.Pp
+System Management Bus (SMBus) protocol is also supported by emulating
+it with the
+.Tn I2C
+commands.
+.Sh SUPPORTED DEVICES
+.Bl -tag -width XXXX -compact
+.It Master controllers
+.Bl -tag -width XXXX -compact
+.It Xr gscsio 4
+National Semiconductor Geode SC1100 Super I/O ACCESS.bus
+.El
+.It Slave devices
+.Bl -tag -width XXXX -compact
+.It Xr lmtemp 4
+National Semiconductor LM75/LM77 temperature sensor
+.El
+.El
+.Sh SEE ALSO
+.Xr gscsio 4 ,
+.Xr intro 4 ,
+.Xr lmtemp 4 ,
+.Xr iic 9
+.Sh HISTORY
+The
+.Tn I2C
+framework first appeared in
+.Nx 2.0 .
+.Ox
+support was added in
+.Ox 3.6 .
+.Sh AUTHORS
+The
+.Tn I2C
+framework was written by
+Steve C. Woodford and Jason R. Thorpe for
+.Nx
+and then ported to
+.Ox
+by
+.An Alexander Yurchenko Aq grange@openbsd.org .
diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 540fa4b69f8..acdfb1d2386 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile,v 1.77 2004/02/09 19:21:52 espie Exp $
+#	$OpenBSD: Makefile,v 1.78 2004/05/23 18:37:06 grange Exp $
 #	$NetBSD: Makefile,v 1.4 1996/01/09 03:23:01 thorpej Exp $
 
 #	Makefile for section 9 (kernel function and variable) manual pages.
@@ -8,8 +8,8 @@ MAN=	altq.9 audio.9 autoconf.9 boot.9 bus_dma.9 bus_space.9 \
 	dohooks.9 dopowerhooks.9 doshutdownhooks.9 dostartuphooks.9 \
 	extattr.9 file.9 \
 	fork1.9 extent.9 getdevvp.9 getnewvnode.9 hash.9 hashinit.9 \
-	hardclock.9 hook_establish.9 hz.9 hzto.9 intro.9 inittodr.9 log.9 \
-	kern.9 knote.9 kthread.9 ktrace.9 lock.9 \
+	hardclock.9 hook_establish.9 hz.9 hzto.9 iic.9 intro.9 inittodr.9 \
+	kern.9 knote.9 kthread.9 ktrace.9 lock.9 log.9 \
 	malloc.9 mbuf.9 mbuf_tags.9 md5.9 microtime.9 namei.9 \
 	panic.9 pfind.9 physio.9 pmap.9 \
 	pool.9 powerhook_establish.9 ppsratecheck.9 printf.9 psignal.9 \
diff --git a/share/man/man9/iic.9 b/share/man/man9/iic.9
new file mode 100644
index 00000000000..3bd0a70f08a
--- /dev/null
+++ b/share/man/man9/iic.9
@@ -0,0 +1,333 @@
+.\"	$OpenBSD: iic.9,v 1.1 2004/05/23 18:37:06 grange Exp $
+.\"
+.\" Copyright (c) 2003 Wasabi Systems, Inc.
+.\" All rights reserved.
+.\"
+.\" Written by Jason R. Thorpe 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 July 29, 2003
+.Dt IIC 9
+.Os
+.Sh NAME
+.Nm iic_acquire_bus ,
+.Nm iic_release_bus ,
+.Nm iic_exec ,
+.Nm iic_smbus_write_byte ,
+.Nm iic_smbus_read_byte ,
+.Nm iic_smbus_receive_byte
+.Nd Inter IC (I2C) bus
+.Sh SYNOPSIS
+.Fd #include <dev/i2c/i2cvar.h>
+.Ft int
+.Fo iic_acquire_bus
+.Fa "i2c_tag_t ic"
+.Fa "int flags"
+.Fc
+.Ft int
+.Fo iic_release_bus
+.Fa "i2c_tag_t ic"
+.Fa "int flags"
+.Fc
+.Ft int
+.Fo iic_exec
+.Fa "i2c_tag_t ic"
+.Fa "i2c_op_t op"
+.Fa "i2c_addr_t addr"
+.Fa "const void *cmdbuf"
+.Fa "size_t cmdlen"
+.Fa "void *buf"
+.Fa "size_t len"
+.Fa "int flags"
+.Fc
+.Ft int
+.Fo iic_smbus_write_byte
+.Fa "i2c_tag_t ic"
+.Fa "i2c_addr_t addr"
+.Fa "uint8_t cmd"
+.Fa "uint8_t data"
+.Fa "int flags"
+.Fc
+.Ft int
+.Fo iic_smbus_read_byte
+.Fa "i2c_tag_t ic"
+.Fa "i2c_addr_t addr"
+.Fa "uint8_t cmd"
+.Fa "uint8_t *datap"
+.Fa "int flags"
+.Fc
+.Ft int
+.Fo iic_smbus_receive_byte
+.Fa "i2c_tag_t ic"
+.Fa "i2c_addr_t addr"
+.Fa "uint8_t *datap"
+.Fa "int flags"
+.Fc
+.Sh DESCRIPTION
+I2C is a two-wire bus developed by Philips used for connecting
+integrated circuits.
+It is commonly used for connecting devices such as EEPROMs,
+temperature sensors, fan controllers, real-time clocks, tuners,
+and other types of integrated circuits.
+The
+.Nm iic
+interface provides an means of communicating with I2C-connected devices.
+The System Management Bus, or SMBus, is a variant of the I2C bus with
+a simplified command protocol and some electrical differences.
+.Sh DATA TYPES
+Drivers for devices attached to the I2C bus will make use of the
+following data types:
+.Bl -tag -width i2c_addr_t
+.It Fa i2c_tag_t
+Controller tag for the I2C bus.
+This is a pointer to a
+.Fa struct i2c_controller ,
+consisting of function pointers filled in by the I2C
+controller driver.
+.It Fa i2c_op_t
+I2C bus operation.
+The following I2C bus operations are defined:
+.Bl -tag -width XXXX
+.It I2C_OP_READ
+Perform a read operation.
+.It I2C_OP_READ_WITH_STOP
+Perform a read operation and send a STOP condition on the I2C bus at
+the conclusion of the read.
+.It I2C_OP_WRITE
+Perform a write operation.
+.It I2C_OP_WRITE_WITH_STOP
+Perform a write operation and send a STOP condition on the I2C bus at
+the conclusion of the write.
+.El
+.It Fa i2c_addr_t
+I2C device address.
+.It Fa struct i2c_attach_args
+Devices are attached to an I2C bus using this structure.
+The structure is defined as follows:
+.Bd -literal
+struct i2c_attach_args {
+	i2c_tag_t ia_tag;	/* controller */
+	i2c_addr_t ia_addr;	/* address of device */
+	int ia_size;		/* size (for EEPROMs) */
+};
+.Ed
+.El
+.Sh FUNCTIONS
+The following functions comprise the API provided to drivers of
+I2C-connected devices:
+.Bl -tag -width iic_exec
+.It Fn iic_acquire_bus "ic" "flags"
+Acquire an exclusive lock on the I2C bus.
+This is required since only one device may communicate on the
+I2C bus at a time.
+Drivers should acquire the bus lock, perform the I2C bus operations
+necessary, and then release the bus lock.
+Passing the
+.Fa I2C_F_POLL
+flag indicates to
+.Fn iic_acquire_bus
+that sleeping is not permitted.
+.It Fn iic_release_bus "ic" "flags"
+Release an exclusive lock on the I2C bus.
+If the
+.Fa I2C_F_POLL
+flag was passed to
+.Fn iic_acquire_bus ,
+it must also be passed to
+.Fn iic_release_bus .
+.\" XXXJRT Someone help me with the mark-up here!
+.\" .It Fn iic_exec "ic" "op" "addr" "cmdbuf" "cmdlen" "buf" "len" "flags"
+.It Fn iic_exec "ic" "op" "addr" "cmdbuf" "cmdlen" "buf" "len"
+Perform a a series of I2C transactions on the bus.
+.Fn iic_exec
+initiates the operation by sending a START condition on the I2C
+bus and then transmitting the address of the target device along
+with the transaction type.
+If
+.Fa cmdlen
+is non-zero, the command pointed to by
+.Fa cmdbuf
+is then send to the device.
+If
+.Fa buflen
+is non-zero,
+.Fn iic_exec
+will then transmit or receive the data, as indicated by
+.Fa op .
+If
+.Fa op
+indicates a read operation,
+.Fn iic_exec
+will send a REPEATED START before transferring the data.
+If
+.Fa op
+so indicates, a STOP condition will be sent on the I2C
+bus at the conclusion of the operation.
+Passing the
+.Fa I2C_F_POLL
+flag indicates to
+.Fn iic_exec
+that sleeping is not permitted.
+.It Fn iic_smbus_write_byte "ic" "addr" "cmd" "data" "flags"
+Perform an SMBus WRITE BYTE operation.  This is equivalent to
+I2C_OP_WRITE_WITH_STOP with
+.Fa cmdlen
+of 1 and
+.Fa len
+of 1.
+.It Fn iic_smbus_read_byte "ic" "addr" "cmd" "datap" "flags"
+Perform an SMBus READ BYTE operation.  This is equivalent to
+I2C_OP_READ_WITH_STOP with
+.Fa cmdlen
+of 1 and
+.Fa len
+of 1.
+.It Fn iic_smbus_receive_byte "ic" "addr" "datap" "flags"
+Perform an SMBus RECEIVE BYTE operation.  This is equivalent to
+I2C_OP_READ_WITH_STOP with
+.Fa cmdlen
+of 0 and
+.Fa len
+of 1.
+.El
+.Sh CONTROLLER INTERFACE
+The I2C controller driver must fill in the function pointers of
+an
+.Fa i2c_controller
+structure, which is defined as follows:
+.Bd -literal
+struct i2c_controller {
+	void	*ic_cookie;	/* controller private */
+
+	int	(*ic_acquire_bus)(void *, int);
+	void	(*ic_release_bus)(void *, int);
+
+	int	(*ic_exec)(void *, i2c_op_t, i2c_addr_t,
+		   const void *, size_t, void *, size_t, int);
+
+	int	(*ic_send_start)(void *, int);
+	int	(*ic_send_stop)(void *, int);
+	int	(*ic_initiate_xfer)(void *, i2c_addr_t, int);
+	int	(*ic_read_byte)(void *, uint8_t *, int);
+	int	(*ic_write_byte)(void *, uint8_t, int);
+};
+.Ed
+.Pp
+The
+.Fn (*ic_acquire_bus)
+and
+.Fn (*ic_release_bus)
+functions must always be provided.
+.Pp
+The controller driver may elect to provide an
+.Fn (*ic_exec)
+function.
+This function is intended for use by automated controllers
+that do not provide manual control over I2C bus conditions
+such as START and STOP.
+.Pp
+If the
+.Fn (*ic_exec)
+function is not provided, the following 5 functions will be
+used by
+.Fn iic_exec
+in order to execute the I2C bus operation:
+.Bl -tag -width XXXX
+.It Fn (*ic_send_start) "cookie" "flags"
+Send a START condition on the I2C bus.
+The
+.Fa I2C_F_POLL
+flag indicates that sleeping is not permitted.
+.It Fn (*ic_send_stop) "cookie" "flags"
+Send a STOP condition on the I2C bus.
+The
+.Fa I2C_F_POLL
+flag indicates that sleeping is not permitted.
+.It Fn (*ic_initiate_xfer) "cookie" "addr" "flags"
+Initiate a transfer on the I2C bus by sending a START condition and
+then transmitting the I2C device address and transfer type.
+The
+.Fa I2C_F_READ
+flag indicates a read transfer; the lack of this flag indicates a
+write transfer.
+The
+.Fa I2C_F_POLL
+flag indicates that sleeping is not permitted.
+The error code
+.Dv ETIMEDOUT
+should be returned if a timeout that would indicate that the
+device is not present occurs.
+.It Fn (*ic_read_byte) "cookie" "datap" "flags"
+Read a byte from the I2C bus into the memory location referenced by
+.Fa datap .
+The
+.Fa I2C_F_LAST
+flag indicates that this is the final byte of the transfer, and that
+a NACK condition should be sent on the I2C bus following the transfer
+of the byte.
+The
+.Fa I2C_F_STOP
+flag indicates that a STOP condition should be sent on the I2C bus following
+the transfer of the byte.
+The
+.Fa I2C_F_POLL
+flag indicates that sleeping is not permitted.
+.It Fn (*ic_write_byte) "cookie" "data" "flags"
+Write the byte contained in
+.Fa data
+to the I2C bus.
+The
+.Fa I2C_F_STOP
+flag indicates that a STOP condition should be sent on the I2C bus following
+the transfer of the byte.
+The
+.Fa I2C_F_POLL
+flag indicates that sleeping is not permitted.
+.El
+.Sh SEE ALSO
+.Xr iic 4
+.Sh HISTORY
+The
+.Nm iic
+API first appeared in
+.Nx 2.0 .
+.Ox
+support was added in
+.Ox 3.6 .
+.Sh AUTHORS
+The
+.Nm iic
+API was written by
+Steve C. Woodford and Jason R. Thorpe for
+.Nx
+and then ported to
+.Ox
+by
+.An Alexander Yurchenko Aq grange@openbsd.org .