336 lines
9.1 KiB
Groff
336 lines
9.1 KiB
Groff
.\" $NetBSD: iic.9,v 1.3 2007/02/02 07:37:06 wiz 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 12, 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
|
|
.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 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
|
|
.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" "len" "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 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
|
|
.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.
|
|
The
|
|
.Dv I2C_F_STOP
|
|
flag indicates that a STOP condition should be sent on the I2C bus following
|
|
the transfer of the byte.
|
|
The
|
|
.Dv 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
|
|
.Dv I2C_F_STOP
|
|
flag indicates that a STOP condition should be sent on the I2C bus following
|
|
the transfer of the byte.
|
|
The
|
|
.Dv 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 .
|