IIC(4) BSD Kernel Interfaces Manual IIC(4)
NAME
iic -- Inter IC (I2C) bus
SYNOPSIS
iic* at alipm? # sparc64
iic* at acpismbus? # amd64 i386
iic* at amdpm? # amd64 i386
iic* at armadillo9iic? # evbarm
iic0 at at91twi? # evbarm
iic0 at ausmbus0 # evbmips
iic0 at cuda0 # macppc
iic0 at gpiic? # evbppc
iic* at gpioiic? # amd64 i386
iic* at gtiic? # evbppc
iic* at gxiic? # evbarm
iic* at ichsmb? # amd64 i386
iic0 at iociic0 # acorn26
iic0 at iomdiic? # acorn32
iic0 at iopiic? # evbarm iyonix
iic* at ki2c? # macppc
iic* at nfsmb? # amd64 i386
iic* at ociic? # sandpoint
iic* at piixpm? # amd64 i386
iic0 at slugiic0 # evbarm
iic* at viapcib? # i386
DESCRIPTION
I2C is a two-wire bus developed by Philips used for connecting integrated circuits. It is commonly used for connecting devices such as EEP-
ROMs, temperature sensors, fan controllers, real-time clocks, tuners, and other types of integrated circuits.
The iic driver provides a uniform programming interface layer between I2C master controllers and various I2C slave devices. Each I2C master
controller attaches an iic framework; several slave devices can then be attached to the iic bus.
All I2C slave devices are uniquely identified by the address on the bus. The master accesses a particular slave device using its address.
System Management Bus (SMBus) protocol is also supported by emulating it with the I2C commands.
SUPPORTED MASTERS
A wide list of I2C masters are supported, among them are:
alipm(4) Acer Labs M7101 SMBus controller
acpismbus(4) ACPI SMBus Control Method Interface
amdpm(4) AMD768 Power Management Controller and AMD8111 System Management Controller
armadillo9iic(4)
at91twi(4)
ausmbus(4)
cuda(4) support for CUDA microcontrollers found in many Power Macintosh and and compatible computers
gpiic(4)
gtiic(4)
gxiic(4)
ichsmb(4) Intel ICH SMBus controller
iociic(4)
iomdiic(4)
iopiic(4)
ki2c(4)
gpioiic(4) GPIO bit-banging
nfsmb(4) NVIDIA nForce 2/3/4 SMBus controller and SMBus driver
ociic(4)
piixpm(4) Intel PIIX and compatible Power Management controller
slugiic(4)
viapcib(4)
SUPPORTED SLAVES
A wide list of slaves are supported, among them:
dbcool(4) dbCool(tm) family of environmental monitors and fan controllers
rs5c372rtc(4) RICOH RS5C372A and RS5C372B real-time clock
sgsmix(4) driver for SGS 7433 Basic Audio Processor found in some Apple machines
spdmem(4) Generic Memory Module Serial Presence Detect
SEE ALSO
dtviic(4), intro(4), i2cscan(8), iic(9)
HISTORY
The I2C framework first appeared in NetBSD 2.0. OpenBSD support was added in OpenBSD 3.6. This manpage first appeared in NetBSD 6.0, it was
ported from OpenBSD.
AUTHORS
The I2C framework was written by Steve C. Woodford and Jason R. Thorpe for NetBSD and then ported to OpenBSD by Alexander Yurchenko
<grange@openbsd.org>.
BSD
October 15, 2011 BSD
Check Out this Related Man Page
IIC(9) BSD Kernel Developer's Manual IIC(9)
NAME
iic_acquire_bus, iic_release_bus, iic_exec, iic_smbus_write_byte, iic_smbus_read_byte, iic_smbus_receive_byte -- Inter IC (I2C) bus
SYNOPSIS
#include <dev/i2c/i2cvar.h>
int
iic_acquire_bus(i2c_tag_t ic, int flags);
int
iic_release_bus(i2c_tag_t ic, int flags);
int
iic_exec(i2c_tag_t ic, i2c_op_t op, i2c_addr_t addr, const void *cmdbuf, size_t cmdlen, void *buf, size_t buflen, int flags);
int
iic_smbus_write_byte(i2c_tag_t ic, i2c_addr_t addr, uint8_t cmd, uint8_t data, int flags);
int
iic_smbus_read_byte(i2c_tag_t ic, i2c_addr_t addr, uint8_t cmd, uint8_t *datap, int flags);
int
iic_smbus_receive_byte(i2c_tag_t ic, i2c_addr_t addr, uint8_t *datap, int flags);
DESCRIPTION
I2C is a two-wire bus developed by Philips used for connecting integrated circuits. It is commonly used for connecting devices such as EEP-
ROMs, temperature sensors, fan controllers, real-time clocks, tuners, and other types of integrated circuits. The 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 com-
mand protocol and some electrical differences.
DATA TYPES
Drivers for devices attached to the I2C bus will make use of the following data types:
i2c_tag_t Controller tag for the I2C bus. This is a pointer to a struct i2c_controller, consisting of function pointers filled in by the
I2C controller driver.
i2c_op_t I2C bus operation. The following I2C bus operations are defined:
I2C_OP_READ
Perform a read operation.
I2C_OP_READ_WITH_STOP
Perform a read operation and send a STOP condition on the I2C bus at the conclusion of the read.
I2C_OP_WRITE
Perform a write operation.
I2C_OP_WRITE_WITH_STOP
Perform a write operation and send a STOP condition on the I2C bus at the conclusion of the write.
i2c_addr_t I2C device address.
struct i2c_attach_args
Devices are attached to an I2C bus using this structure. The structure is defined as follows:
struct i2c_attach_args {
i2c_tag_t ia_tag; /* controller */
i2c_addr_t ia_addr; /* address of device */
int ia_size; /* size (for EEPROMs) */
};
FUNCTIONS
The following functions comprise the API provided to drivers of I2C-connected devices:
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. Driv-
ers should acquire the bus lock, perform the I2C bus operations necessary, and then release the bus lock. Passing the I2C_F_POLL
flag indicates to iic_acquire_bus() that sleeping is not permitted.
iic_release_bus(ic, flags)
Release an exclusive lock on the I2C bus. If the I2C_F_POLL flag was passed to iic_acquire_bus(), it must also be passed to
iic_release_bus().
iic_exec(ic, op, addr, cmdbuf, cmdlen, buf, buflen, flags)
Perform a series of I2C transactions on the bus. 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 cmdlen is non-zero, the command pointed
to by cmdbuf is then sent to the device. If buflen is non-zero, iic_exec() will then transmit or receive the data, as indicated by
op. If op indicates a read operation, iic_exec() will send a REPEATED START before transferring the data. If op so indicates, a
STOP condition will be sent on the I2C bus at the conclusion of the operation. Passing the I2C_F_POLL flag indicates to iic_exec()
that sleeping is not permitted.
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 cmdlen of 1 and buflen of 1.
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 cmdlen of 1 and buflen of 1.
iic_smbus_receive_byte(ic, addr, datap, flags)
Perform an SMBus RECEIVE BYTE operation. This is equivalent to I2C_OP_READ_WITH_STOP with cmdlen of 0 and buflen of 1.
CONTROLLER INTERFACE
The I2C controller driver must fill in the function pointers of an i2c_controller structure, which is defined as follows:
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);
};
The (*ic_acquire_bus)() and (*ic_release_bus)() functions must always be provided.
The controller driver may elect to provide an (*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.
If the (*ic_exec)() function is not provided, the following 5 functions will be used by iic_exec() in order to execute the I2C bus operation:
(*ic_send_start)(cookie, flags)
Send a START condition on the I2C bus. The I2C_F_POLL flag indicates that sleeping is not permitted.
(*ic_send_stop)(cookie, flags)
Send a STOP condition on the I2C bus. The I2C_F_POLL flag indicates that sleeping is not permitted.
(*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
I2C_F_READ flag indicates a read transfer; the lack of this flag indicates a write transfer. The I2C_F_POLL flag indicates that sleep-
ing is not permitted. The error code ETIMEDOUT should be returned if a timeout that would indicate that the device is not present
occurs.
(*ic_read_byte)(cookie, datap, flags)
Read a byte from the I2C bus into the memory location referenced by datap. The 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 I2C_F_STOP flag indi-
cates that a STOP condition should be sent on the I2C bus following the transfer of the byte. The I2C_F_POLL flag indicates that
sleeping is not permitted.
(*ic_write_byte)(cookie, data, flags)
Write the byte contained in data to the I2C bus. The I2C_F_STOP flag indicates that a STOP condition should be sent on the I2C bus
following the transfer of the byte. The I2C_F_POLL flag indicates that sleeping is not permitted.
SEE ALSO
iic(4), i2cscan(8)
NXP Semiconductors, I2C-bus Specification and User Manual, Revision 03,
http://www.ics.nxp.com/support/documents/i2c/pdf/i2c.bus.specification.pdf, June 19, 2007.
Duracell Inc. et. al., System Management Bus (SMBus) Specification, Version 2.0, http://smbus.org/specs/smbus20.pdf, August 3, 2000.
HISTORY
The iic API first appeared in NetBSD 2.0. OpenBSD support was added in OpenBSD 3.6.
AUTHORS
The iic API was written by Steve C. Woodford and Jason R. Thorpe for NetBSD and then ported to OpenBSD by Alexander Yurchenko
<grange@openbsd.org>.
BSD
October 15, 2011 BSD