drivers.html 52 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757
  1. <!doctype html>
  2. <html lang="en">
  3. <head>
  4. <meta charset="utf-8">
  5. <meta name="viewport" content="width=device-width, initial-scale=1">
  6. <title>Drivers &amp; Buses | NebOS Architecture</title>
  7. <meta name="description" content="NebOS drivers: PCI enumeration, floppy/ATA/AHCI storage, the USB core with UHCI, OHCI, EHCI and xHCI, HID input, USB mass storage, serial, board sensors and the panic path.">
  8. <link rel="icon" href="favicon.svg" type="image/svg+xml">
  9. <link rel="stylesheet" href="style.css">
  10. </head>
  11. <body>
  12. <a class="skip" href="#main">Skip to content</a>
  13. <header class="site-header">
  14. <a class="brand" href="index.html">
  15. <span class="brand-mark" aria-hidden="true"></span>
  16. <span>NebOS <span class="brand-sub">Architecture</span></span>
  17. </a>
  18. <nav class="site-nav" aria-label="Architecture sections">
  19. <a href="index.html">Overview</a>
  20. <a href="boot.html">Boot</a>
  21. <a href="memory.html">Memory</a>
  22. <a href="cpu.html">CPU</a>
  23. <a href="drivers.html" aria-current="page">Drivers</a>
  24. <a href="filesystems.html">Filesystems</a>
  25. <a href="graphics.html">Graphics</a>
  26. <a href="network.html">Network</a>
  27. <a href="userland.html">Userland</a>
  28. <a href="development.html">Development</a>
  29. </nav>
  30. </header>
  31. <main id="main" class="page">
  32. <div class="page-head">
  33. <p class="kicker">Drivers &amp; buses</p>
  34. <h1>Polled hardware, one vtable per bus.</h1>
  35. <p class="lede">
  36. Most NebOS drivers are polled rather than interrupt-driven: storage,
  37. USB and every NIC are serviced from process context. That trades
  38. latency and CPU time for simple, single-owner state and a kernel that
  39. stays easy to reason about on old hardware.
  40. </p>
  41. <div class="meta">
  42. <span class="pill">PCI enumeration</span>
  43. <span class="pill">FDC · PATA · SATA</span>
  44. <span class="pill">UHCI · OHCI · EHCI · xHCI</span>
  45. <span class="pill">PS/2 · USB · I2C touchpad</span>
  46. </div>
  47. </div>
  48. <nav class="toc" aria-label="On this page">
  49. <h2>On this page</h2>
  50. <ul>
  51. <li><a href="#inventory">Driver inventory</a></li>
  52. <li><a href="#pci">PCI &amp; discovery</a></li>
  53. <li><a href="#storage">Storage</a></li>
  54. <li><a href="#usb">USB stack</a></li>
  55. <li><a href="#wifi">WiFi (Intel 7265D/3165, 6200/6300, RTL8821AU)</a></li>
  56. <li><a href="#hid">Input</a></li>
  57. <li><a href="#serial">Serial</a></li>
  58. <li><a href="#sensors">Sensors &amp; power</a></li>
  59. <li><a href="#rtc">Wall clock (RTC)</a></li>
  60. <li><a href="#panic">Panic screen</a></li>
  61. <li><a href="#limits">Limits</a></li>
  62. <li><a href="#sources">Source map</a></li>
  63. </ul>
  64. </nav>
  65. <section id="inventory">
  66. <h2>Driver inventory</h2>
  67. <p>
  68. Every driver in the tree is small enough to read in one sitting. The
  69. table below is the quickest way to find the one responsible for a
  70. device.
  71. </p>
  72. <div class="table-wrap">
  73. <table>
  74. <thead>
  75. <tr><th>Subsystem</th><th>Driver</th><th>Bus / access</th><th>Service model</th></tr>
  76. </thead>
  77. <tbody>
  78. <tr><td>Floppy</td><td><span class="file">disk.c</span></td><td>ISA FDC + DMA channel 2</td><td>IRQ 6; FAT operations set <code>sys_fs_busy</code></td></tr>
  79. <tr><td>PATA</td><td><span class="file">ata.c</span></td><td>Legacy ports or PCI native BARs</td><td>Polled PIO, DRQ wait per sector</td></tr>
  80. <tr><td>SATA</td><td><span class="file">ahci.c</span></td><td>PCI AHCI MMIO</td><td>Polled, READ/WRITE DMA EXT</td></tr>
  81. <tr><td>eMMC</td><td><span class="file">sdhci.c</span></td><td>Intel Braswell SDHCI, PCI <code>00:10.0</code> (<code>8086:2294</code>)</td><td>Polled PIO, 1-bit/25 MHz; no DMA/IRQ</td></tr>
  82. <tr><td>USB</td><td><span class="file">usb.c</span> + <span class="file">uhci.c</span> <span class="file">ohci.c</span> <span class="file">ehci.c</span> <span class="file">xhci.c</span></td><td>PCI I/O ports or MMIO</td><td>Polled; hotplug watcher in the WM loop</td></tr>
  83. <tr><td>Network</td><td><span class="file">e1000e.c</span> <span class="file">r8168.c</span> <span class="file">ne2000.c</span> <span class="file">asix.c</span> <span class="file">rndis.c</span></td><td>PCI or USB</td><td>Polled, one active receiver; <code>r8168</code> covers the RTL8111E/8168 family (970A-DS3P) as well as the AT3IONT-I's RTL8112L.</td></tr>
  84. <tr><td>WiFi</td><td><span class="file">iwl_trans.c</span> <span class="file">iwl_mvm.c</span> <span class="file">iwl_dvm.c</span> <span class="file">wifi.c</span></td><td>PCIe, Intel 7265D/3165 (<code>8086:095a/095b/3165/3166</code>) and 6200/6300 (<code>8086:4239/422c</code>, <code>4238/422b</code>)</td><td>Polled RX ring; firmware from <code>/ramfs/firmware</code>, loaded on first use</td></tr>
  85. <tr><td>USB WiFi</td><td><span class="file">rtl8821au.c</span> <span class="file">wifi.c</span></td><td>USB 2.0 high speed, Realtek RTL8821AU/8811AU (TP-Link Archer T2U Nano <code>2357:011f</code> and the other Linux <code>rtw88_8821au</code> IDs)</td><td>Vendor control requests for registers, one bulk-IN/one bulk-OUT endpoint; firmware + register tables from <code>/ramfs/firmware</code></td></tr>
  86. <tr><td>Panel backlight</td><td><span class="file">backlight.c</span></td><td>Intel Braswell/Cherryview graphics MMIO, PCI <code>00:02.0</code> (<code>8086:22b0/22b1</code>)</td><td>Polled register writes; F6/F7 and <code>E0 14</code>/<code>E0 15</code> step 10%; <code>SYS_BACKLIGHT</code> drives the control-panel slider</td></tr>
  87. <tr><td>PS/2</td><td><span class="file">mouse.c</span>, <span class="file">io.c</span></td><td>i8042</td><td>IRQ 1 keyboard, IRQ 12 mouse; polling fallback</td></tr>
  88. <tr><td>Touchpad</td><td><span class="file">i2c.c</span>, <span class="file">touchpad.c</span>, <span class="file">touchpad_gesture.c</span></td><td>LPSS DesignWare I2C, slave <code>0x15</code></td><td>Polled input register every 25 ms; software tap and two-finger scroll gestures; no GPIO interrupt driver</td></tr>
  89. <tr><td>Serial</td><td><span class="file">serial.c</span></td><td>16550 UART, COM1</td><td>IRQ 4 ring buffer + polled transmitter</td></tr>
  90. <tr><td>Thermal</td><td><span class="file">thermal.c</span></td><td>Intel DTS MSR</td><td>Sampled once a second from the scheduler tick</td></tr>
  91. <tr><td>Board sensors / EC</td><td><span class="file">it87.c</span>, <span class="file">tpec.c</span>, <span class="file">ec.c</span>, <span class="file">cros_ec.c</span></td><td>Super I/O, ThinkPad H8 EC, Chrome OS EC (temps, fans, battery, AC, switches)</td><td>Polled; EC battery-index/FIFO/page-selector writes only</td></tr>
  92. <tr><td>Wall clock</td><td><span class="file">rtc.c</span></td><td>CMOS RTC ports <code>0x70/0x71</code></td><td>Read/write under the BKL; update-cycle retries and a 1970–2069 two-digit year window</td></tr>
  93. </tbody>
  94. </table>
  95. </div>
  96. </section>
  97. <section id="pci">
  98. <h2>PCI &amp; discovery</h2>
  99. <p>
  100. <span class="file">pci.c</span> walks bus/device/function and exposes
  101. BAR and capability access. The USB scan checks all functions: real
  102. PIIX3/PIIX4/VIA layouts put the USB function at 0:07.2 or 0:01.2, not
  103. 0:07.0. Controllers with unassigned BARs are ignored rather than
  104. driven at address zero.
  105. </p>
  106. <p>
  107. MMIO regions are mapped through <code>ioremap()</code>, which returns
  108. a kernel address in the shared window at <code>0xC0000000</code>
  109. (see <a href="memory.html#paging">Memory → Paging</a>); drivers keep
  110. the physical BAR only for logging. PCI
  111. interrupts are disabled before touching MMIO, so every driver polls
  112. its own status registers. <code>lspci</code> lists every function;
  113. with a filter it prints BAR type, size and address details.
  114. </p>
  115. </section>
  116. <section id="storage">
  117. <h2>Storage</h2>
  118. <p>
  119. <span class="file">blkdev.c</span> is a small registry of block
  120. devices. Each device exposes sector read/write plus geometry; FAT,
  121. the format command and the installer sit above that interface and
  122. never talk to a controller directly. Devices are named
  123. <code>floppy0</code>, <code>ide0</code>, <code>sata0</code>,
  124. <code>mmc0</code>, <code>usb0</code> and so on; partitions append
  125. <code>p1</code>, <code>p2</code>.
  126. </p>
  127. <figure class="figure">
  128. <svg viewBox="0 0 920 246" role="img" aria-labelledby="storage-title storage-desc">
  129. <title id="storage-title">Storage software layers</title>
  130. <desc id="storage-desc">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.</desc>
  131. <rect class="svg-box blue" x="40" y="30" width="230" height="62" rx="9"/>
  132. <text class="svg-text" x="60" y="57">VFS · FAT · format · install</text>
  133. <text class="svg-sub" x="60" y="77">files, or a whole-image clone</text>
  134. <rect class="svg-box accent" x="345" y="30" width="230" height="62" rx="9"/>
  135. <text class="svg-text" x="365" y="57">blkdev registry</text>
  136. <text class="svg-sub" x="365" y="77">sector read / write + geometry</text>
  137. <rect class="svg-box" x="650" y="30" width="230" height="62" rx="9"/>
  138. <text class="svg-text" x="670" y="57">driver</text>
  139. <text class="svg-sub" x="670" y="77">FDC · ATA · AHCI · SDHCI · USB</text>
  140. <path class="svg-line blue" d="M270 61h67"/>
  141. <path class="svg-line blue" d="M330 55l7 6-7 6"/>
  142. <path class="svg-line accent" d="M575 61h67"/>
  143. <path class="svg-line accent" d="M635 55l7 6-7 6"/>
  144. <rect class="svg-box green" x="40" y="142" width="230" height="62" rx="9"/>
  145. <text class="svg-text" x="60" y="169">floppy.img</text>
  146. <text class="svg-sub" x="60" y="189">CHS + ISA DMA</text>
  147. <rect class="svg-box green" x="345" y="142" width="230" height="62" rx="9"/>
  148. <text class="svg-text" x="365" y="169">ide0 / ide0pN</text>
  149. <text class="svg-sub" x="365" y="189">PIO, legacy or native BARs</text>
  150. <rect class="svg-box green" x="650" y="142" width="230" height="62" rx="9"/>
  151. <text class="svg-text" x="670" y="169">sata0 · mmc0 · usb0</text>
  152. <text class="svg-sub" x="670" y="189">AHCI · SDHCI · USB MSC</text>
  153. <path class="svg-line" d="M175 92v42"/>
  154. <path class="svg-line" d="M169 126l6 7 6-7"/>
  155. <path class="svg-line" d="M460 92v42"/>
  156. <path class="svg-line" d="M454 126l6 7 6-7"/>
  157. <path class="svg-line" d="M765 92v42"/>
  158. <path class="svg-line" d="M759 126l6 7 6-7"/>
  159. </svg>
  160. <figcaption>
  161. <strong>One narrow waist.</strong> Filesystems and tools only see
  162. <code>struct blk_dev</code>. The floppy still needs IRQ 6, but ATA,
  163. AHCI, SDHCI and USB MSC are polled; a FAT operation takes a
  164. non-preemptible section and <code>format_busy</code> keeps a
  165. destructive format/install exclusive. The installer clones the
  166. MBR and every used sector of the source image.
  167. </figcaption>
  168. </figure>
  169. <h3>Floppy</h3>
  170. <p>
  171. <span class="file">disk.c</span> drives the 8272-compatible FDC
  172. through ISA DMA channel 2, with the single-sector DMA buffer at
  173. <code>0x4000</code>. Retries handle the usual real-hardware flakiness.
  174. The second floppy slot can hold <code>root.img</code>.
  175. </p>
  176. <h3>PATA</h3>
  177. <p>
  178. <span class="file">ata.c</span> uses the legacy command block or the
  179. PCI IDE interface's native BARs. Multi-sector PIO waits for DRQ
  180. before every sector because drives drop it between sectors; it polls
  181. the command-block status rather than the alternate-status BAR, and
  182. falls back to single-sector commands when a bridge leaves DRQ pending.
  183. </p>
  184. <h3>SATA/AHCI</h3>
  185. <p>
  186. <span class="file">ahci.c</span> drives the first AHCI controller
  187. only, with no IRQs and no NCQ. It does COMRESET, IDENTIFY through the
  188. shared <code>ata_identify_parse()</code>, and READ/WRITE DMA EXT
  189. through a page-allocated bounce buffer. A disk added after boot needs
  190. a rescan; there is no COMRESET hotplug.
  191. </p>
  192. <h3>eMMC/SDHCI</h3>
  193. <p>
  194. <span class="file">sdhci.c</span> drives the Intel Braswell MMC
  195. function at PCI <code>00:10.0</code> (<code>8086:2294</code>, class
  196. <code>0805</code>), the HP Chromebook's eMMC. It resets the SDHCI
  197. host, selects the 1.8 V rail and Host Control 2's 1.8 V signalling,
  198. runs a 400 kHz initialization clock, then CMD0/1/2/3/7/16 and CMD8
  199. to read EXT_CSD (<code>SEC_COUNT</code> at 212,
  200. <code>CACHE_SIZE</code> at 249), and switches to a 25 MHz data clock.
  201. Sector I/O is CMD17/CMD24 through the polled PIO buffer port at
  202. 1-bit/25 MHz; there is no DMA, IRQ, bus-width/high-speed switch or
  203. hotplug. The read/write loops yield every 32 sectors so a long
  204. format does not starve the window manager. The eMMC appears as
  205. <code>mmc0</code>, and <code>format mmc0</code> writes an MBR + FAT
  206. partition exactly like an IDE/SATA disk. The write path flushes the
  207. card cache with CMD6 <code>FLUSH_CACHE</code> when EXT_CSD reports
  208. one.
  209. </p>
  210. </section>
  211. <section id="usb">
  212. <h2>USB stack</h2>
  213. <p>
  214. <span class="file">usb.c</span> is controller-agnostic. It handles
  215. enumeration, descriptor parsing, hub recursion, bus scans, per-controller
  216. addresses, the hotplug watcher and interrupt-IN consumers. Each host
  217. controller implements the <code>usb_hcd_ops</code> vtable in
  218. <span class="file">usb_hcd.h</span>.
  219. </p>
  220. <figure class="figure">
  221. <svg viewBox="0 0 920 300" role="img" aria-labelledby="usb-title usb-desc">
  222. <title id="usb-title">USB controller topology</title>
  223. <desc id="usb-desc">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.</desc>
  224. <rect class="svg-box accent" x="30" y="24" width="200" height="64" rx="9"/>
  225. <text class="svg-text" x="50" y="50">EHCI</text>
  226. <text class="svg-sub" x="50" y="70">high-speed root ports</text>
  227. <rect class="svg-box blue" x="252" y="24" width="200" height="64" rx="9"/>
  228. <text class="svg-text" x="272" y="50">UHCI</text>
  229. <text class="svg-sub" x="272" y="70">full/low speed · 1 instance</text>
  230. <rect class="svg-box blue" x="474" y="24" width="200" height="64" rx="9"/>
  231. <text class="svg-text" x="494" y="50">OHCI</text>
  232. <text class="svg-sub" x="494" y="70">full/low speed · up to 4</text>
  233. <rect class="svg-box green" x="696" y="24" width="194" height="64" rx="9"/>
  234. <text class="svg-text" x="716" y="50">xHCI</text>
  235. <text class="svg-sub" x="716" y="70">USB2 + USB3 root ports</text>
  236. <path class="svg-line accent" d="M130 88v40h330v28"/>
  237. <path class="svg-line blue" d="M352 88v68"/>
  238. <path class="svg-line blue" d="M574 88v68"/>
  239. <path class="svg-line green" d="M793 88v40H460v28"/>
  240. <rect class="svg-box" x="300" y="156" width="320" height="58" rx="9"/>
  241. <text class="svg-text" x="320" y="181">usb core</text>
  242. <text class="svg-sub" x="320" y="201">enumeration · hubs · hotplug · interrupt-IN slots</text>
  243. <path class="svg-line" d="M460 214v34"/>
  244. <path class="svg-line" d="M454 240l6 7 6-7"/>
  245. <rect class="svg-box" x="300" y="248" width="320" height="50" rx="9"/>
  246. <text class="svg-text" x="320" y="266">usbhid · keyboard + mouse</text>
  247. <text class="svg-text" x="320" y="286">usbmsc · mass storage</text>
  248. </svg>
  249. <figcaption>
  250. <strong>Companions are not optional.</strong> EHCI is scanned first
  251. so its port resets can hand non-high-speed devices back to a
  252. companion. There is no transaction translator: a low/full-speed
  253. device behind a high-speed hub is invisible to EHCI.
  254. </figcaption>
  255. </figure>
  256. <div class="table-wrap">
  257. <table>
  258. <thead>
  259. <tr><th>Controller</th><th>Transport</th><th>Instances</th><th>Implementation notes</th></tr>
  260. </thead>
  261. <tbody>
  262. <tr><td>UHCI</td><td>PCI I/O ports</td><td>1</td><td>Frame list at <code>0x3000</code>; control QH plus one QH per interrupt slot.</td></tr>
  263. <tr><td>OHCI</td><td>PCI MMIO</td><td>up to 4</td><td>HCCA from the page allocator, static ED/TD sets in the uncacheable <code>ohci_dma_page</code>, TDs start at <code>CC = NotAccessed</code>. Before reset it requests SMM ownership (<code>HcCommandStatus.OCR</code>, clear <code>HcControl.IR</code>) and disables the AMD southbridge USB SMI on <code>1002:4385</code>.</td></tr>
  264. <tr><td>EHCI</td><td>PCI MMIO</td><td>up to 4</td><td>Async QH/qTD schedule, page-allocated descriptors, polling only, no periodic list.</td></tr>
  265. <tr><td>xHCI</td><td>PCI MMIO</td><td>—</td><td>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 <code>HCH</code> around <code>HCRST</code>; 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.</td></tr>
  266. </tbody>
  267. </table>
  268. </div>
  269. <p>
  270. AMD SB600/SB700/SB800/SB950 firmware can leave the OHCI controllers
  271. owned by the SMM and keep the southbridge USB SMI enabled. The
  272. driver requests ownership and clears the SMI enable before scanning
  273. (<code>ohci.c</code>), so USB2 ports on the 970A-DS3P's SB950 work
  274. after the firmware handoff. The SB950's legacy OHCI DMA does not
  275. snoop dirty CPU cache lines, so the EDs, TDs, setup packet and
  276. interrupt buffers live in one page that <code>paging_init</code>
  277. maps uncacheable (PDE 0 is split before paging is enabled). Without
  278. it the controller occasionally read an empty ED, skipped the
  279. transfer and never re-armed the interrupt endpoint; the cursor
  280. froze with no error. Control transfers still flush their
  281. write-back data buffers around the transfer.
  282. </p>
  283. <p>
  284. Enumeration starts every device on the USB default 8-byte EP0 and
  285. adopts the descriptor's real <code>bMaxPacketSize0</code>
  286. afterwards. A failed port attempt is retried three times with a
  287. fresh port reset and a 20 ms settle, and OHCI gets a second boot
  288. pass 60 ms after the EHCI-first walk so a companion handback
  289. cannot leave a low-speed device unseen. HID detach is debounced
  290. (three consecutive disconnected reads, 50 TD errors) and a detach
  291. forces a clean full rescan, because a false port-loss leaves no
  292. connect-change bit to wake the per-port path.
  293. </p>
  294. <p>
  295. Hubs are class-9 devices: <code>usb.c</code> sets their configuration,
  296. powers every downstream port (honouring <code>bPwrOn2PwrGood</code>),
  297. resets and waits for <code>PORT_ENABLE</code>, then enumerates
  298. recursively. This is what makes the X201's internal PCH hubs work.
  299. Hotplug watches root ports; a device behind a hub is only found when a
  300. full scan runs (<code>lsusb</code> also bumps the USB generation so
  301. <code>usbhid</code> re-attaches). A scan and every mass-storage
  302. command claim the controllers for the calling process
  303. (<code>usb_bus_claim()</code>/<code>usb_bus_release()</code>, nesting).
  304. Every HCD delay and the ASIX/RNDIS/usbmsc probe delays go through
  305. <code>usb_delay_ms()</code>, and every HCD completion and port-reset
  306. poll loop calls <code>usb_poll_relax(t0)</code> outside its spinlock.
  307. When the claim belongs to a sleepable scan (<code>lsusb</code>, the
  308. kworker's HID rescan/hotplug, or the <code>storage</code> rescan
  309. reading a USB disk), the delay sleeps and the poll yields once a wait
  310. passes 2&nbsp;ms, both dropping the BKL, so port resets, NAKing
  311. devices and settle times no longer freeze the WM; everywhere else
  312. they busy-wait as before. The poll yields instead of sleeping
  313. because a 1&nbsp;ms sleep on an idle CPU wakes on the 100&nbsp;Hz idle
  314. tick. While another context owns the bus, the
  315. <span class="file">usb.c</span> wrappers refuse controller access
  316. (<code>usb_scan_foreign()</code>: control and bulk transfers fail,
  317. interrupt polls return no data, ports read as connected),
  318. <code>usb_hotplug_poll</code> skips its pass and
  319. <code>usbhid_poll</code> skips its tick. A USB NIC, the RTL8821AU or
  320. a USB disk therefore sees a transient error during a bus scan; the
  321. scan re-enumerates those devices anyway.
  322. </p>
  323. <h3>Mass storage</h3>
  324. <p>
  325. <span class="file">usbmsc.c</span> is a device-level probe alongside
  326. the ASIX Ethernet driver. It claims an interface with class 8,
  327. subclass 6 and protocol 0x50, parses its bulk IN/OUT endpoints and
  328. identifies the disk with SCSI INQUIRY + READ CAPACITY. Commands use
  329. Bulk-Only Transport with LUN 0 and 512-byte blocks: READ(10),
  330. WRITE(10), SYNCHRONIZE CACHE and a BOT reset/endpoint-halt recovery.
  331. Short bulk-IN chunks are accumulated within a BOT data stage; a
  332. failed READ(10) gets REQUEST SENSE, retries and a 1-sector
  333. fallback. Present devices are registered as <code>usb0..</code>
  334. (<code>BLK_USB</code>) by <code>blk_scan()</code>, so
  335. <code>storage</code>, the VFS, <code>format</code> and
  336. <code>install</code> can use them.
  337. </p>
  338. <p>
  339. Bulk transfers exist on EHCI and xHCI only; a mass-storage device on
  340. a UHCI/OHCI companion is left unclaimed. The xHCI driver drives
  341. direct USB3 root-port devices (USB3 hubs are not decoded), so a
  342. SuperSpeed stick on the Chromebook works. This is what makes the
  343. installer's <code>usb0</code> source possible: it reads the whole
  344. live image into RAM first and then writes the target, so slow eMMC
  345. writes cannot leave the USB source idle between chunks.
  346. </p>
  347. <h3>USB tethering</h3>
  348. <p>
  349. <span class="file">rndis.c</span> is another device-level probe. It
  350. scans every configuration for an RNDIS control function
  351. (<code>02/02/FF</code>, <code>E0/01/03</code> or an <code>EF</code>
  352. variant) and a data interface with bulk endpoints, selects that
  353. configuration, then sends RNDIS INIT/QUERY/packet-filter messages
  354. over the control interface. Ethernet frames travel in 44-byte RNDIS
  355. packet headers on the bulk pair, so the existing IPv4 stack sees a
  356. normal netdev named <code>rndis</code>. This is Android USB
  357. tethering, not WiFi; QEMU's full-speed <code>usb-net</code> device is
  358. the test target (<code>make run-rndis</code>). CDC-ECM/NCM and the
  359. RNDIS interrupt notification endpoint are not implemented.
  360. </p>
  361. </section>
  362. <section id="wifi">
  363. <h2>WiFi (Intel 7265D/3165, 6200/6300, RTL8821AU)</h2>
  364. <p>
  365. Two Intel generations share one PCIe transport. The HP Chromebook's
  366. Wireless-AC 7265 rev D or 3165 runs the newer <em>MVM</em> firmware
  367. (<span class="file">iwl_mvm.c</span>); the ThinkPad X201's Centrino
  368. Advanced-N 6200 (or Ultimate-N 6300) runs the older <em>DVM</em>
  369. firmware (<span class="file">iwl_dvm.c</span>).
  370. A Realtek RTL8821AU USB stick is the third backend
  371. (<span class="file">rtl8821au.c</span>, below).
  372. <span class="file">wifi_fw.c</span> picks the backend when the radio
  373. comes up — a plugged-in stick wins over the built-in card, otherwise
  374. the PCI probe decides — so <span class="file">wifi.c</span> and the
  375. <code>wifi</code> command are the same for all three. Everything is
  376. polled; every ring and buffer is page-allocated so nothing big lands
  377. in the kernel BSS.
  378. </p>
  379. <figure class="figure">
  380. <svg viewBox="0 0 920 300" role="img" aria-labelledby="wifi-title wifi-desc">
  381. <title id="wifi-title">WiFi software layers</title>
  382. <desc id="wifi-desc">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.</desc>
  383. <rect class="svg-box blue" x="40" y="20" width="400" height="56" rx="9"/>
  384. <text class="svg-text" x="60" y="44">wifi command + wpa.c (ring 3)</text>
  385. <text class="svg-sub" x="60" y="64">scan · PBKDF2 · 4-way / group handshake</text>
  386. <rect class="svg-box blue" x="480" y="20" width="400" height="56" rx="9"/>
  387. <text class="svg-text" x="500" y="44">net stack</text>
  388. <text class="svg-sub" x="500" y="64">DHCP · DNS · TCP via struct netdev</text>
  389. <rect class="svg-box accent" x="40" y="112" width="840" height="50" rx="9"/>
  390. <text class="svg-text" x="60" y="134">wifi.c — 802.11 station + the wifi netdev</text>
  391. <text class="svg-sub" x="60" y="152">auth/assoc · 802.11 ↔ Ethernet (LLC/SNAP, CCMP header) · EAPOL queue · SYS_WIFI</text>
  392. <rect class="svg-box" x="40" y="182" width="840" height="44" rx="9"/>
  393. <text class="svg-text" x="60" y="209">iwl_mvm.c (7265D) · iwl_dvm.c (6200/6300) · rtl8821au.c (USB) — via wifi_fw.c</text>
  394. <rect class="svg-box green" x="40" y="246" width="840" height="44" rx="9"/>
  395. <text class="svg-text" x="60" y="273">iwl_trans.c (PCIe rings, firmware DMA) · usb.c bulk + vendor control (RTL8821AU)</text>
  396. <path class="svg-line blue" d="M240 76v28"/>
  397. <path class="svg-line blue" d="M234 98l6 7 6-7"/>
  398. <path class="svg-line blue" d="M680 76v28"/>
  399. <path class="svg-line blue" d="M674 98l6 7 6-7"/>
  400. <path class="svg-line" d="M460 162v14"/>
  401. <path class="svg-line" d="M460 226v14"/>
  402. </svg>
  403. <figcaption>
  404. <strong>Keys stay in ring 3 until installed.</strong> The supplicant
  405. derives the PTK and unwraps the GTK; the kernel only moves EAPOL
  406. frames and hands the TK/GTK to the firmware, which does CCMP.
  407. Sources: <span class="file">ucmd_wifi.c</span>,
  408. <span class="file">wpa.c</span>, <span class="file">wifi.c</span>,
  409. <span class="file">wifi_fw.c</span>, <span class="file">iwl_mvm.c</span>,
  410. <span class="file">rtl8821au.c</span>,
  411. <span class="file">iwl_dvm.c</span>, <span class="file">iwl_trans.c</span>.
  412. </figcaption>
  413. </figure>
  414. <ul>
  415. <li><strong>Transport.</strong> <span class="file">iwl_trans.c</span> follows Linux iwlwifi for the 7000 family: APM init, one legacy RX queue of 256 × 4 KB RBDs, gen1 128-byte TFDs, byte-count tables in dwords, and the FH service channel loading firmware sections through a 128 KB bounce buffer. The NIC is kept awake (MAC access request held) and interrupts stay masked; PCI INTx is disabled. Host commands use the wide 8-byte header (legacy commands go out as group 1).</li>
  416. <li><strong>Firmware.</strong> <code>iwlwifi-7265D-29.ucode</code> ships in the command pack as <code>firmware/iwlwifi-7265D-29.ucode</code> (1,036,312 bytes). It is a single-CPU image with LMAC scan, DQA queues and the old station API. <span class="file">iwl_mvm.c</span> runs the INIT image (NVM read for the MAC address, calibration, PHY-DB collection), then the runtime image (PHY-DB replay, DQA, aux station, PHY context, CAM power, MCC <code>ZZ</code>, station MAC context).</li>
  417. <li><strong>Queues.</strong> Command queue 0 (FIFO 7), aux queue 1 (scan probes), BSS queue 4 for the AP station (management and data, BE FIFO).</li>
  418. <li><strong>Station.</strong> <span class="file">wifi.c</span> builds open-system authentication and the association request itself, without WMM or HT IEs, so data frames are plain non-QoS 802.11 + LLC/SNAP. Management frames go at 1 Mb/s CCK (6 Mb/s on 5 GHz), data at a fixed 12 Mb/s OFDM (no rate scaling table yet).</li>
  419. <li><strong>Security.</strong> WPA2-PSK with CCMP only. The 4-way and group handshakes run in ring 3 (<span class="file">wpa.c</span>); the kernel queues EAPOL frames and installs the TK/GTK with <code>ADD_STA_KEY</code>. TX uses the firmware's CCMP engine with the key embedded in <code>TX_CMD</code>; the host builds the 8-byte CCMP header and its packet number. On the tested 7265D-29 the firmware does not use the installed keys for RX and reports <code>SEC_ENC_ERR</code>, so RX CCMP is decrypted in software by <span class="file">ccmp.c</span> (AES-CCM, RFC 3610) with the same TK/GTK. There is no software replay window yet.</li>
  420. <li><strong>Bring-up on first use.</strong> The boot probe only finds the PCI function. The firmware is loaded by the first <code>wifi</code> command, so boot time and RAM do not change when WiFi is unused. The netdev reports <code>link_up() = 0</code> until it is connected, so the boot DHCP is skipped.</li>
  421. <li><strong>kexec.</strong> <code>netdev_shutdown()</code> always stops the card through <code>wifi_shutdown()</code>, even when it is not the active netdev, because its RX ring would keep writing into pages the next kernel reuses.</li>
  422. </ul>
  423. <h3>6200/6300: the DVM firmware</h3>
  424. <p>
  425. The transport differences live in one per-family descriptor
  426. (<code>fam_7000</code>/<code>fam_6000</code> in
  427. <span class="file">iwl_trans.c</span>):
  428. </p>
  429. <div class="table-wrap">
  430. <table>
  431. <thead>
  432. <tr><th>Parameter</th><th>7265D/3165 (MVM)</th><th>6200/6300 (DVM)</th></tr>
  433. </thead>
  434. <tbody>
  435. <tr><td>Firmware</td><td><code>iwlwifi-7265D-29.ucode</code> (TLV)</td><td><code>iwlwifi-6000-4.ucode</code> (v2 header: inst/data sections at <code>0x0</code>/<code>0x800000</code>)</td></tr>
  436. <tr><td>Scheduler queues</td><td>31</td><td>20</td></tr>
  437. <tr><td>Command queue / FIFO</td><td>0 / 7</td><td>4 / 7</td></tr>
  438. <tr><td>Data queues</td><td>aux 1, BSS 4 (configured by firmware, <code>SCD_QUEUE_CFG</code>)</td><td>VO 0 (management), VI 1, BE 2 (data), BK 3 (configured by the transport)</td></tr>
  439. <tr><td>Command header</td><td>8-byte wide (group 1)</td><td>4-byte</td></tr>
  440. <tr><td>Byte-count table</td><td>dwords</td><td>bytes</td></tr>
  441. <tr><td>MAC address</td><td>NVM via <code>NVM_ACCESS_CMD</code></td><td>OTP read by the host through <code>CSR_EEPROM_REG</code></td></tr>
  442. </tbody>
  443. </table>
  444. </div>
  445. <ul>
  446. <li><strong>Bring-up.</strong> The host reads the 2 KB OTP (MAC at word 0x15, radio config at 0x48, crystal calibration through the calibration link), writes the radio SKU bits during NIC init, then runs the INIT image: <code>CALIBRATION_CFG_CMD</code> and every <code>CALIBRATION_RES_NOTIFICATION</code> stored by op code until <code>CALIBRATION_COMPLETE</code>. The runtime image gets the stored results back as <code>REPLY_PHY_CALIBRATION_CMD</code>, DC calibration, TX antennas, an RXON, TX power and a CAM power table.</li>
  447. <li><strong>RXON.</strong> DVM has no MAC/PHY contexts: one <code>REPLY_RXON</code> carries channel, BSSID, filters and association. A full RXON first clears the association, which wipes the firmware's station table, so the broadcast station (15) and the AP station (0) are re-added with their fixed-rate <code>LINK_QUALITY</code> tables, and a new TX power command follows every retune.</li>
  448. <li><strong>Scan.</strong> One <code>REPLY_SCAN_CMD</code> per band: 2.4 GHz, then 5 GHz after <code>SCAN_COMPLETE_NOTIFICATION</code>. Only channels the EEPROM regulatory tables mark valid are scanned, and probes are only sent where they are marked active and not radar. A firmware assert makes the next scan or connect reload the firmware instead of failing until reboot.</li>
  449. <li><strong>Keys.</strong> <code>REPLY_ADD_STA</code> in modify mode on the AP station (pairwise offset 0, group offset 1). RX frames are the same <code>RX_PHY</code> + <code>RX_MPDU</code> pair as on the 7265D, so the software CCMP fallback in <span class="file">wifi.c</span> covers both cards. The 6200 transmits on antenna B (its <code>ANT_BC</code> configuration).</li>
  450. </ul>
  451. <h3 id="rtl8821au">RTL8821AU USB stick</h3>
  452. <p>
  453. <span class="file">rtl8821au.c</span> ports the Linux
  454. <code>rtw88</code> 8821A/USB bring-up (<code>rtw88xxa_power_on()</code>
  455. and the helpers it calls) and implements the same entry points as
  456. the Intel layers. Registers are USB vendor requests
  457. (<code>bRequest 5</code>, <code>wValue</code> = address, 1/2/4 bytes);
  458. the 8051 firmware is written in 196-byte requests to
  459. <code>0x1000</code> page by page. The USB probe only matches the
  460. VID/PID, parses the bulk endpoints and sets the configuration; the
  461. chip is powered on by the first <code>wifi</code> command, which
  462. takes a few seconds of control transfers.
  463. </p>
  464. <div class="table-wrap">
  465. <table>
  466. <thead>
  467. <tr><th>Step</th><th>What</th><th>Linux source</th></tr>
  468. </thead>
  469. <tbody>
  470. <tr><td>eFuse</td><td>Card-enable power sequence, 512-byte physical map → logical map; MAC at 0x107, crystal cap, BB swing, RFE (external LNA/PA) flags, TX power bases</td><td><code>rtw_parse_efuse_map</code>, <code>rtw88xxa_read_efuse</code></td></tr>
  471. <tr><td>MAC</td><td>Power sequence, LLT (256 pages, boundary 248), firmware download + <code>FW_READY</code>, MAC table, page reservation, queue map, EDCA/beacon/USB burst setup</td><td><code>rtw88xxa_power_on</code>, <code>__rtw_download_firmware_legacy</code></td></tr>
  472. <tr><td>PHY</td><td>BB + AGC tables, crystal cap, RF-A table, 2.4 GHz band switch; the tables' <code>if/elif/else</code> branches use the 8821A cut/RFE rules</td><td><code>rtw_parse_tbl_phy_cond</code>, <code>rtw88xxa_switch_band</code></td></tr>
  473. <tr><td>Channel</td><td>Band switch (RFE pin mux, CCK on/off, basic rates), RF 0x18 channel/band, 20 MHz bandwidth, TX AGC from the eFuse base index</td><td><code>rtw88xxa_set_channel</code></td></tr>
  474. </tbody>
  475. </table>
  476. </div>
  477. <ul>
  478. <li><strong>Tables outside the kernel.</strong> The MAC/BB/AGC/RF-A register tables and the power sequences (~11 KB) are taken unchanged from Linux into <code>third_party/rtw88/rtw8821a_table.inc</code> (BSD-3-Clause). The host tool <span class="file">mkrtwtbl.c</span> turns them into <code>firmware/rtl8821a.tbl</code> (layout in <span class="file">rtl8821a_tbl.h</span>), which ships in the full pack next to <code>firmware/rtw8821a_fw.bin</code> (31,898 bytes from linux-firmware). Only the driver code is in the kernel image (~12 KB).</li>
  479. <li><strong>One TX endpoint.</strong> The xHCI driver keeps a single bulk-OUT ring and reconfigures it when the endpoint changes, so every TX queue (management and data) is mapped to one DMA queue — LOW with 3–4 bulk-OUT endpoints, NORMAL with 2 — and therefore one endpoint. A TX transfer that would be an exact multiple of 512 bytes is shifted by 8 bytes (<code>PKT_OFFSET</code> 1) instead of needing a zero-length packet.</li>
  480. <li><strong>RX.</strong> RX aggregation is off, so a bulk-IN transfer (8 KB buffer) normally holds one packet; the parser still walks several. RSSI comes from the PHY status (CCK LNA/VGA table, OFDM gain − 110 dBm). <code>rtl8821au_poll()</code> drains up to 64 transfers per call.</li>
  481. <li><strong>Scan.</strong> A software channel hop driven by the poll: 2.4 GHz 1–13 and 5 GHz 36–48 active (wildcard probe request, 70 ms), 52–64/100–140/149–165 passive (120 ms).</li>
  482. <li><strong>Crypto in software.</strong> The chip's security engine is not used: <span class="file">wifi.c</span> decrypts CCMP RX with <span class="file">ccmp.c</span>, and the driver encrypts CCMP TX with <code>ccmp_tx_encrypt()</code> (802.11 and RFC 3610 vectors in <code>make test-ccmp</code>). TX uses fixed rates with fallback disabled: 1 Mb/s (2.4 GHz) / 6 Mb/s (5 GHz) management, 12 Mb/s data, hardware sequence numbers.</li>
  483. <li><strong>Delays.</strong> <code>SYS_WIFI</code> runs with interrupts off, so the millisecond tick does not advance inside a call: all bring-up delays are busy waits; only the scan dwell uses the tick (between polls).</li>
  484. <li><strong>Unplug.</strong> Repeated USB errors, a disconnected root port or a re-enumeration mark the device dead; <span class="file">wifi.c</span> drops to DOWN and the next <code>wifi</code> command brings it up again.</li>
  485. </ul>
  486. </section>
  487. <section id="hid">
  488. <h2>Input</h2>
  489. <p>
  490. <span class="file">usbhid.c</span> gives every HID class-3 interface
  491. with an interrupt-IN endpoint one of the six USB interrupt slots. Boot
  492. interfaces (subclass 1, protocol 1/2) are used as-is; other class-3
  493. interfaces are classified by reading their HID report descriptor.
  494. Composite receivers and several devices can coexist; mouse reports
  495. from all slots are merged.
  496. </p>
  497. <ul>
  498. <li><strong>Mouse.</strong> Three-byte boot reports: buttons in <code>b0 &amp; 7</code>, signed <code>dx/dy</code>. HID's +y is flipped to the PS/2 convention.</li>
  499. <li><strong>Keyboard.</strong> Eight-byte boot reports (modifier + six keycodes). Reports are diffed and decoded through a HID-usage → scancode-set-1 table, then injected with <code>io_inject_scancode()</code>.</li>
  500. <li><strong>Repeat.</strong> A boot keyboard only reports changes, so <code>io.c</code> adds software typematic repeat (500 ms delay, 33 ms rate).</li>
  501. <li><strong>PS/2.</strong> The i8042 path shares the cursor and keyboard code; the BIOS legacy USB emulation is disabled because the kernel owns the devices.</li>
  502. </ul>
  503. <p>
  504. <code>mouseinfo</code> shows the active backend and whether a USB
  505. keyboard is attached. Headless regression tests inject mouse motion
  506. and keys through QMP and verify the result with screen dumps.
  507. </p>
  508. <h3>I2C touchpad</h3>
  509. <p>
  510. The HP Chromebook 11 G5 EE has no PS/2 port: its Elan touchpad is a
  511. HID-over-I2C device on LPSS I2C6. The LPSS I2C functions are hidden
  512. from PCI in ACPI mode, so <span class="file">touchpad.c</span> scans
  513. the two firmware BAR windows for a DesignWare component (only on an
  514. Airmont CPU, family 6 model <code>0x4C</code>: elsewhere the scan
  515. would reset-cycle 32 fixed MMIO windows for ~64 ms of boot) and
  516. <span class="file">i2c.c</span> drives that controller in fast mode,
  517. polled and without interrupts.
  518. </p>
  519. <ul>
  520. <li><strong>Probe.</strong> Slave address <code>0x15</code>: reset
  521. (<code>0x0100</code>), consume the 2-byte acknowledgement, read the
  522. HID descriptor, select absolute mode (<code>0x0300 = 1</code>) and
  523. wake the device (<code>0x0800</code>). Resetting last leaves it
  524. silent until the next power cycle.</li>
  525. <li><strong>Reports.</strong> The Elan vendor report <code>0x5D</code>
  526. carries a finger bitmask and five packed bytes per active finger
  527. (X/Y high bits, X low, Y low, size, pressure). The decoder feeds the
  528. device-independent <span class="file">touchpad_gesture.c</span>
  529. engine; a future PS/2 or USB touchpad backend only has to produce
  530. the same two-contact frame. The native max-X/Y commands
  531. (<code>0x0106</code>/<code>0x0107</code>) give the corner zone a
  532. physical coordinate frame.</li>
  533. <li><strong>Tap gestures.</strong> A short stationary contact is
  534. turned into a synthetic button press: two fingers is a right click,
  535. one finger starting in the bottom-right zone (right 25% x bottom
  536. 25% of the pad) is a right click, and one finger elsewhere is a
  537. left click. The press is held for 120 ms so applications polling
  538. <code>SYS_WIN_POINTER</code> sample it. Taps shorter than two 25 ms
  539. samples, longer than 300 ms, moved more than 60 coordinate units,
  540. or accompanied by a physical clickpad press are ignored.</li>
  541. <li><strong>Physical clickpad.</strong> The single clickpad button
  542. is latched at its leading edge: a press whose finger starts in the
  543. bottom-right zone reports the right button, anywhere else reports
  544. the left button, and the choice holds until the button is released
  545. (so a corner drag stays a right drag).</li>
  546. <li><strong>Two-finger scroll.</strong> With exactly two contacts,
  547. the pointer freezes and the centroid movement accumulates. After
  548. about 30 device units it becomes a scroll and emits movement / 2
  549. in pixels; natural direction (two fingers up = later content) is
  550. the default, and the two-finger right tap is suppressed once the
  551. gesture has scrolled. The pointer re-anchors when one finger
  552. remains. The <code>scroll on|off|natural|traditional</code> option
  553. tunes it.</li>
  554. <li><strong>Polling.</strong> The report GPIO has no driver yet, so
  555. the input register is read every 25 ms. Back-to-back reads stall the
  556. device, which is why the poll is throttled rather than run flat
  557. out.</li>
  558. <li><strong>Discovery and tuning.</strong> <code>touchpad</code>
  559. prints the probe result, max coordinates, last report and synthesized
  560. click counters, and takes <code>rightclick off|tap|corner|both</code>,
  561. <code>tapclick on|off</code> or
  562. <code>scroll on|off|natural|traditional</code>; <code>mouseinfo</code>
  563. lists the Elan vendor/product ID next to the PS/2 and USB backends.</li>
  564. </ul>
  565. </section>
  566. <section id="serial">
  567. <h2>Serial</h2>
  568. <p>
  569. <span class="file">serial.c</span> drives the 16550 at COM1, 115200
  570. 8N1, with an IRQ-driven receive ring buffer. It is used for the boot
  571. trace, the netlog mirror source, the <code>dbg</code> monitor and the
  572. <code>KXE2</code> kexec receiver.
  573. </p>
  574. <p>
  575. The transmitter is polled, so a machine without a serial port still
  576. boots normally. <code>serial_puthex</code> and
  577. <code>serial_putdec</code> are the structured dump helpers used by
  578. drivers.
  579. </p>
  580. </section>
  581. <section id="sensors">
  582. <h2>Sensors, power &amp; thermals</h2>
  583. <ul>
  584. <li><strong>DTS / AMD Tctl.</strong> <span class="file">thermal.c</span> reads <code>IA32_THERM_STATUS</code> on an allowlist of Core/Core 2, Nehalem/Westmere, Bonnell and Airmont/Braswell models. TjMax comes from <code>IA32_TEMPERATURE_TARGET</code> on Nehalem/Westmere; Airmont uses coretemp's 90 °C table (the kernel does not read the MSR before the IDT exists), and Bonnell uses the table. AMD family 15h models below <code>0x60</code> (Bulldozer/Piledriver) read <code>D18F3xA4</code> at PCI <code>0:18.3</code>; the package value is sampled from the kworker under the BKL and copied to every CPU.</li>
  585. <li><strong>IT87xx.</strong> <span class="file">it87.c</span> reads the Super I/O temperatures and fan tachometers on the ASUS AT3IONT-I and the Gigabyte 970A-DS3P (IT8728F). Nothing is written to fan control.</li>
  586. <li><strong>ThinkPad EC.</strong> <span class="file">tpec.c</span> is gated on an SMBIOS Lenovo/IBM match and reads temperatures and fan mode through the shared ACPI EC protocol in <span class="file">ec.c</span> (ports <code>0x62/0x66</code>, command <code>0x80</code> read / <code>0x81</code> write, OBF/IBF waits, stale-byte drain, bounded polls). Battery/AC state comes from <code>0x38/0x39</code> (present, charging, discharging), <code>0x46</code> bit 4 (AC online), and the page-selected 16-byte window at <code>0xA0..0xAF</code>; <code>0x81</code> selects the battery and page (0 dynamic, 1 mode, 2 design, 5 manufacturer, 6 model). That page selector is the only EC write, and it is restored when it changed.</li>
  587. <li><strong>Chrome EC.</strong> <span class="file">cros_ec.c</span> probes the Chrome OS EC, gated on the ACPI memory version, the <code>'E','C'</code> memmap id and the device feature bits; it skips the probe when the ThinkPad EC is present. Its ACPI window <code>0x20..0xFF</code> mirrors memmap <code>0x00..0xDF</code>: temperature sensors <code>0x00..0x0f</code>/<code>0x18..0x1f</code> (raw − 73 °C), fans <code>0x10..0x17</code> (<code>0xffff</code> absent), switches <code>0x30</code> (lid/power button), and the battery block <code>0x40..0x7f</code> (AC/present/charging flags at <code>0x4c</code>, voltage/rate/remaining/design/last-full/cycle count, and the 8-byte strings). <code>EC_ACPI_MEM_BATTERY_INDEX</code> <code>0x12</code> selects the battery and waits for <code>BATT_INDEX</code> <code>0x4e</code>; <code>EC_ACPI_MEM_STRINGS_FIFO</code> <code>0x16</code> returns longer strings when supported. The Cyan full-charge workaround is applied, and the units are mAh/mA. <span class="file">power_src.c</span> picks the ThinkPad backend first, then the Chrome EC; <code>SYS_CROS_EC_SENSORS</code> (107) exposes the EC temperature/fan/switch snapshot.</li>
  588. <li><strong>MTRRs.</strong> <span class="file">mtrr.c</span> manages write-combining ranges for the framebuffer and reports the effective mapping.</li>
  589. </ul>
  590. <p>
  591. <code>sensors</code> prints supported CPU temperatures (and the
  592. Intel 90/100/125 °C delta scales when there is no published TjMax),
  593. board sensors and both EC types; <code>powerinfo</code> prints the
  594. source (<code>thinkpad</code> or <code>chrome ec</code>), the AC
  595. adapter, battery model/manufacturer/serial, capacities, voltage,
  596. rate and cycle count through <code>SYS_POWER_INFO</code>;
  597. <code>power</code> prints ratios, effective MHz and C-state hints.
  598. The WM top bar shows the CPU temperature and, on both ThinkPads
  599. and Chromebooks, a status icon at the far right for the first
  600. present battery: a plug while the AC adapter is online, a
  601. level-filled battery on battery, with a percentage tooltip below
  602. the icon on hover. The tooltip is painted after the windows, so
  603. it always stays on top. Machines without an EC show neither.
  604. </p>
  605. </section>
  606. <section id="rtc">
  607. <h2>Wall clock (RTC)</h2>
  608. <p>
  609. <span class="file">rtc.c</span> talks to the MC146818-compatible
  610. CMOS clock through ports <code>0x70/0x71</code>. Reads honour the
  611. register-B BCD/binary and 12/24-hour modes, retry when the
  612. update-in-progress bit is set, and decode the hour's PM flag. The
  613. RTC only stores a two-digit year, so the kernel expands it over a
  614. 1970–2069 window (70–99 → 1900s, 00–69 → 2000s); a board whose
  615. dead battery left 1980 or 1990 therefore reads correctly instead of
  616. being pushed a century forward. Writes validate the calendar (leap
  617. years included), raise the register-B SET bit, preserve the mode
  618. bits and write the computed weekday. On ACPI machines the FADT
  619. century register (offset 108, normally CMOS <code>0x32</code>) is
  620. written as well, so the firmware and other operating systems see
  621. the intended century; boards without ACPI get no arbitrary NVRAM
  622. write.
  623. </p>
  624. <p>
  625. <code>SYS_RTC_GET</code>/<code>SYS_RTC_SET</code> (104/105) expose
  626. the full <code>struct sys_datetime</code>; the older
  627. <code>SYS_RTC_HMS</code>/<code>SYS_RTC_DATETIME</code> calls remain
  628. the small read-only views. The WM’s top-bar date/time opens the
  629. control panel, whose Date &amp; Time tile reveals an inline
  630. editor; its <em>Sync NTP</em> button fetches UTC through
  631. <code>SYS_NTP_SYNC</code> (106), backed
  632. by the SNTP client in <span class="file">ntp.c</span>, and writes
  633. it with <code>SYS_RTC_SET</code>. The <code>date</code> command
  634. prints the same clock in the classic Linux format.
  635. </p>
  636. </section>
  637. <section id="panic">
  638. <h2>Panic screen</h2>
  639. <p>
  640. On a ring-0 fault, <span class="file">panic.c</span> draws straight
  641. into the framebuffer — bypassing the shadow buffer and the WM — and
  642. mirrors the same data to COM1 before halting. The banner includes the
  643. vector and error code, GPRs, control registers, current pid/name,
  644. uptime, instruction bytes and stack return-address candidates in the
  645. kernel image.
  646. </p>
  647. <p>
  648. Faults from ring 3 do not halt: the process is killed with a short
  649. message in its terminal and serial log. There is no interactive
  650. debugger on screen; the <code>dbg</code> kernel command drives a
  651. serial monitor instead.
  652. </p>
  653. </section>
  654. <section id="limits">
  655. <h2>Limits</h2>
  656. <ul>
  657. <li><strong>Polling.</strong> USB, storage and network drivers consume CPU time while waiting; there is no IRQ-driven data path outside PS/2, serial and the PIT.</li>
  658. <li><strong>EHCI.</strong> High-speed root ports only; no split transactions for low/full-speed devices behind a high-speed hub.</li>
  659. <li><strong>xHCI.</strong> USB2 and USB3 root ports; direct SuperSpeed devices work, but USB3 hub port-status decoding is not implemented.</li>
  660. <li><strong>HID.</strong> Report IDs are not handled, absolute pointers/tablets are ignored, and there is no wheel support.</li>
  661. <li><strong>AHCI.</strong> First controller only, no hotplug after boot, disks above 2 TB are clamped to 32-bit LBA.</li>
  662. <li><strong>eMMC.</strong> Polled 1-bit/25 MHz PIO; no DMA, IRQ, CMD6 bus-width/high-speed/DDR switch or hotplug. Only the eMMC function is driven; the SDIO/SD functions and SD card reader are not.</li>
  663. <li><strong>Storage serialization.</strong> A FAT/floppy operation sets <code>sys_fs_busy</code> and stalls process switching for its duration; the PIT keeps ticking.</li>
  664. <li><strong>EC.</strong> The Chrome EC path uses the ACPI v2 memmap only: no MEC host-command interface, EC SCI events, charger current/voltage, charging limit or EC firmware version. The ThinkPad H8 path is limited to its page-selected battery window and has no SCI handler. Battery/AC is polled by the WM once a second.</li>
  665. <li><strong>WiFi.</strong> Intel 7265 rev D/3165 (7265D firmware) and 6200/6300 (6000 firmware, written without hardware in the loop); WPA2-PSK/CCMP and open networks, no WPA3/SAE, 802.1X, TKIP or WEP. No roaming, power save, background scan, HT/VHT, aggregation or rate scaling. Group rekeys need the background <code>wifi __keep</code> helper running. RX CCMP falls back to the byte-oriented software AES-CCM path when the firmware rejects the installed keys, so it has no replay window and is CPU-bound at high RX rates.</li>
  666. <li><strong>RTL8821AU.</strong> High-speed EHCI/xHCI only (no UHCI/OHCI bulk). No IQ calibration, thermal power tracking, DIG, BT coexistence or by-rate/regulatory TX power tables (the eFuse base index is used for every rate); 20 MHz legacy rates only. Only one bulk device can stream on xHCI at a time (single bulk ring), so it does not mix with an ASIX dongle or a USB stick transfer.</li>
  667. <li><strong>Suspend.</strong> There is no S0ix/suspend path; package C-states and the EC sleep handshake remain firmware-managed.</li>
  668. </ul>
  669. </section>
  670. <section id="sources">
  671. <h2>Source map</h2>
  672. <ul class="filelist">
  673. <li><code>kernel/pci.h</code> — enumeration</li>
  674. <li><code>kernel/blkdev.c</code> — block registry</li>
  675. <li><code>kernel/sdhci.c</code>, <code>kernel/sdhci.h</code> — Intel Braswell eMMC</li>
  676. <li><code>kernel/disk.c</code> — floppy / DMA</li>
  677. <li><code>kernel/ata.c</code>, <code>kernel/ahci.c</code> — PATA/SATA</li>
  678. <li><code>kernel/usb.c</code>, <code>kernel/usb_hcd.h</code> — USB core</li>
  679. <li><code>kernel/uhci.c</code>, <code>kernel/ohci.c</code>, <code>kernel/ehci.c</code>, <code>kernel/xhci.c</code></li>
  680. <li><code>kernel/usbmsc.c</code>, <code>kernel/usbmsc.h</code> — USB BOT/SCSI mass storage</li>
  681. <li><code>kernel/rndis.c</code>, <code>kernel/rndis.h</code> — USB RNDIS tethering</li>
  682. <li><code>kernel/iwl_trans.c</code>, <code>kernel/iwl_trans.h</code> — Intel WiFi PCIe transport (7000 and 6000 families)</li>
  683. <li><code>kernel/iwl_mvm.c</code>, <code>kernel/iwl_mvm.h</code> — 7265D/3165 firmware commands (MVM)</li>
  684. <li><code>kernel/iwl_dvm.c</code>, <code>kernel/iwl_dvm.h</code> — 6200/6300 firmware commands (DVM)</li>
  685. <li><code>kernel/wifi_fw.c</code>, <code>kernel/wifi_fw.h</code> — WiFi backend dispatch (Intel MVM/DVM, RTL8821AU)</li>
  686. <li><code>kernel/rtl8821au.c</code>, <code>kernel/rtl8821au.h</code> — Realtek RTL8821AU USB WiFi</li>
  687. <li><code>tools/mkrtwtbl.c</code>, <code>include/rtl8821a_tbl.h</code>, <code>third_party/rtw88/</code> — RTL8821A register tables → <code>firmware/rtl8821a.tbl</code></li>
  688. <li><code>kernel/wifi.c</code>, <code>kernel/wifi.h</code> — 802.11 station, <code>wifi</code> netdev, <code>SYS_WIFI</code></li>
  689. <li><code>kernel/ccmp.c</code>, <code>kernel/ccmp.h</code> — software CCMP (AES-CCM): RX fallback, RTL8821AU TX</li>
  690. <li><code>kernel/install.c</code> — live-image clone installer</li>
  691. <li><code>kernel/backlight.c</code>, <code>kernel/backlight.h</code> — Cherryview/Braswell panel PWM</li>
  692. <li><code>kernel/usbhid.c</code>, <code>kernel/mouse.c</code>, <code>kernel/io.c</code> — input</li>
  693. <li><code>kernel/i2c.c</code>, <code>kernel/i2c.h</code> — DesignWare/LPSS I2C master</li>
  694. <li><code>kernel/touchpad.c</code>, <code>kernel/touchpad.h</code> — Elan HID-over-I2C touchpad</li>
  695. <li><code>kernel/touchpad_gesture.c</code>, <code>kernel/touchpad_gesture.h</code> — device-independent contact gestures (tap, right-click zones, scroll)</li>
  696. <li><code>kernel/touchpad_gesture_test.c</code> — host test (<code>make test-touchpad</code>)</li>
  697. <li><code>kernel/serial.c</code>, <code>kernel/serial_ring_buf.c</code></li>
  698. <li><code>kernel/thermal.c</code>, <code>kernel/it87.c</code>, <code>kernel/tpec.c</code>, <code>kernel/ec.c</code>, <code>kernel/cros_ec.c</code>, <code>kernel/power_src.c</code>, <code>kernel/mtrr.c</code></li>
  699. <li><code>kernel/rtc.c</code> — CMOS wall clock read/write</li>
  700. <li><code>kernel/panic.c</code>, <code>kernel/timer.S</code> — fatal exceptions</li>
  701. </ul>
  702. </section>
  703. </main>
  704. <footer class="site-footer">
  705. <div class="inner">
  706. <p><strong>NebOS 0.2.0</strong> · Architecture documentation · <a href="index.html">overview</a></p>
  707. <p>Maintain alongside <code>AGENTS.md</code> and the source files listed on each page.</p>
  708. </div>
  709. </footer>
  710. </body>
  711. </html>