Drivers & buses

Polled hardware, one vtable per bus.

Most NebOS drivers are polled rather than interrupt-driven: storage, USB and every NIC are serviced from process context. That trades latency and CPU time for simple, single-owner state and a kernel that stays easy to reason about on old hardware.

PCI enumeration FDC · PATA · SATA UHCI · OHCI · EHCI · xHCI PS/2 · USB · I2C touchpad

Driver inventory

Every driver in the tree is small enough to read in one sitting. The table below is the quickest way to find the one responsible for a device.

SubsystemDriverBus / accessService model
Floppydisk.cISA FDC + DMA channel 2IRQ 6; FAT operations set sys_fs_busy
PATAata.cLegacy ports or PCI native BARsPolled PIO, DRQ wait per sector
SATAahci.cPCI AHCI MMIOPolled, READ/WRITE DMA EXT
eMMCsdhci.cIntel Braswell SDHCI, PCI 00:10.0 (8086:2294)Polled PIO, 1-bit/25 MHz; no DMA/IRQ
USBusb.c + uhci.c ohci.c ehci.c xhci.cPCI I/O ports or MMIOPolled; hotplug watcher in the WM loop
Networke1000e.c r8168.c ne2000.c asix.c rndis.cPCI or USBPolled, one active receiver; r8168 covers the RTL8111E/8168 family (970A-DS3P) as well as the AT3IONT-I's RTL8112L.
WiFiiwl_trans.c iwl_mvm.c iwl_dvm.c wifi.cPCIe, Intel 7265D/3165 (8086:095a/095b/3165/3166) and 6200/6300 (8086:4239/422c, 4238/422b)Polled RX ring; firmware from /ramfs/firmware, loaded on first use
USB WiFirtl8821au.c wifi.cUSB 2.0 high speed, Realtek RTL8821AU/8811AU (TP-Link Archer T2U Nano 2357:011f and the other Linux rtw88_8821au IDs)Vendor control requests for registers, one bulk-IN/one bulk-OUT endpoint; firmware + register tables from /ramfs/firmware
Panel backlightbacklight.cIntel Braswell/Cherryview graphics MMIO, PCI 00:02.0 (8086:22b0/22b1)Polled register writes; F6/F7 and E0 14/E0 15 step 10%; SYS_BACKLIGHT drives the control-panel slider
PS/2mouse.c, io.ci8042IRQ 1 keyboard, IRQ 12 mouse; polling fallback
Touchpadi2c.c, touchpad.c, touchpad_gesture.cLPSS DesignWare I2C, slave 0x15Polled input register every 25 ms; software tap and two-finger scroll gestures; no GPIO interrupt driver
Serialserial.c16550 UART, COM1IRQ 4 ring buffer + polled transmitter
Thermalthermal.cIntel DTS MSRSampled once a second from the scheduler tick
Board sensors / ECit87.c, tpec.c, ec.c, cros_ec.cSuper I/O, ThinkPad H8 EC, Chrome OS EC (temps, fans, battery, AC, switches)Polled; EC battery-index/FIFO/page-selector writes only
Wall clockrtc.cCMOS RTC ports 0x70/0x71Read/write under the BKL; update-cycle retries and a 1970–2069 two-digit year window

PCI & discovery

pci.c walks bus/device/function and exposes BAR and capability access. The USB scan checks all functions: real PIIX3/PIIX4/VIA layouts put the USB function at 0:07.2 or 0:01.2, not 0:07.0. Controllers with unassigned BARs are ignored rather than driven at address zero.

MMIO regions are mapped through ioremap(), which returns a kernel address in the shared window at 0xC0000000 (see Memory → Paging); drivers keep the physical BAR only for logging. PCI interrupts are disabled before touching MMIO, so every driver polls its own status registers. lspci lists every function; with a filter it prints BAR type, size and address details.

Storage

blkdev.c is a small registry of block devices. Each device exposes sector read/write plus geometry; FAT, the format command and the installer sit above that interface and never talk to a controller directly. Devices are named floppy0, ide0, sata0, mmc0, usb0 and so on; partitions append p1, p2.

