IIC(9)

📦
version 11.0 · 2 versions
, in nixpkgs unstable

💅 IIC(9) — the Inter IC (I2C) bus, explained by your favorite kernel gremlin 🎀

okay bestie, sit down, grab a strawberry 🍓 — this is IIC(9), from the Kernel Developer's Manual, and it's literally the group chat between your kernel and every tiny chip on the board. no cap, it's iconic.

✨ 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, aka the six functions you'll be vibing with 💖

🌸 SYNOPSIS 🌸

#include <dev/i2c/i2cvar.h>

int
iic_acquire_bus(i2c_tag_t ic, int flags);

void
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);

like, just look at those signatures. gorgeous. no notes. 🫶

🦋 DESCRIPTION 🦋

so I2C is a two-wire bus developed by Philips, used for connecting integrated circuits, and honestly? it ate. it's the main character of board-level comms.

it's commonly used for connecting devices such as EEPROMs, temperature sensors, fan controllers, real-time clocks, tuners, and other types of integrated circuits. every single one of those is lowkey doing the most on just two little wires.

the iic interface provides a means of communicating with I2C-connected devices. that's the whole vibe check: you talk, the chip talks back, everybody's happy ✨

and then there's the System Management Bus, or SMBus — a variant of the I2C bus with a simplified command protocol and some electrical differences. same energy, slightly different outfit 💅

🌈 DATA TYPES 🌈

Drivers for devices attached to the I2C bus will make use of the following data types — learn them, love them, they're your new besties:

  • 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. so it's like the controller's contact card 📇
  • 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. read it and yeet the STOP, basically 🛑
    • 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. that's the chip's @, iykyk.
  • 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. this is the good stuff, bestie, pay attention 🔥

  • 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 — it's giving "one mic, one voice" 🎤. Drivers 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. no naps allowed 😴❌
  • 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(). symmetric behavior, periodt.
  • iic_exec(ic, op, addr, cmdbuf, cmdlen, buf, buflen, flags) — Perform a series of I2C transactions on the bus. so here's the choreography, bestie:
    • 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. one byte in, one byte out, slay 💅
  • 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. zero command bytes, still iconic.

👑 CONTROLLER INTERFACE 👑

now for the other side of the relationship, the controller driver's side 🫶. 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. mandatory. non-negotiable. the bare minimum 💀

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. fancy automated controllers get to skip the micromanagement ✨

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. go go go 🚦
  • (*ic_send_stop)(cookie, flags) — Send a STOP condition on the I2C bus. The I2C_F_POLL flag indicates that sleeping is not permitted. that's a wrap, bestie 🛑
  • (*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 sleeping is not permitted. The error code ETIMEDOUT should be returned if a timeout that would indicate that the device is not present occurs. so if nobody answers... it's giving ghosted 👻
  • (*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 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.
  • (*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 🧚

like, go read the specs, they're long but they're the moment 📚✨

⭐ HISTORY ⭐

The iic API first appeared in NetBSD 2.0. OpenBSD support was added in OpenBSD 3.6. a glow-up across two operating systems, we love to see it 🌈

💖 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>. legends, all three of them 👑👑👑

De bian — October 15, 2011 — that's the source/version and date on this one, so shoutout to the Debian manpage packaging era, mwah 💋 this page has been a whole vibe, hope I2C makes sense now, love u bye 🎀✨

📦 where this page comes from