sysfs class -> driver model -> tools (XR-101..XR-114)

Overview

This map runs the other direction from the libc map: it starts at a sysfs class the kernel publishes, names the subsystem core that creates it (with the config gate), explains the driver-model relationship (what registers the device, what the class directory inherits), lists the userspace consumers and how exactly they touch the class, and records the /dev and /proc cross-refs that duplicate or complement the view. The rows are XR-101..XR-114 of the coverage ledger (statuses authoritative there: 13 documented, 1 source-limited; the 7-d pass upgraded XR-102, XR-106, XR-107, XR-110, XR-111, XR-113 and XR-114).

Sources and honesty rules for this page: attribute contracts come from the kernel Documentation/ABI/ tree; tool behavior comes from the tools’ own documentation (util-linux man pages, systemd man pages, project READMEs) or source named per row; live observations are stamped live@5.10.134 (the container host this encyclopedia was built on; populations differ elsewhere and prove nothing about other kernels). Where a consumer claim could not be sourced, the row is source-limited and names the missing source instead of asserting. Class IDs cite the sysfs ledger; per-class pages under classes/ carry the full attribute tables.

How the rows were sourced

• Kernel contracts: the Documentation/ABI/ tree grepped per class for What: entries (counts quoted per row: block 76 + block-device 8, bdi 10, net 31 + queues 14 + statistics 24, tty 17, nvme 66, hwmon 119, thermal 27, power 59, backlight 5 core, led 5 core, pwm 11, regulator 33, drm 1, devlink 7, bus-dax 18, infiniband 130, devices-system-cpu 19, module 5, plus the obsolete gpio tree and sysfs-fs-xfs).
• Subsystem code: the class-registration and attribute blocks named per row (genhd.c, blk-sysfs.c, net-sysfs.c, tty_io.c, nvme/core.c, backing-dev.c, arch/x86/kernel/{msr,cpuid}.c, …), with config gates traced through Makefiles/Kconfig.
• Tools: the tool’s own documentation or source (util-linux man pages, systemd man pages, iproute2, nvme-cli/libnvme, ndctl, lm-sensors, brightnessctl, libgpiod, thermal daemon) – never assumed from the name; upstream tool documentation fetched for the 7-d pass (NetworkManager(8), thermald(8), the UPower reference manual, the libinput docs, drm(7)/libdrm man pages, rdma-core and ndctl READMEs, cpuid(1), msr(4), sysctl(8), dmidecode(8)).
• Live snapshot: live@5.10.134 class populations, attribute listings, topology symlinks, and uevent payloads, read read-only; nothing was written to /sys during research.

Reading rules

• wraps is not used here; the arrow vocabulary for tools is: reads (consumes attributes/uevents), writes (sets attributes or ATTR files), bypasses (uses netlink/ioctl/char-dev instead of sysfs), gated-by (config, boot param, or udev rule). Kernel-side arrows keep the encyclopedia vocabulary (services, implements, consumes).
• The /dev, /proc cross-refs column exists because sysfs is rarely the only view: most class devices have a char/block node (created from the uevent’s DEVNAME), a /proc twin with a different shape (/proc/partitions vs /sys/class/block), or a sibling class (vc for tty). Where the live host had the class but not the node, the row says so – that split is real on minimal/container systems, not a measurement error.
• Consumers are described by HOW, not by name-dropping: a tool that reads sysfs, one that writes an attribute, and one that bypasses via netlink or a char device are three different integration contracts, and the row records which one each tool uses, with the source named.
• Class populations quoted as “live N” are the 5.10.134 container host snapshot, not ABI promises.
• Non-1:1 is the point: udev is a consumer and a writer; several tools deliberately do not use sysfs (ip/ethtool use netlink, libgpiod uses the gpio char device); /proc and /dev twins exist for most rows.

XR-101 – /sys/class/block + bdi -> block core -> genhd/blk-sysfs -> lsblk, blockdev