Storage software layers The VFS, format and install tools use a block-device registry, which dispatches to the floppy, ATA PIO, AHCI, SDHCI or USB mass-storage driver, then to the physical disk. VFS · FAT · format · install files, or a whole-image clone blkdev registry sector read / write + geometry driver FDC · ATA · AHCI · SDHCI · USB floppy.img CHS + ISA DMA ide0 / ide0pN PIO, legacy or native BARs sata0 · mmc0 · usb0 AHCI · SDHCI · USB MSC
One narrow waist. Filesystems and tools only see struct blk_dev. The floppy still needs IRQ 6, but ATA, AHCI, SDHCI and USB MSC are polled; a FAT operation takes a non-preemptible section and format_busy keeps a destructive format/install exclusive. The installer clones the MBR and every used sector of the source image.

Floppy

disk.c drives the 8272-compatible FDC through ISA DMA channel 2, with the single-sector DMA buffer at 0x4000. Retries handle the usual real-hardware flakiness. The second floppy slot can hold root.img.

PATA

ata.c uses the legacy command block or the PCI IDE interface's native BARs. Multi-sector PIO waits for DRQ before every sector because drives drop it between sectors; it polls the command-block status rather than the alternate-status BAR, and falls back to single-sector commands when a bridge leaves DRQ pending.

SATA/AHCI

ahci.c drives the first AHCI controller only, with no IRQs and no NCQ. It does COMRESET, IDENTIFY through the shared ata_identify_parse(), and READ/WRITE DMA EXT through a page-allocated bounce buffer. A disk added after boot needs a rescan; there is no COMRESET hotplug.

eMMC/SDHCI

sdhci.c drives the Intel Braswell MMC function at PCI 00:10.0 (8086:2294, class 0805), the HP Chromebook's eMMC. It resets the SDHCI host, selects the 1.8 V rail and Host Control 2's 1.8 V signalling, runs a 400 kHz initialization clock, then CMD0/1/2/3/7/16 and CMD8 to read EXT_CSD (SEC_COUNT at 212, CACHE_SIZE at 249), and switches to a 25 MHz data clock. Sector I/O is CMD17/CMD24 through the polled PIO buffer port at 1-bit/25 MHz; there is no DMA, IRQ, bus-width/high-speed switch or hotplug. The read/write loops yield every 32 sectors so a long format does not starve the window manager. The eMMC appears as mmc0, and format mmc0 writes an MBR + FAT partition exactly like an IDE/SATA disk. The write path flushes the card cache with CMD6 FLUSH_CACHE when EXT_CSD reports one.

USB stack

usb.c is controller-agnostic. It handles enumeration, descriptor parsing, hub recursion, bus scans, per-controller addresses, the hotplug watcher and interrupt-IN consumers. Each host controller implements the usb_hcd_ops vtable in usb_hcd.h.

USB controller topology EHCI handles high-speed root ports, UHCI and OHCI handle low and full speed devices, xHCI handles USB2 and USB3 root ports. All feed the same USB core, which drives HID input and USB mass storage. EHCI high-speed root ports UHCI full/low speed · 1 instance OHCI full/low speed · up to 4 xHCI USB2 + USB3 root ports usb core enumeration · hubs · hotplug · interrupt-IN slots usbhid · keyboard + mouse usbmsc · mass storage
Companions are not optional. EHCI is scanned first so its port resets can hand non-high-speed devices back to a companion: a K line state before the reset, or no port-enable after it (whatever the line state reads), means the device is not high-speed. There is no transaction translator: a low/full-speed device behind a high-speed hub is invisible to EHCI.
ControllerTransportInstancesImplementation notes
UHCIPCI I/O ports1Frame list at 0x3000; control QH plus one QH per interrupt slot.
OHCIPCI MMIOup to 4HCCA from the page allocator, static ED/TD sets in the uncacheable ohci_dma_page, TDs start at CC = NotAccessed. Before reset it requests SMM ownership (HcCommandStatus.OCR, clear HcControl.IR) and disables the AMD southbridge USB SMI on 1002:4385.
EHCIPCI MMIOup to 4Async QH/qTD schedule, page-allocated descriptors, polling only, no periodic list.
xHCIPCI MMIO—USB2 and USB3 root ports; direct SuperSpeed devices use a 512-byte EP0 and the port speed in the slot context (USB3 hubs are not decoded). Halts and waits for HCH around HCRST; EP0 max packet is the speed's fixed value (8/64/512), and a full-speed EP0 is corrected with Evaluate Context after the first descriptor read (the VIA VL805 on the 970A-DS3P babbled on a high-speed stick otherwise); a SuperSpeed port is not PED-disabled before its reset; failed control transfers are always logged with their completion code; EP0 stages are encoded as one TD per stage (EDK2 style) because chained control TDs stall on Braswell.

