IICBUS(4)

📦 version 15.1, in freebsd 14.5, freebsd 15.1, nixpkgs unstable

💅 IICBUS(4) — the iicbus manual, bestie edition ✨

okay so this is the iicbus(4) page from the Kernel Interfaces Manual and honestly it's kind of a whole vibe — it's the I2C bus system, and by the end of this you're gonna know her intimately. no cap. 🫶

✨ NAME ✨

iicbus — the I2C bus system, aka the loml 💖

🌸 SYNOPSIS 🌸

device iicbus
device iicbb

device iic
device ic
device iicsmb

like, that's the whole lineup. main characters only. 👑

🦋 DESCRIPTION 🦋

okay so the iicbus system is literally the blueprint. it provides a uniform, modular, and architecture-independent system for the implementation of drivers that control various I2C devices and utilize different I2C controllers. it's giving "glow-up through structure." ✨

🎀 I2C 🎀

so I2C is an acronym for Inter Integrated Circuit bus. the I2C bus was developed in the early 1980's by Philips semiconductors, and her whole purpose at birth was "provide an easy way to connect a CPU to peripheral chips in a TV-set." humble beginnings, iconic trajectory. 💅

the BUS physically consists of 2 active wires and a ground connection. the active wires are SDA and SCL, and both of them are bidirectional. where SDA is the Serial DAta line and SCL is the Serial CLock line. yes bestie, the naming is that literal, it ate. 🍓

every single component hooked up to the bus has its own unique address — whether it's a CPU, an LCD driver, a memory, or a complex function chip. each of these chips can act as a receiver and/or transmitter depending on its functionality. obviously an LCD driver is only a receiver, while a memory or I/O chip can be both transmitter and receiver. and like, furthermore? there may be one or more BUS MASTERs. multi-tasking queens. 👑

the BUS MASTER is the chip issuing the commands on the BUS. in the I2C protocol specification it is stated that the IC that initiates a data transfer on the bus is considered the BUS MASTER — and at that time all the others are regarded as the BUS SLAVEs. as mentioned before, the IC bus is a Multi-MASTER BUS, which means more than one IC capable of initiating data transfer can be connected to it. no gatekeeping here. 🌈

💜 DEVICES 💜

some I2C device drivers are available, and here's the roster:

  • iic — general i/o operation (the chill generalist, lowkey everywhere)
  • ic — network IP interface
  • iicsmb — I2C to SMB software bridge (she connects worlds, a diplomat fr fr)

🌟 INTERFACES 🌟

the I2C protocol may be implemented by hardware or software. software interfaces rely on very simple hardware — usually two lines twiddled by 2 registers. hardware interfaces are more intelligent and receive 8-bit characters they write to the bus according to the I2C protocol. both valid, both serving. ✨

I2C interfaces may also act on the bus as slave devices, allowing spontaneous bidirectional communications, thanks to the multi-master capabilities of the I2C protocol. it's giving "i can do both, actually." 💅

some I2C interfaces are available:

  • pcf — Philips PCF8584 master/slave interface (the overachiever, does both)
  • iicbb — generic bit-banging master-only driver (master-only, knows her lane)
  • lpbb — parallel port specific bit-banging interface (niche but iconic)

🔥 BUS FREQUENCY CONFIGURATION 🔥

the operating frequency of an I2C bus may be fixed or configurable. the bus may be used as part of some larger standard interface, and that interface specification may require a fixed frequency — in which case the driver for that hardware would not honor an attempt to configure a different speed. so like, don't try it. she said no. 💀

a general purpose I2C bus, such as those found in many embedded systems, will often support multiple bus frequencies. versatile queen behavior.

when a system supports multiple I2C buses, a different frequency can be configured for each bus by number, represented by the %d in the variable names below. buses can be configured using any combination of device hints, Flattened Device Tree (FDT) data, tunables set via loader(8), or at runtime using sysctl(8). and here's the priority tea: when configuration is supplied using more than one method, FDT and hint data will be overridden by a tunable, which can be overridden by sysctl(8). hierarchy is real. 👑

🎀 Device Hints 🎀

set hint.iicbus.%d.frequency to the frequency in Hz, on systems that use device hints to configure I2C devices. the hint is also honored by systems that use FDT data if no frequency is configured using FDT. she's the fallback bestie. 🫶

🦋 Flattened Device Tree Data 🦋

configure the I2C bus speed using the FDT standard clock-frequency property of the node describing the I2C controller hardware. standard, clean, FDT-approved. ✨

💖 Sysctl and Tunable 💖

set dev.iicbus.%d.frequency in loader.conf(5). the same variable can be changed at any time with sysctl(8). and listen — reset the bus using i2c(8) or the iic(4) I2CRSTCARD ioctl to make the change take effect. don't skip this step, i'm begging. 🙈

👀 SEE ALSO 👀

(the whole friend group, go say hi) 💜

⭐ HISTORY ⭐

the iicbus manual page first appeared in FreeBSD 3.0. vintage, but make it timeless. 🎀

🌸 AUTHORS 🌸

this manual page was written by Nicolas Souchu. legend behavior, we stan. 🫶

and that's the page bestie!! this was the IICBUS(4) manpage, from the Kernel Interfaces Manual, dated March 7, 2021, Debian source/version line and all — go forth and twiddle those two lines with confidence. mwah 💋 periodt.

📦 where this page comes from