ABI documentation: stable/sysfs-block (76 What: entries) plus testing/sysfs-block-device (8); testing/sysfs-class-bdi (10). Live interesting values: vda/queue/rotational=1 vs pmem0/rotational=0; scheduler reads [mq-deadline] kyber bfq none (the brackets are in the file bytes, tool output strips them). Two honest gaps from the live pass: the multipath-tools README documents its libudev-based walk of these directories (a second consumer reading via udev’s device database), and the bdi class’s six anonymous 0:N directories on this host could not be traced to a named registrant in the fetched sources – the class page states the gap instead of guessing. Topology is visible from this class too: on the live host vda linked to its virtio controller while pmem0 linked through an ndbus region to a different parent – which is how lsblk can show bus ancestry without any block-specific tooling. Per-class pages: block, bdi; kernel side: block devices.

XR-102 – /sys/class/net -> net core -> net-sysfs -> ip, ethtool, NetworkManager

The NetworkManager consumer claim upgraded in the 7-d pass: the fetched NetworkManager(8) (Debian trixie 1.52.1) states that the daemon manages “the primary network connection and other network interfaces, like Ethernet, Wi-Fi, and Mobile Broadband devices” and “will connect any network device when a connection for that device becomes available”, that “udev(7) device manager is used for the network device discovery”, and names the udev properties that steer management (NM_UNMANAGED, ID_NET_MANAGED_BY, ID_NET_AUTO_LINK_LOCAL_ONLY, ID_NET_DHCP_BROADCAST) plus the D-Bus export of network state. The page therefore documents NM’s integration at the udev/netlink/D-Bus layer and makes no direct-sysfs-read claim for it. ABI: testing/sysfs-class-net (31), -queues (14), -statistics (24). Live quirk: eth0/speed reads -1 and lo returns EINVAL for speed. The live pass also separated ABI-documented from live-only attributes: gro_flush_timeout, napi_defer_hard_irqs, proto_down and traffic_class exist in the source but predate their ABI entries, and threaded (5.12) is correctly absent on this 5.10 host. The statistics directory carried exactly the 24 ABI-named files. Pages: net; kernel side: netdev, netlink.

XR-103 – /sys/class/tty -> tty core -> tty_io -> stty, agetty, udev

ABI: testing/sysfs-tty (17 entries). Live serial facts: ttyS0/uartclk=1843200, type=4 (= PORT_16550A per include/uapi/linux/serial.h); console/active reads ttyS1 on this host while tty0/active reads tty1 – the attr names the current backend of that device. The interesting split: sysfs tty attributes are driver-provided metadata; line settings live in the termios interface that stty drives, and the serial-driver group (TIOCGSERIAL-family ioctls) is documented as a separate attr group. Note the devnode contract: the tty class is one of the few where the uevent MAJOR (4) maps to the classic /dev/ttyN naming without udev rules doing anything clever. The screen-content twin class SYSC-vc (vcs/vcsa/vcsu families, dev 7:0/7:64/7:128 live) is documented alongside because agetty-class tools and screenshot tools read it for the same ttys. Pages: tty; the libc/ioctl side of termios is mapped in XR-013 of the libc map.

XR-104 – /sys/class/nvme -> nvme host core -> nvme-cli, libnvme

ABI: stable/sysfs-nvme (66 What: entries, 39 class-level per the ledger). Honesty note: this host has no NVMe device, so no live attribute was verified – the entry is ABI + source only by design. Source detail worth keeping: the subsystem class (SYSC-nvme-subsystem, 6 attrs) hangs below the controller class with its own attribute set, and the fabrics-gated attributes are visibility-filtered per transport, so a tool scanning the class must handle absent attrs gracefully – which is exactly what libnvme’s filter code does. Pages: nvme, kernel side: nvme driver.

XR-105 – /sys/class/hwmon -> hwmon core -> sensors (lm-sensors)

ABI: testing/sysfs-class-hwmon (119 What: entries; a full-tree recount finds 120 including one driver-specific file – both figures are stated on the class page). The class being empty live on this container host is the config-vs-population gate in action: CONFIG_HWMON may be on, but no chip driver matched hardware. The attribute naming contract is the reason libsensors can be generic: every chip driver maps its readings onto the same inN_input / tempN_input / fanN_input shapes, so the tool needs no per-chip knowledge to list them. Page: hwmon.

XR-106 – /sys/class/thermal -> thermal core -> thermald

