Source-Changes-HG archive
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]
[src/trunk]: src Manpage that explains the i2c framework... from OpenBSD.
details: https://anonhg.NetBSD.org/src/rev/579b21ed1e98
branches: trunk
changeset: 586881:579b21ed1e98
user: xtraeme <xtraeme%NetBSD.org@localhost>
date: Wed Jan 04 19:14:55 2006 +0000
description:
Manpage that explains the i2c framework... from OpenBSD.
diffstat:
distrib/sets/lists/comp/mi | 4 +-
share/man/man9/Makefile | 4 +-
share/man/man9/iic.9 | 337 +++++++++++++++++++++++++++++++++++++++++++++
3 files changed, 342 insertions(+), 3 deletions(-)
diffs (truncated from 384 to 300 lines):
diff -r 65b4af4cb499 -r 579b21ed1e98 distrib/sets/lists/comp/mi
--- a/distrib/sets/lists/comp/mi Wed Jan 04 19:13:48 2006 +0000
+++ b/distrib/sets/lists/comp/mi Wed Jan 04 19:14:55 2006 +0000
@@ -1,4 +1,4 @@
-# $NetBSD: mi,v 1.841 2006/01/03 12:49:36 yamt Exp $
+# $NetBSD: mi,v 1.842 2006/01/04 19:14:55 xtraeme Exp $
./etc/mtree/set.comp comp-sys-root
./usr/bin/addr2line comp-debug-bin bfd
./usr/bin/ar comp-util-bin bfd
@@ -5284,6 +5284,7 @@
./usr/share/man/cat9/ieee80211_rssadapt_lower_rate.0 comp-sys-catman .cat
./usr/share/man/cat9/ieee80211_rssadapt_raise_rate.0 comp-sys-catman .cat
./usr/share/man/cat9/ieee80211_rssadapt_updatestats.0 comp-sys-catman .cat
+./usr/share/man/cat9/iic.0 comp-sys-catman .cat
./usr/share/man/cat9/in4_cksum.0 comp-sys-catman .cat
./usr/share/man/cat9/in6_cksum.0 comp-sys-catman .cat
./usr/share/man/cat9/in_cksum.0 comp-sys-catman .cat
@@ -9217,6 +9218,7 @@
./usr/share/man/man9/ieee80211_rssadapt_lower_rate.9 comp-sys-man .man
./usr/share/man/man9/ieee80211_rssadapt_raise_rate.9 comp-sys-man .man
./usr/share/man/man9/ieee80211_rssadapt_updatestats.9 comp-sys-man .man
+./usr/share/man/man9/iic.9 comp-sys-man .man
./usr/share/man/man9/in4_cksum.9 comp-sys-man .man
./usr/share/man/man9/in6_cksum.9 comp-sys-man .man
./usr/share/man/man9/in_cksum.9 comp-sys-man .man
diff -r 65b4af4cb499 -r 579b21ed1e98 share/man/man9/Makefile
--- a/share/man/man9/Makefile Wed Jan 04 19:13:48 2006 +0000
+++ b/share/man/man9/Makefile Wed Jan 04 19:14:55 2006 +0000
@@ -1,4 +1,4 @@
-# $NetBSD: Makefile,v 1.186 2005/12/24 21:07:05 matt Exp $
+# $NetBSD: Makefile,v 1.187 2006/01/04 19:14:55 xtraeme Exp $
# Makefile for section 9 (kernel function and variable) manual pages.
@@ -19,7 +19,7 @@
hash.9 hardclock.9 humanize_number.9 hz.9 \
ieee80211.9 ieee80211_crypto.9 ieee80211_input.9 ieee80211_ioctl.9 \
ieee80211_node.9 ieee80211_output.9 ieee80211_proto.9 \
- ieee80211_radiotap.9 \
+ ieee80211_radiotap.9 iic.9 \
in4_cksum.9 inittodr.9 intro.9 ioasic.9 ioctl.9 ipkdb.9 isa.9 \
isapnp.9 itimerfix.9 kcopy.9 kcont.9 \
kfilter_register.9 knote.9 \
diff -r 65b4af4cb499 -r 579b21ed1e98 share/man/man9/iic.9
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/iic.9 Wed Jan 04 19:14:55 2006 +0000
@@ -0,0 +1,337 @@
+.\" $NetBSD: iic.9,v 1.1 2006/01/04 19:14:55 xtraeme 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 January, 2006
+.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 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
+.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 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
+.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
Home |
Main Index |
Thread Index |
Old Index