AMD SB600/SB700/SB800/SB950 firmware can leave the OHCI controllers owned by the SMM and keep the southbridge USB SMI enabled. The driver requests ownership and clears the SMI enable before scanning (ohci.c), so USB2 ports on the 970A-DS3P's SB950 work after the firmware handoff. The SB950's legacy OHCI DMA does not snoop dirty CPU cache lines, so the EDs, TDs, setup packet and interrupt buffers live in one page that paging_init maps uncacheable (PDE 0 is split before paging is enabled). Without it the controller occasionally read an empty ED, skipped the transfer and never re-armed the interrupt endpoint; the cursor froze with no error. Control transfers still flush their write-back data buffers around the transfer.

Enumeration starts every device on the USB default 8-byte EP0 and adopts the descriptor's real bMaxPacketSize0 afterwards. A failed port attempt is retried three times with a fresh port reset and a 20 ms settle, and OHCI gets a second boot pass 60 ms after the EHCI-first walk so a companion handback cannot leave a low-speed device unseen. HID detach is debounced (three consecutive disconnected reads, 50 TD errors) and a detach forces a clean full rescan, because a false port-loss leaves no connect-change bit to wake the per-port path.

Hubs are class-9 devices: usb.c sets their configuration, powers every downstream port (honouring bPwrOn2PwrGood), resets and waits for PORT_ENABLE, then enumerates recursively. This is what makes the X201's internal PCH hubs work. Hotplug watches root ports; a device behind a hub is only found when a full scan runs (lsusb also bumps the USB generation so usbhid re-attaches). A scan and every mass-storage command claim the controllers for the calling process (usb_bus_claim()/usb_bus_release(), nesting). Every HCD delay and the ASIX/RNDIS/usbmsc probe delays go through usb_delay_ms(), and every HCD completion and port-reset poll loop calls usb_poll_relax(t0) outside its spinlock. When the claim belongs to a sleepable scan (lsusb, the kworker's HID rescan/hotplug, or the storage rescan reading a USB disk), the delay sleeps and the poll yields once a wait passes 2 ms, both dropping the BKL, so port resets, NAKing devices and settle times no longer freeze the WM; everywhere else they busy-wait as before. The poll yields instead of sleeping because a 1 ms sleep on an idle CPU wakes on the 100 Hz idle tick. While another context owns the bus, the usb.c wrappers refuse controller access (usb_scan_foreign(): control and bulk transfers fail, interrupt polls return no data, ports read as connected), usb_hotplug_poll skips its pass and usbhid_poll skips its tick. A USB NIC, the RTL8821AU or a USB disk therefore sees a transient error during a bus scan; the scan re-enumerates those devices anyway.

Mass storage

usbmsc.c is a device-level probe alongside the ASIX Ethernet driver. It claims an interface with class 8, subclass 6 and protocol 0x50, parses its bulk IN/OUT endpoints and identifies the disk with SCSI INQUIRY + READ CAPACITY. Commands use Bulk-Only Transport with LUN 0 and 512-byte blocks: READ(10), WRITE(10), SYNCHRONIZE CACHE and a BOT reset/endpoint-halt recovery. Short bulk-IN chunks are accumulated within a BOT data stage; a failed READ(10) gets REQUEST SENSE, retries and a 1-sector fallback. Present devices are registered as usb0.. (BLK_USB) by blk_scan(), so storage, the VFS, format and install can use them.

Bulk transfers exist on EHCI and xHCI only; a mass-storage device on a UHCI/OHCI companion is left unclaimed. The xHCI driver drives direct USB3 root-port devices (USB3 hubs are not decoded), so a SuperSpeed stick on the Chromebook works. This is what makes the installer's usb0 source possible: it reads the whole live image into RAM first and then writes the target, so slow eMMC writes cannot leave the USB source idle between chunks.

USB tethering