ABI: testing/sysfs-class-thermal (27 entries, no per-entry Date/KernelVersion lines – the ABI file is older-style, which is why the class page carries no since dates). The thermal story spans three sysfs views: this class (zones), the cooling-device directory /sys/class/thermal_cooling (outside the class ledger’s seeded rows), and the hwmon mirror some drivers register (XR-105); a tool that only reads one of them sees half the picture. Kernel side: thermal; class page: thermal. The thermald consumer claim upgraded in the 7-d pass: the fetched thermald(8) man page states the sysfs scan verbatim (the row’s former missing source was per-file usage evidence).

XR-107 – /sys/class/power_supply -> power supply core -> UPower

ABI: testing/sysfs-class-power (59 core What: entries; 82 documented paths ledger-wide including driver ABI files; the earliest per-entry KernelVersion lines date to 2.6.35). The class models everything with a charge state – batteries, AC adapters, UPSes – with type selecting which properties apply, which is what makes generic desktop consumers possible. The UPower consumer claim upgraded in the 7-d pass: the fetched reference manual gives the concrete class-to-daemon linkage (NativePath = the sysfs power_supply path, kernel-reported properties) and UPower(7) names the enumeration contract. Pages: power_supply.

XR-108 – /sys/class/leds + backlight -> leds/backlight cores -> brightnessctl, systemd-backlight

ABI: stable/sysfs-class-backlight (5 core attrs; 16 What: lines across the ABI tree vs the ledger’s 15 – both figures recorded on the class page) and testing/sysfs-class-led (5 core; 96 tree-wide including flash/multicolor/trigger files). This row is the cleanest write-path example: normal users change one attribute file and the kernel translates it into driver calls; the tool surface is deliberately thin (brightnessctl is a few hundred lines around read-scale-write). The systemd restore flow is the second write-path pattern worth knowing: state is persisted per device at shutdown and replayed by a udev rule when the device reappears, which works because the attribute exists from device registration on. Pages: leds, backlight.

XR-109 – /sys/class/{gpio,pwm,regulator,i2c-adapter} -> subsystem cores -> libgpiod, i2c-tools

This row is the map’s clearest bypass story: the tools moved to char devices while the class dirs remain for compatibility and for the i2c instantiate/remove convenience. The gpio ABI file itself says the sysfs interface was to be removed after 2020 (the chipX tree it documents lives in the obsolete/ directory), and the cdev ABI (testing/gpio-cdev, since 4.4) is what libgpiod’s README points at. Regulators remain a genuine sysfs write surface (constraints/state attrs), and pwm exposes per-channel export/enable/ duty-cycle attrs. Pages: gpio, pwm, regulator, i2c-adapter; kernel side: gpio, regulator, i2c/spi.

XR-110 – /sys/class/input -> input core -> libinput/evdev

ABI: no class-level ABI file (only driver-specific ones); claims above trace to named kernel sources. The capability tree is the interesting part: capabilities/ev-style bitmaps are what udev’s input_id builtin parses to set ID_INPUT_KEYBOARD/ID_INPUT_MOUSE-class properties, which downstream devices rules then match on – the sysfs files are the raw material for the event-device classification. The libinput consumer claim upgraded in the 7-d pass: the fetched libinput documentation (wayland.freedesktop.org, 1.31.0, device-configuration-via-udev) documents the udev-property contract verbatim, closing the row’s former gap. Page: input.

XR-111 – /sys/class/drm + graphics -> DRM core -> libdrm/compositors

ABI: testing/sysfs-class-drm (1 entry: boot_display). The live snapshot makes the split concrete: the drm class carried only its version attribute, while the fbdev layer under graphics carried the live framebuffer console (fbcon, with rotate, cursor_blink and write-only rotate_all). On machines with real GPUs the card/render device directories are where connector and client state lives, which is the part drm(7) now documents: the libdrm wrappers over the DRM character-device ioctls (7-d pass fetch; the gitlab.freedesktop.org repo itself stayed unreachable behind an anti-bot wall, so the Debian-shipped libdrm man pages are the citation). Pages: drm, graphics.

XR-112 – /sys/class/{msr,cpuid} -> x86 arch code -> msr-tools (source-limited)

