1.\" $NetBSD: iic.4,v 1.38 2025/01/23 19:26:29 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 ds28e17iic? # 1-Wire " 46.Cd "iic* at dwiic? # amd64 i386 " 47.Cd "iic* at exyoi2c? # evbarm " 48.Cd "iic* at g2i2c? # evbarm " 49.Cd "iic0 at gpiic? # evbppc " 50.Cd "iic* at gpioiic? # amd64 i386 " 51.Cd "iic* at gttwsi? # evbarm evbppc " 52.Cd "iic* at gxiic? # evbarm " 53.Cd "iic* at i2cbus? # evbarm " 54.Cd "iic* at ichsmb? # amd64 i386 " 55.Cd "iic* at imcsmb? # amd64 i386 " 56.Cd "iic* at imxi2c? # evbarm " 57.Cd "iic0 at iomdiic? # acorn32 " 58.Cd "iic0 at iopiic? # evbarm iyonix " 59.Cd "iic* at ismt? # amd64 i386 " 60.Cd "iic* at jziic? # evbmips " 61.Cd "iic* at ki2c? # macppc " 62.Cd "iic* at nbpiic? # hpcarm " 63.Cd "iic* at nfsmb? # amd64 i386 " 64.Cd "iic* at ociic? # sandpoint " 65.Cd "iic* at omapiic? # evbarm " 66.Cd "iic* at pcfiic? # sparc64 " 67.Cd "iic* at piixpm? # amd64 i386 " 68.Cd "iic* at pmu? # macppc " 69.Cd "iic* at ri2c? # evbmips " 70.Cd "iic* at rtciic? # mmeye " 71.Cd "iic0 at slugiic0 # evbarm " 72.Cd "iic* at tegrai2c? # evbarm " 73.Cd "iic* at tiiic? # evbarm " 74.Cd "iic* at tsciic? # alpha " 75.Cd "iic* at umcpmio? # USB " 76.Cd "iic* at viapcib? # i386 " 77.Cd "iic* at voyager0 # evbmips " 78.Cd "iic0 at ziic? # evbmips zaurus " 79.Sh DESCRIPTION 80I2C is a two-wire bus developed by Philips used for connecting 81integrated circuits. 82It is commonly used for connecting devices such as EEPROMs, 83temperature sensors, fan controllers, real-time clocks, tuners, 84and other types of integrated circuits. 85.Pp 86The 87.Nm 88driver provides a uniform programming interface layer between I2C 89master controllers and various I2C slave devices. 90Each I2C master controller attaches an 91.Nm 92framework; several slave devices can then be attached to the 93.Nm 94bus. 95.Pp 96All I2C slave devices are uniquely identified by the address on the bus. 97The master accesses a particular slave device using its address. 98.\" Devices are found on the bus using a sophisticated scanning routine 99.\" which attempts to identify commonly available devices. 100.\" On other machines (such as sparc64 and macppc) where the machine ROM 101.\" supplies a list of I2C devices, that list is used instead. 102.Pp 103System Management Bus (SMBus) protocol is also supported by emulating 104it with the I2C commands. 105.Sh IOCTLS 106The following 107.Xr ioctl 2 108calls apply to 109.Em IIC 110devices. 111They are defined in the header file 112.In dev/i2c/i2c_io.h : 113.Bl -tag -width indent 114.It Dv I2C_IOCTL_EXEC (i2c_ioctl_exec_t) 115User ioctl to execute an i2c operation. 116.Bd -literal 117typedef enum { 118 I2C_OP_READ, 119 I2C_OP_READ_WITH_STOP, 120 I2C_OP_WRITE, 121 I2C_OP_WRITE_WITH_STOP, 122 I2C_OP_READ_BLOCK, 123 I2C_OP_WRITE_BLOCK 124} i2c_op_t; 125 126typedef struct i2c_ioctl_exec { 127 i2c_op_t iie_op; /* operation to perform */ 128 i2c_addr_t iie_addr; /* address of device */ 129 const void *iie_cmd; /* pointer to command */ 130 size_t iie_cmdlen; /* length of command */ 131 void *iie_buf; /* pointer to data buffer */ 132 size_t iie_buflen; /* length of data buffer */ 133} i2c_ioctl_exec_t; 134.Ed 135.El 136.Sh SUPPORTED MASTERS 137A wide list of I2C masters are supported, among them are: 138.Pp 139.\" 140.\" Generate the following list with these (t)csh commands: 141.\" cd .../src/sys/arch 142.\" 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 143.\" cat /tmp/x 144.\" 145.Bl -tag -width 18n -compact -offset indent 146.It Xr acpismbus 4 147ACPI SMBus Control Method Interface 148.It Xr alipm 4 149Acer Labs M7101 SMBus controller 150.It Xr amdpm 4 151AMD768 Power Management Controller and AMD8111 System Management Controller 152.It Xr coram 4 153Digital video driver for Conexant CX23885 based cards 154.It Xr cuda 4 155Support for CUDA microcontrollers found in many Power Macintosh and 156compatible computers 157.It Xr cxdtv 4 158Digital video driver for Conexant CX2388x based cards 159.It Xr ds28e17iic 4 1601-Wire to I2C bridge 161.It Xr gpioiic 4 162GPIO I2C controller 163.It Xr ichsmb 4 164Intel Chipset internal SMBus controller 165.It Xr ismt 4 166Intel Chipset internal SMBus 2.0 controller with DMA 167.It Xr nfsmb 4 168NVIDIA nForce 2/3/4 SMBus controller and SMBus driver 169.It Xr piixpm 4 170Intel PIIX and compatible Power Management controller 171.It Xr umcpmio 4 172MCP-2221 / 2221A USB multi-io chip 173.El 174.Sh SUPPORTED SLAVES 175A wide list of slaves are supported, among them: 176.Pp 177.\" 178.\" Create the following list with these commands: 179.\" cd .../src/sys/arch 180.\" 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 181.\" cat /tmp/x 182.\" 183.Bl -tag -width 13n -compact -offset indent 184.It Xr adm1026hm 4 185Analog Devices ADM1026 complete thermal system management controller 186.It Xr admtemp 4 187Analog Devices ADM1021 temperature sensor 188.It Xr aht20temp 4 189Aosong AHT20 humidity/temperature sensors 190.It Xr am2315temp 4 191Aosong AM2315 humidity/temperature sensors 192.It Xr bmx280thp 4 193Bosch BMP280/BME280 humidity/temperature/pressure sensors 194.It Xr ddc 4 195VESA Display Data Channel V2 devices 196.It Xr dbcool 4 197dbCool(tm) family of environmental monitors and fan controllers 198.It Xr ds2482ow 4 199Maxim DS2482-100 and DS2482-800 I2C to 1-Wire bridge 200.It Xr g760a 4 201Global Mixed-mode Technology Inc. G760a fan speed controller 202.It Xr hythygtemp 4 203IST-AG HYT-221/271/939 humidity/temperature sensors 204.It Xr ibmhawk 4 205Temperature, voltage, and fan sensors present on IBM eServers 206.It Xr ims 4 207I2C mice and touch panels 208.It Xr lm 4 209National Semiconductor LM78, LM79, and compatible hardware monitors 210.It Xr lmenv 4 211National Semiconductor LM81, LM87, and compatible hardware monitors 212.It Xr lmtemp 4 213National Semiconductor LM75, LM77, and compatible hardware monitors 214.It Xr mcp980x 4 215Microchip 9800/1/2/3 I2C temperature sensor 216.It Xr mpl115a 4 217Freescale MPL115A2 absolute pressure sensor 218.It Xr pcf8563rtc 4 219NXP PCF8563 real-time clock 220.It Xr rs5c372rtc 4 221RICOH RS5C372A and RS5C372B real-time clock 222.It Xr s390rtc 4 223Seiko Instruments S-35390 real-time clock 224.It Xr scmdi2c 4 225I2C frontend for the Sparkfun Serial Controlled Motor Driver. 226.It Xr sdtemp 4 227JEDEC JC-42.4 compatible memory module temperature sensors 228.It Xr seeprom 4 22924-series I2C EEPROM driver 230.It Xr sgp40mox 4 231Sensirion SGP40 MOx gas sensors 232.It Xr sgsmix 4 233SGS 7433 Basic Audio Processor found in some Apple machines 234.It Xr sht3xtemp 4 235Sensirion SHT30/SHT31/SHT35 temperature/humidity sensors 236.It Xr sht4xtemp 4 237Sensirion SHT40/SHT41/SHT45 temperature/humidity sensors 238.It Xr si70xxtemp 4 239Silicon Labs SI7013/SI7020/SI7021 humidity/temperature sensors 240.It Xr smscmon 4 241Standard Microsystems Corporation LPC47M192 and LPC47M997 sensors 242.It Xr spdmem 4 243Generic Memory Module Serial Presence Detect 244.It Xr ssdfb 4 245OLED/PLED framebuffer modules 246.It Xr tea5767radio 4 247Philips/NXP TEA5767 FM stereo radio 248.It Xr tps65217pmic 4 249Texas Instruments TPS65217 Power Management IC 250.It Xr tsllux 4 251Taos TSL256x Light-to-Digital Converter 252.El 253.Sh FILES 254.Bl -tag -width "/dev/iicu" -compact 255.It /dev/iic Ns Ar u 256I2C device unit 257.Ar u 258file. 259.El 260.Sh SEE ALSO 261.Xr dtviic 4 , 262.Xr intro 4 , 263.Xr i2cscan 8 , 264.Xr iic 9 265.Sh HISTORY 266The I2C framework first appeared in 267.Nx 2.0 . 268.Ox 269support was added in 270.Ox 3.6 . 271This manpage first appeared in 272.Nx 6.0 , 273it was ported from 274.Ox . 275.Sh AUTHORS 276.An -nosplit 277The I2C framework was written by 278.An Steve C. Woodford 279and 280.An Jason R. Thorpe 281for 282.Nx 283and then ported to 284.Ox 285by 286.An Alexander Yurchenko Aq Mt grange@openbsd.org . 287