rndis.c is another device-level probe. It scans every configuration for an RNDIS control function (02/02/FF, E0/01/03 or an EF variant) and a data interface with bulk endpoints, selects that configuration, then sends RNDIS INIT/QUERY/packet-filter messages over the control interface. Ethernet frames travel in 44-byte RNDIS packet headers on the bulk pair, so the existing IPv4 stack sees a normal netdev named rndis. This is Android USB tethering, not WiFi; QEMU's full-speed usb-net device is the test target (make run-rndis). CDC-ECM/NCM and the RNDIS interrupt notification endpoint are not implemented.

WiFi (Intel 7265D/3165, 6200/6300, RTL8821AU)

Two Intel generations share one PCIe transport. The HP Chromebook's Wireless-AC 7265 rev D or 3165 runs the newer MVM firmware (iwl_mvm.c); the ThinkPad X201's Centrino Advanced-N 6200 (or Ultimate-N 6300) runs the older DVM firmware (iwl_dvm.c). A Realtek RTL8821AU USB stick is the third backend (rtl8821au.c, below). wifi_fw.c picks the backend when the radio comes up — a plugged-in stick wins over the built-in card, otherwise the PCI probe decides — so wifi.c and the wifi command are the same for all three. Everything is polled; every ring and buffer is page-allocated so nothing big lands in the kernel BSS.

WiFi software layers The ring-3 wifi command runs the WPA2 handshake and talks to wifi.c through SYS_WIFI; the network stack uses wifi.c as a normal netdev. wifi.c uses iwl_mvm.c for firmware commands, which uses the iwl_trans.c PCIe transport to reach the card. wifi command + wpa.c (ring 3) scan · PBKDF2 · 4-way / group handshake net stack DHCP · DNS · TCP via struct netdev wifi.c — 802.11 station + the wifi netdev auth/assoc · 802.11 ↔ Ethernet (LLC/SNAP, CCMP header) · EAPOL queue · SYS_WIFI iwl_mvm.c (7265D) · iwl_dvm.c (6200/6300) · rtl8821au.c (USB) — via wifi_fw.c iwl_trans.c (PCIe rings, firmware DMA) · usb.c bulk + vendor control (RTL8821AU)
Keys stay in ring 3 until installed. The supplicant derives the PTK and unwraps the GTK; the kernel only moves EAPOL frames and hands the TK/GTK to the firmware, which does CCMP. Sources: ucmd_wifi.c, wpa.c, wifi.c, wifi_fw.c, iwl_mvm.c, rtl8821au.c, iwl_dvm.c, iwl_trans.c.

6200/6300: the DVM firmware

The transport differences live in one per-family descriptor (fam_7000/fam_6000 in iwl_trans.c):

Parameter7265D/3165 (MVM)6200/6300 (DVM)
Firmwareiwlwifi-7265D-29.ucode (TLV)iwlwifi-6000-4.ucode (v2 header: inst/data sections at 0x0/0x800000)
Scheduler queues3120
Command queue / FIFO0 / 74 / 7
Data queuesaux 1, BSS 4 (configured by firmware, SCD_QUEUE_CFG)VO 0 (management), VI 1, BE 2 (data), BK 3 (configured by the transport)
Command header8-byte wide (group 1)4-byte
Byte-count tabledwordsbytes
MAC addressNVM via NVM_ACCESS_CMDOTP read by the host through CSR_EEPROM_REG

RTL8821AU USB stick

rtl8821au.c ports the Linux rtw88 8821A/USB bring-up (rtw88xxa_power_on() and the helpers it calls) and implements the same entry points as the Intel layers. Registers are USB vendor requests (bRequest 5, wValue = address, 1/2/4 bytes); the 8051 firmware is written in 196-byte requests to 0x1000 page by page. The USB probe only matches the VID/PID, parses the bulk endpoints and sets the configuration; the chip is powered on by the first wifi command, which takes a few seconds of control transfers.

