1.\" $NetBSD: iic.4,v 1.36 2024/11/04 21:02:01 brad Exp $ 2.\" $OpenBSD: iic.4,v 1.74 2008/09/10 16:13:43 reyk Exp $ 3.\" 4.\" Copyright (c) 2004, 2006 Alexander Yurchenko <grange@openbsd.org> 5.\" Copyright (c) 2009 Hubert Feyrer <hubertf@NetBSD.org> 6.\" 7.\" Permission to use, copy, modify, and distribute this software for any 8.\" purpose with or without fee is hereby granted, provided that the above 9.\" copyright notice and this permission notice appear in all copies. 10.\" 11.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 12.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 13.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 14.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 15.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 16.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 17.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 18.\" 19.Dd November 6, 2021 20.Dt IIC 4 21.Os 22.Sh NAME 23.Nm iic 24.Nd Inter IC (I2C) bus 25.Sh SYNOPSIS 26.\" 27.\" Use the following commands in (t)csh to output the list below (note 28.\" the first sed command includes a <space> and <tab> character in each 29.\" of the bracket expressions): 30.\" cd .../src/sys/arch 31.\" grep -h '^iic.*at' */conf/* | sort -u -k +3 | sed -e 's,[ ][ ]*, ,g' -e 's, *#.*,,' | sh -c 'while read iic at ic ; do printf ".Cd \"$iic $at %-20s # %s\"\n" "$ic" "`grep \"iic.*at.*$ic\" */conf/* | sed \"s,/.*,,\" | sort -u | tr \"\012\" \ `" ; done' | uniq | tee /tmp/x 32.\" cat /tmp/x 33.\" 34.Cd "iic* at alipm? # alpha amd64 i386 sparc64 " 35.Cd "iic* at amdpm? # amd64 i386 " 36.Cd "iic* at armadillo9iic? # evbarm " 37.Cd "iic0 at at91twi? # evbarm " 38.Cd "iic0 at ausmbus0 # evbmips " 39.Cd "iic* at awiniic? # evbarm " 40.Cd "iic* at bcmi2c? # evbarm " 41.Cd "iic* at coram? # amd64 i386 " 42.Cd "iic* at cuda? # macppc " 43.Cd "iic* at cxdtv? # amd64 i386 " 44.Cd "iic* at diic? # acorn32 evbppc " 45.Cd "iic* at dwiic? # amd64 i386 " 46.Cd "iic* at exyoi2c? # evbarm " 47.Cd "iic* at g2i2c? # evbarm " 48.Cd "iic0 at gpiic? # evbppc " 49.Cd "iic* at gpioiic? # amd64 i386 " 50.Cd "iic* at gttwsi? # evbarm evbppc " 51.Cd "iic* at gxiic? # evbarm " 52.Cd "iic* at i2cbus? # evbarm " 53.Cd "iic* at ichsmb? # amd64 i386 " 54.Cd "iic* at imcsmb? # amd64 i386 " 55.Cd "iic* at imxi2c? # evbarm " 56.Cd "iic0 at iomdiic? # acorn32 " 57.Cd "iic0 at iopiic? # evbarm iyonix " 58.Cd "iic* at ismt? # amd64 i386 " 59.Cd "iic* at jziic? # evbmips " 60.Cd "iic* at ki2c? # macppc " 61.Cd "iic* at nbpiic? # hpcarm " 62.Cd "iic* at nfsmb? # amd64 i386 " 63.Cd "iic* at ociic? # sandpoint " 64.Cd "iic* at omapiic? # evbarm " 65.Cd "iic* at pcfiic? # sparc64 " 66.Cd "iic* at piixpm? # amd64 i386 " 67.Cd "iic* at pmu? # macppc " 68.Cd "iic* at ri2c? # evbmips " 69.Cd "iic* at rtciic? # mmeye " 70.Cd "iic0 at slugiic0 # evbarm " 71.Cd "iic* at tegrai2c? # evbarm " 72.Cd "iic* at tiiic? # evbarm " 73.Cd "iic* at tsciic? # alpha " 74.Cd "iic* at viapcib? # i386 " 75.Cd "iic* at voyager0 # evbmips " 76.Cd "iic0 at ziic? # evbmips zaurus " 77.Sh DESCRIPTION 78I2C is a two-wire bus developed by Philips used for connecting 79integrated circuits. 80It is commonly used for connecting devices such as EEPROMs, 81temperature sensors, fan controllers, real-time clocks, tuners, 82and other types of integrated circuits. 83.Pp 84The 85.Nm 86driver provides a uniform programming interface layer between I2C 87master controllers and various I2C slave devices. 88Each I2C master controller attaches an 89.Nm 90framework; several slave devices can then be attached to the 91.Nm 92bus. 93.Pp 94All I2C slave devices are uniquely identified by the address on the bus. 95The master accesses a particular slave device using its address. 96.\" Devices are found on the bus using a sophisticated scanning routine 97.\" which attempts to identify commonly available devices. 98.\" On other machines (such as sparc64 and macppc) where the machine ROM 99.\" supplies a list of I2C devices, that list is used instead. 100.Pp 101System Management Bus (SMBus) protocol is also supported by emulating 102it with the I2C commands. 103.Sh IOCTLS 104The following 105.Xr ioctl 2 106calls apply to 107.Em IIC 108devices. 109They are defined in the header file 110.In dev/i2c/i2c_io.h : 111.Bl -tag -width indent 112.It Dv I2C_IOCTL_EXEC (i2c_ioctl_exec_t) 113User ioctl to execute an i2c operation. 114.Bd -literal 115typedef enum { 116 I2C_OP_READ, 117 I2C_OP_READ_WITH_STOP, 118 I2C_OP_WRITE, 119 I2C_OP_WRITE_WITH_STOP, 120 I2C_OP_READ_BLOCK, 121 I2C_OP_WRITE_BLOCK 122} i2c_op_t; 123 124typedef struct i2c_ioctl_exec { 125 i2c_op_t iie_op; /* operation to perform */ 126 i2c_addr_t iie_addr; /* address of device */ 127 const void *iie_cmd; /* pointer to command */ 128 size_t iie_cmdlen; /* length of command */ 129 void *iie_buf; /* pointer to data buffer */ 130 size_t iie_buflen; /* length of data buffer */ 131} i2c_ioctl_exec_t; 132.Ed 133.El 134.Sh SUPPORTED MASTERS 135A wide list of I2C masters are supported, among them are: 136.Pp 137.\" 138.\" Generate the following list with these (t)csh commands: 139.\" cd .../src/sys/arch 140.\" grep -h '^iic.*at' */conf/* | awk '{print $3}' | sed 's,.$,,' | sort -u | sh -c 'while read i ; do echo .It Xr $i 4; n=`grep -h ^.Nd ../../share/man/man4/$i* | sed "s,^.Nd ,,"`; if [ -n "$n" ]; then echo $n ; else echo "" ; fi ; done' | tee /tmp/x 141.\" cat /tmp/x 142.\" 143.Bl -tag -width 18n -compact -offset indent 144.It Xr acpismbus 4 145ACPI SMBus Control Method Interface 146.It Xr alipm 4 147Acer Labs M7101 SMBus controller 148.It Xr amdpm 4 149AMD768 Power Management Controller and AMD8111 System Management Controller 150.It Xr coram 4 151Digital video driver for Conexant CX23885 based cards 152.It Xr cuda 4 153Support for CUDA microcontrollers found in many Power Macintosh and 154compatible computers 155.It Xr cxdtv 4 156Digital video driver for Conexant CX2388x based cards 157.It Xr gpioiic 4 158GPIO I2C controller 159.It Xr ichsmb 4 160Intel Chipset internal SMBus controller 161.It Xr ismt 4 162Intel Chipset internal SMBus 2.0 controller with DMA 163.It Xr nfsmb 4 164NVIDIA nForce 2/3/4 SMBus controller and SMBus driver 165.It Xr piixpm 4 166Intel PIIX and compatible Power Management controller 167.El 168.Sh SUPPORTED SLAVES 169A wide list of slaves are supported, among them: 170.Pp 171.\" 172.\" Create the following list with these commands: 173.\" cd .../src/sys/arch 174.\" grep -h '.* at iic.*' */conf/* | sed -e 's,^#,,' -e 's, .*,,' -e 's,.$,,' | sort -u | sh -c 'while read i ; do echo .It Xr $i 4 ; n=`grep ^.Nd ../../share/man/man4/$i* | sed "s,^.Nd ,,"` ; if [ -n "$n" ]; then echo $n ; else echo "" ; fi ; done' | tee /tmp/x 175.\" cat /tmp/x 176.\" 177.Bl -tag -width 13n -compact -offset indent 178.It Xr adm1026hm 4 179Analog Devices ADM1026 complete thermal system management controller 180.It Xr admtemp 4 181Analog Devices ADM1021 temperature sensor 182.It Xr aht20temp 4 183Aosong AHT20 humidity/temperature sensors 184.It Xr am2315temp 4 185Aosong AM2315 humidity/temperature sensors 186.It Xr bmx280thp 4 187Bosch BMP280/BME280 humidity/temperature/pressure sensors 188.It Xr ddc 4 189VESA Display Data Channel V2 devices 190.It Xr dbcool 4 191dbCool(tm) family of environmental monitors and fan controllers 192.It Xr ds2482ow 4 193Maxim DS2482-100 and DS2482-800 I2C to 1-Wire bridge 194.It Xr g760a 4 195Global Mixed-mode Technology Inc. G760a fan speed controller 196.It Xr hythygtemp 4 197IST-AG HYT-221/271/939 humidity/temperature sensors 198.It Xr ibmhawk 4 199Temperature, voltage, and fan sensors present on IBM eServers 200.It Xr ims 4 201I2C mice and touch panels 202.It Xr lm 4 203National Semiconductor LM78, LM79, and compatible hardware monitors 204.It Xr lmenv 4 205National Semiconductor LM81, LM87, and compatible hardware monitors 206.It Xr lmtemp 4 207National Semiconductor LM75, LM77, and compatible hardware monitors 208.It Xr mcp980x 4 209Microchip 9800/1/2/3 I2C temperature sensor 210.It Xr mpl115a 4 211Freescale MPL115A2 absolute pressure sensor 212.It Xr pcf8563rtc 4 213NXP PCF8563 real-time clock 214.It Xr rs5c372rtc 4 215RICOH RS5C372A and RS5C372B real-time clock 216.It Xr s390rtc 4 217Seiko Instruments S-35390 real-time clock 218.It Xr scmdi2c 4 219I2C frontend for the Sparkfun Serial Controlled Motor Driver. 220.It Xr sdtemp 4 221JEDEC JC-42.4 compatible memory module temperature sensors 222.It Xr seeprom 4 22324-series I2C EEPROM driver 224.It Xr sgp40mox 4 225Sensirion SGP40 MOx gas sensors 226.It Xr sgsmix 4 227SGS 7433 Basic Audio Processor found in some Apple machines 228.It Xr sht3xtemp 4 229Sensirion SHT30/SHT31/SHT35 temperature/humidity sensors 230.It Xr sht4xtemp 4 231Sensirion SHT40/SHT41/SHT45 temperature/humidity sensors 232.It Xr si70xxtemp 4 233Silicon Labs SI7013/SI7020/SI7021 humidity/temperature sensors 234.It Xr smscmon 4 235Standard Microsystems Corporation LPC47M192 and LPC47M997 sensors 236.It Xr spdmem 4 237Generic Memory Module Serial Presence Detect 238.It Xr ssdfb 4 239OLED/PLED framebuffer modules 240.It Xr tea5767radio 4 241Philips/NXP TEA5767 FM stereo radio 242.It Xr tps65217pmic 4 243Texas Instruments TPS65217 Power Management IC 244.It Xr tsllux 4 245Taos TSL256x Light-to-Digital Converter 246.El 247.Sh FILES 248.Bl -tag -width "/dev/iicu" -compact 249.It /dev/iic Ns Ar u 250I2C device unit 251.Ar u 252file. 253.El 254.Sh SEE ALSO 255.Xr dtviic 4 , 256.Xr intro 4 , 257.Xr i2cscan 8 , 258.Xr iic 9 259.Sh HISTORY 260The I2C framework first appeared in 261.Nx 2.0 . 262.Ox 263support was added in 264.Ox 3.6 . 265This manpage first appeared in 266.Nx 6.0 , 267it was ported from 268.Ox . 269.Sh AUTHORS 270.An -nosplit 271The I2C framework was written by 272.An Steve C. Woodford 273and 274.An Jason R. Thorpe 275for 276.Nx 277and then ported to 278.Ox 279by 280.An Alexander Yurchenko Aq Mt grange@openbsd.org . 281