No class ABI file exists for either class; all claims trace to the named arch sources. The safety story is unusually sharp here: msr writes can boot-loop or worse a machine, which is why the driver added the allow_writes parameter (on/off/default) gating writes on the char device – a layering where the class directory is inert and all the policy sits on the /dev side. Pages: msr, cpuid, mem/misc context. The 7-d fetch pass narrowed the gap without closing it: msr(4) and cpuid(1) are now cited above, but the msr-tools rdmsr/wrmsr documentation remains unfetched, so the tool-to-device linkage is still unasserted.

XR-113 – /sys/class/infiniband + devlink + dax -> RDMA/devlink/dax cores -> rdma, ndctl

Pages: infiniband, infiniband_verbs, devlink, nd; RDMA background: rdma. The rdma-core and ndctl halves upgraded in the 7-d pass: the official rdma-core README (github.com/linux-rdma/rdma-core) states the userspace-components claim and the uverbsX/rdma_cm/umadX node mapping, and the ndctl README (github.com/pmem/ndctl) states the libnvdimm-management scope; the umad and uverbs devnode details below keep their kernel-source attributions. Source details kept from the fetch pass: the umad class devices carry an abi_version attr and a infiniband/%s devnode; uverbs devnodes are mode 0666 (user-level verbs need access from unprivileged processes); and on the live host ndctl0 was a char device at 253:0 while /sys/dev/block/253:0 pointed at zram0 – the two /sys/dev namespaces are separate major spaces, verified live.

XR-114 – non-class trees (/sys/devices, /sys/bus, /sys/module, /sys/kernel, /sys/fs) -> sysctl, dmidecode

Pages: cpu-freq, cgroups-v2; procfs context: proc. What distinguishes this row from the class rows: there is no class directory to cite – consumers address paths under /sys/devices (per-CPU policy dirs), /sys/module (per-module parameters and sections), /sys/kernel (global attrs like the BTF blob) and /sys/fs (filesystem-specific trees, plus the cgroup2 mount). The ABI files mirror that structure: sysfs-devices-system-cpu (19), sysfs-module (5), sysfs-kernel-btf, sysfs-fs-xfs. The 7-d fetch pass sourced both remaining consumer claims: procps’ sysctl(8) is explicitly a /proc/sys tool (quote above), and dmidecode(8) reads the DMI table from sysfs first (/sys/firmware/dmi/tables/...) before /dev/mem.

Coverage and gaps

Key Takeaways

• The decisive question for any tool row is read, write, or bypass: lsblk and sensors read; brightnessctl and cpupower write; ip/ethtool, libgpiod, i2c-tools, nvme-cli (action side) and devlink all bypass sysfs via netlink/ioctl/char devices.
• udev appears on both sides of the interface: it consumes uevents and writes ATTR files (systemd-backlight restore), while human tools see the result.
• Class population is config- and hardware-gated: empty live dirs (hwmon, thermal, power_supply, leds, backlight, i2c-adapter, nvme) say nothing about the ABI contract, and missing /dev nodes (input, cpu, dri) on the build host are snapshots, not rules.
• The source-limited set is down to one row (XR-112): kernel-side contracts are documented everywhere, and the consumer documentation (NetworkManager, thermald, UPower, libinput, libdrm, rdma-core/ndctl, sysctl/dmidecode) was fetched upstream in the 7-d pass – only the msr-tools rdmsr/wrmsr docs remain unreachable, and XR-112 names its missing source.

Interview Questions

1. Does ip link set eth0 up write to /sys/class/net/eth0? No – ip(8) uses rtnetlink; sysfs netdev attributes are read-side observability (XR-102).
2. Why does libgpiod ignore /sys/class/gpio? The gpio sysfs ABI is obsolete (removed after 2020 per its own ABI file); the supported interface is the /dev/gpiochipN char device (XR-109).
3. What writes your backlight level at boot? systemd-backlight@.service, via a udev ATTR write of the saved brightness value (XR-108).

Cross-References

• Method and coverage – status vocabulary.
• Cross-layer maps overview and coverage ledger.
• Sysfs overview, sysfs ledger, sysfs internals, observing sysfs.
• udev – uevent consumption and ATTR writes.
• libc -> syscall -> kernel and feature matrix – sibling maps.