StepWhatLinux source
eFuseCard-enable power sequence, 512-byte physical map → logical map; MAC at 0x107, crystal cap, BB swing, RFE (external LNA/PA) flags, TX power basesrtw_parse_efuse_map, rtw88xxa_read_efuse
MACPower sequence, LLT (256 pages, boundary 248), firmware download + FW_READY, MAC table, page reservation, queue map, EDCA/beacon/USB burst setuprtw88xxa_power_on, __rtw_download_firmware_legacy
PHYBB + AGC tables, crystal cap, RF-A table, 2.4 GHz band switch; the tables' if/elif/else branches use the 8821A cut/RFE rulesrtw_parse_tbl_phy_cond, rtw88xxa_switch_band
ChannelBand switch (RFE pin mux, CCK on/off, basic rates), RF 0x18 channel/band, 20 MHz bandwidth, TX AGC from the eFuse base indexrtw88xxa_set_channel

Input

usbhid.c gives every HID class-3 interface with an interrupt-IN endpoint one of the six USB interrupt slots. Boot interfaces (subclass 1, protocol 1/2) are used as-is; other class-3 interfaces are classified by reading their HID report descriptor. Composite receivers and several devices can coexist; mouse reports from all slots are merged.

mouseinfo shows the active backend and whether a USB keyboard is attached. Headless regression tests inject mouse motion and keys through QMP and verify the result with screen dumps.

I2C touchpad

The HP Chromebook 11 G5 EE has no PS/2 port: its Elan touchpad is a HID-over-I2C device on LPSS I2C6. The LPSS I2C functions are hidden from PCI in ACPI mode, so touchpad.c scans the two firmware BAR windows for a DesignWare component (only on an Airmont CPU, family 6 model 0x4C: elsewhere the scan would reset-cycle 32 fixed MMIO windows for ~64 ms of boot) and i2c.c drives that controller in fast mode, polled and without interrupts.

Serial

serial.c drives the 16550 at COM1, 115200 8N1, with an IRQ-driven receive ring buffer. It is used for the boot trace, the netlog mirror source, the dbg monitor and the KXE2 kexec receiver.

The transmitter is polled, so a machine without a serial port still boots normally. serial_puthex and serial_putdec are the structured dump helpers used by drivers.

Sensors, power & thermals

sensors prints supported CPU temperatures (and the Intel 90/100/125 °C delta scales when there is no published TjMax), board sensors and both EC types; powerinfo prints the source (thinkpad or chrome ec), the AC adapter, battery model/manufacturer/serial, capacities, voltage, rate and cycle count through SYS_POWER_INFO; power prints ratios, effective MHz and C-state hints. The WM top bar shows the CPU temperature and, on both ThinkPads and Chromebooks, a status icon at the far right for the first present battery: a plug while the AC adapter is online and a level-filled battery on battery. Machines without an EC show neither.

Wall clock (RTC)

rtc.c talks to the MC146818-compatible CMOS clock through ports 0x70/0x71. Reads honour the register-B BCD/binary and 12/24-hour modes, retry when the update-in-progress bit is set, and decode the hour's PM flag. The RTC only stores a two-digit year, so the kernel expands it over a 1970–2069 window (70–99 → 1900s, 00–69 → 2000s); a board whose dead battery left 1980 or 1990 therefore reads correctly instead of being pushed a century forward. Writes validate the calendar (leap years included), raise the register-B SET bit, preserve the mode bits and write the computed weekday. On ACPI machines the FADT century register (offset 108, normally CMOS 0x32) is written as well, so the firmware and other operating systems see the intended century; boards without ACPI get no arbitrary NVRAM write.

SYS_RTC_GET/SYS_RTC_SET (104/105) expose the full struct sys_datetime; the older SYS_RTC_HMS/SYS_RTC_DATETIME calls remain the small read-only views. The WM’s top-bar date/time opens the control panel, whose Date & Time tile reveals an inline editor; its Sync NTP button fetches UTC through SYS_NTP_SYNC (106), backed by the SNTP client in ntp.c, and writes it with SYS_RTC_SET. The date command prints the same clock in the classic Linux format.

Panic screen

On a ring-0 fault, panic.c draws straight into the framebuffer — bypassing the shadow buffer and the WM — and mirrors the same data to COM1 before halting. The banner includes the vector and error code, GPRs, control registers, current pid/name, uptime, instruction bytes and stack return-address candidates in the kernel image.

Faults from ring 3 do not halt: the process is killed with a short message in its terminal and serial log. There is no interactive debugger on screen; the dbg kernel command drives a serial monitor instead.

Limits

Source map