diff options
Diffstat (limited to 'static/openbsd/man9/iic.9')
| -rw-r--r-- | static/openbsd/man9/iic.9 | 360 |
1 files changed, 360 insertions, 0 deletions
diff --git a/static/openbsd/man9/iic.9 b/static/openbsd/man9/iic.9 new file mode 100644 index 00000000..ce3bb006 --- /dev/null +++ b/static/openbsd/man9/iic.9 @@ -0,0 +1,360 @@ +.\" $OpenBSD: iic.9,v 1.10 2022/02/09 07:58:24 visa 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 $Mdocdate: February 9 2022 $ +.Dt IIC_ACQUIRE_BUS 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 , +.Nm iic_is_compatible +.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 +.Ft int +.Fo iic_is_compatible +.Fa "const struct i2c_attach_args *ia" +.Fa "const char *name" +.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) */ + char *ia_name; /* chip name */ + size_t ia_namelen /* length of name concatenation */ + void *ia_cookie; /* pass extra info from + bus to dev */ + void *ia_intr /* interrupt info */ + int ia_poll; /* to force polling */ +}; +.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 . +.It Xo +.Fo iic_exec +.Fa "ic" +.Fa "op" +.Fa "addr" +.Fa "cmdbuf" +.Fa "cmdlen" +.Fa "buf" +.Fa "len" +.Fa "flags" +.Fc +.Xc +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. +.It Fn iic_is_compatible "ia" "name" +Test if the device is compatible with +.Fa name . +.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 Mt grange@openbsd.org . |