[src/uebayasi-xip]: src/share/man/man9 Add also the SMBus specification.

[jruoho <jruoho%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/a2c31529b048
branches:  uebayasi-xip
changeset: 751627:a2c31529b048
user:      jruoho <jruoho%NetBSD.org@localhost>
date:      Wed Mar 17 18:55:14 2010 +0000

description:
Add also the SMBus specification.

diffstat:

 share/man/man9/iic.9 |  349 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 349 insertions(+), 0 deletions(-)

diffs (truncated from 353 to 300 lines):

diff -r bd06e3a4b218 -r a2c31529b048 share/man/man9/iic.9
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/iic.9      Wed Mar 17 18:55:14 2010 +0000
@@ -0,0 +1,349 @@
+.\"    $NetBSD: iic.9,v 1.6.2.2 2010/03/17 18:55:14 jruoho Exp $
+.\"    $OpenBSD: iic.9,v 1.3 2004/08/24 05:48:22 david 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 March 17, 2010
+.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
+.In 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 buflen"
+.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 a 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
+.Dv 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
+.Dv I2C_F_POLL
+flag was passed to
+.Fn iic_acquire_bus ,
+it must also be passed to
+.Fn iic_release_bus .
+.It Fn iic_exec "ic" "op" "addr" "cmdbuf" "cmdlen" "buf" "buflen" "flags"
+Perform 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 sent 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
+.Dv 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 buflen
+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 buflen
+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 buflen
+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
+.Dv 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
+.Dv 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
+.Dv I2C_F_READ
+flag indicates a read transfer; the lack of this flag indicates a
+write transfer.
+The
+.Dv 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
+.Dv 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.