drivers.html 18 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383
  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, 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 HID</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="#hid">Input</a></li>
  56. <li><a href="#serial">Serial</a></li>
  57. <li><a href="#sensors">Sensors &amp; power</a></li>
  58. <li><a href="#panic">Panic screen</a></li>
  59. <li><a href="#limits">Limits</a></li>
  60. <li><a href="#sources">Source map</a></li>
  61. </ul>
  62. </nav>
  63. <section id="inventory">
  64. <h2>Driver inventory</h2>
  65. <p>
  66. Every driver in the tree is small enough to read in one sitting. The
  67. table below is the quickest way to find the one responsible for a
  68. device.
  69. </p>
  70. <div class="table-wrap">
  71. <table>
  72. <thead>
  73. <tr><th>Subsystem</th><th>Driver</th><th>Bus / access</th><th>Service model</th></tr>
  74. </thead>
  75. <tbody>
  76. <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>
  77. <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>
  78. <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>
  79. <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>
  80. <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></td><td>PCI or USB</td><td>Polled, one active receiver</td></tr>
  81. <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>
  82. <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>
  83. <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>
  84. <tr><td>Board sensors</td><td><span class="file">it87.c</span>, <span class="file">tpec.c</span></td><td>Super I/O, ThinkPad EC</td><td>Polled read-only</td></tr>
  85. </tbody>
  86. </table>
  87. </div>
  88. </section>
  89. <section id="pci">
  90. <h2>PCI &amp; discovery</h2>
  91. <p>
  92. <span class="file">pci.c</span> walks bus/device/function and exposes
  93. BAR and capability access. The USB scan checks all functions: real
  94. PIIX3/PIIX4/VIA layouts put the USB function at 0:07.2 or 0:01.2, not
  95. 0:07.0. Controllers with unassigned BARs are ignored rather than
  96. driven at address zero.
  97. </p>
  98. <p>
  99. MMIO regions are mapped through <code>paging_map_mmio()</code>. PCI
  100. interrupts are disabled before touching MMIO, so every driver polls
  101. its own status registers. <code>lspci</code> lists every function;
  102. with a filter it prints BAR type, size and address details.
  103. </p>
  104. </section>
  105. <section id="storage">
  106. <h2>Storage</h2>
  107. <p>
  108. <span class="file">blkdev.c</span> is a small registry of block
  109. devices. Each device exposes sector read/write plus geometry; FAT and
  110. the format command sit above that interface and never talk to a
  111. controller directly. Devices are named <code>floppy0</code>,
  112. <code>ide0</code>, <code>sata0</code> and so on; partitions append
  113. <code>p1</code>, <code>p2</code>.
  114. </p>
  115. <figure class="figure">
  116. <svg viewBox="0 0 920 246" role="img" aria-labelledby="storage-title storage-desc">
  117. <title id="storage-title">Storage software layers</title>
  118. <desc id="storage-desc">The VFS and format tools use a block-device registry, which dispatches to the floppy, ATA PIO or AHCI driver, then to the physical disk.</desc>
  119. <rect class="svg-box blue" x="40" y="30" width="230" height="62" rx="9"/>
  120. <text class="svg-text" x="60" y="57">VFS · FAT · format</text>
  121. <text class="svg-sub" x="60" y="77">files, not sectors</text>
  122. <rect class="svg-box accent" x="345" y="30" width="230" height="62" rx="9"/>
  123. <text class="svg-text" x="365" y="57">blkdev registry</text>
  124. <text class="svg-sub" x="365" y="77">sector read / write + geometry</text>
  125. <rect class="svg-box" x="650" y="30" width="230" height="62" rx="9"/>
  126. <text class="svg-text" x="670" y="57">driver</text>
  127. <text class="svg-sub" x="670" y="77">FDC · ATA · AHCI</text>
  128. <path class="svg-line blue" d="M270 61h67"/>
  129. <path class="svg-line blue" d="M330 55l7 6-7 6"/>
  130. <path class="svg-line accent" d="M575 61h67"/>
  131. <path class="svg-line accent" d="M635 55l7 6-7 6"/>
  132. <rect class="svg-box green" x="40" y="142" width="230" height="62" rx="9"/>
  133. <text class="svg-text" x="60" y="169">floppy.img</text>
  134. <text class="svg-sub" x="60" y="189">CHS + ISA DMA</text>
  135. <rect class="svg-box green" x="345" y="142" width="230" height="62" rx="9"/>
  136. <text class="svg-text" x="365" y="169">ide0 / ide0pN</text>
  137. <text class="svg-sub" x="365" y="189">PIO, legacy or native BARs</text>
  138. <rect class="svg-box green" x="650" y="142" width="230" height="62" rx="9"/>
  139. <text class="svg-text" x="670" y="169">sata0 / sata0pN</text>
  140. <text class="svg-sub" x="670" y="189">AHCI port index</text>
  141. <path class="svg-line" d="M175 92v42"/>
  142. <path class="svg-line" d="M169 126l6 7 6-7"/>
  143. <path class="svg-line" d="M460 92v42"/>
  144. <path class="svg-line" d="M454 126l6 7 6-7"/>
  145. <path class="svg-line" d="M765 92v42"/>
  146. <path class="svg-line" d="M759 126l6 7 6-7"/>
  147. </svg>
  148. <figcaption>
  149. <strong>One narrow waist.</strong> Filesystems and tools only see
  150. <code>struct blk_dev</code>. The floppy still needs IRQ 6, but ATA
  151. and AHCI are polled; a FAT operation takes <code>sys_fs_busy</code>
  152. so the scheduler does not switch away mid-transfer.
  153. </figcaption>
  154. </figure>
  155. <h3>Floppy</h3>
  156. <p>
  157. <span class="file">disk.c</span> drives the 8272-compatible FDC
  158. through ISA DMA channel 2, with the single-sector DMA buffer at
  159. <code>0x4000</code>. Retries handle the usual real-hardware flakiness.
  160. The second floppy slot can hold <code>root.img</code>.
  161. </p>
  162. <h3>PATA</h3>
  163. <p>
  164. <span class="file">ata.c</span> uses the legacy command block or the
  165. PCI IDE interface's native BARs. Multi-sector PIO waits for DRQ
  166. before every sector because drives drop it between sectors; it polls
  167. the command-block status rather than the alternate-status BAR, and
  168. falls back to single-sector commands when a bridge leaves DRQ pending.
  169. </p>
  170. <h3>SATA/AHCI</h3>
  171. <p>
  172. <span class="file">ahci.c</span> drives the first AHCI controller
  173. only, with no IRQs and no NCQ. It does COMRESET, IDENTIFY through the
  174. shared <code>ata_identify_parse()</code>, and READ/WRITE DMA EXT
  175. through a page-allocated bounce buffer. A disk added after boot needs
  176. a rescan; there is no COMRESET hotplug.
  177. </p>
  178. </section>
  179. <section id="usb">
  180. <h2>USB stack</h2>
  181. <p>
  182. <span class="file">usb.c</span> is controller-agnostic. It handles
  183. enumeration, descriptor parsing, hub recursion, bus scans, per-controller
  184. addresses, the hotplug watcher and interrupt-IN consumers. Each host
  185. controller implements the <code>usb_hcd_ops</code> vtable in
  186. <span class="file">usb_hcd.h</span>.
  187. </p>
  188. <figure class="figure">
  189. <svg viewBox="0 0 920 300" role="img" aria-labelledby="usb-title usb-desc">
  190. <title id="usb-title">USB controller topology</title>
  191. <desc id="usb-desc">EHCI handles high-speed root ports, UHCI and OHCI handle low and full speed devices, xHCI handles USB2 root ports. All feed the same USB core and HID layer.</desc>
  192. <rect class="svg-box accent" x="30" y="24" width="200" height="64" rx="9"/>
  193. <text class="svg-text" x="50" y="50">EHCI</text>
  194. <text class="svg-sub" x="50" y="70">high-speed root ports</text>
  195. <rect class="svg-box blue" x="252" y="24" width="200" height="64" rx="9"/>
  196. <text class="svg-text" x="272" y="50">UHCI</text>
  197. <text class="svg-sub" x="272" y="70">full/low speed · 1 instance</text>
  198. <rect class="svg-box blue" x="474" y="24" width="200" height="64" rx="9"/>
  199. <text class="svg-text" x="494" y="50">OHCI</text>
  200. <text class="svg-sub" x="494" y="70">full/low speed · up to 4</text>
  201. <rect class="svg-box green" x="696" y="24" width="194" height="64" rx="9"/>
  202. <text class="svg-text" x="716" y="50">xHCI</text>
  203. <text class="svg-sub" x="716" y="70">USB2 root ports only</text>
  204. <path class="svg-line accent" d="M130 88v40h330v28"/>
  205. <path class="svg-line blue" d="M352 88v68"/>
  206. <path class="svg-line blue" d="M574 88v68"/>
  207. <path class="svg-line green" d="M793 88v40H460v28"/>
  208. <rect class="svg-box" x="300" y="156" width="320" height="58" rx="9"/>
  209. <text class="svg-text" x="320" y="181">usb core</text>
  210. <text class="svg-sub" x="320" y="201">enumeration · hubs · hotplug · interrupt-IN slots</text>
  211. <path class="svg-line" d="M460 214v34"/>
  212. <path class="svg-line" d="M454 240l6 7 6-7"/>
  213. <rect class="svg-box" x="300" y="248" width="320" height="44" rx="9"/>
  214. <text class="svg-text" x="320" y="275">usbhid · keyboard + mouse</text>
  215. </svg>
  216. <figcaption>
  217. <strong>Companions are not optional.</strong> EHCI is scanned first
  218. so its port resets can hand non-high-speed devices back to a
  219. companion. There is no transaction translator: a low/full-speed
  220. device behind a high-speed hub is invisible to EHCI.
  221. </figcaption>
  222. </figure>
  223. <div class="table-wrap">
  224. <table>
  225. <thead>
  226. <tr><th>Controller</th><th>Transport</th><th>Instances</th><th>Implementation notes</th></tr>
  227. </thead>
  228. <tbody>
  229. <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>
  230. <tr><td>OHCI</td><td>PCI MMIO</td><td>up to 4</td><td>HCCA from the page allocator, static ED/TD sets, TDs start at <code>CC = NotAccessed</code>.</td></tr>
  231. <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>
  232. <tr><td>xHCI</td><td>PCI MMIO</td><td>—</td><td>USB2 root ports only; USB3 SuperSpeed devices are not handled.</td></tr>
  233. </tbody>
  234. </table>
  235. </div>
  236. <p>
  237. Hubs are class-9 devices: <code>usb.c</code> sets their configuration,
  238. powers every downstream port (honouring <code>bPwrOn2PwrGood</code>),
  239. resets and waits for <code>PORT_ENABLE</code>, then enumerates
  240. recursively. This is what makes the X201's internal PCH hubs work.
  241. Hotplug watches root ports; a device behind a hub is only found when a
  242. full scan runs (<code>lsusb</code> also bumps the USB generation so
  243. <code>usbhid</code> re-attaches).
  244. </p>
  245. </section>
  246. <section id="hid">
  247. <h2>Input</h2>
  248. <p>
  249. <span class="file">usbhid.c</span> gives every HID class-3 interface
  250. with an interrupt-IN endpoint one of the six USB interrupt slots. Boot
  251. interfaces (subclass 1, protocol 1/2) are used as-is; other class-3
  252. interfaces are classified by reading their HID report descriptor.
  253. Composite receivers and several devices can coexist; mouse reports
  254. from all slots are merged.
  255. </p>
  256. <ul>
  257. <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>
  258. <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>
  259. <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>
  260. <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>
  261. </ul>
  262. <p>
  263. <code>mouseinfo</code> shows the active backend and whether a USB
  264. keyboard is attached. Headless regression tests inject mouse motion
  265. and keys through QMP and verify the result with screen dumps.
  266. </p>
  267. </section>
  268. <section id="serial">
  269. <h2>Serial</h2>
  270. <p>
  271. <span class="file">serial.c</span> drives the 16550 at COM1, 115200
  272. 8N1, with an IRQ-driven receive ring buffer. It is used for the boot
  273. trace, the netlog mirror source, XMODEM transfers, the <code>dbg</code>
  274. monitor and the <code>KXE2</code> kexec receiver.
  275. </p>
  276. <p>
  277. The transmitter is polled, so a machine without a serial port still
  278. boots normally. <code>serial_puthex</code> and
  279. <code>serial_putdec</code> are the structured dump helpers used by
  280. drivers.
  281. </p>
  282. </section>
  283. <section id="sensors">
  284. <h2>Sensors, power &amp; thermals</h2>
  285. <ul>
  286. <li><strong>DTS.</strong> <span class="file">thermal.c</span> reads <code>IA32_THERM_STATUS</code> on an allowlist of Core/Core 2, Nehalem/Westmere and Bonnell models. TjMax comes from <code>IA32_TEMPERATURE_TARGET</code> on Nehalem and later; Bonnell uses a table.</li>
  287. <li><strong>IT87xx.</strong> <span class="file">it87.c</span> reads the Super I/O temperatures and fan tachometers on the ASUS AT3IONT-I. Nothing is written to fan control.</li>
  288. <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 ports <code>0x62/0x66</code>. It drains pending output bytes and uses bounded waits; nothing is written.</li>
  289. <li><strong>MTRRs.</strong> <span class="file">mtrr.c</span> manages write-combining ranges for the framebuffer and reports the effective mapping.</li>
  290. </ul>
  291. <p>
  292. <code>sensors</code> prints DTS values on the 90/100/125 °C scales,
  293. board sensors and EC registers; <code>power</code> prints ratios,
  294. effective MHz and C-state residency.
  295. </p>
  296. </section>
  297. <section id="panic">
  298. <h2>Panic screen</h2>
  299. <p>
  300. On a ring-0 fault, <span class="file">panic.c</span> draws straight
  301. into the framebuffer — bypassing the shadow buffer and the WM — and
  302. mirrors the same data to COM1 before halting. The banner includes the
  303. vector and error code, GPRs, control registers, current pid/name,
  304. uptime, instruction bytes and stack return-address candidates in the
  305. kernel image.
  306. </p>
  307. <p>
  308. Faults from ring 3 do not halt: the process is killed with a short
  309. message in its terminal and serial log. There is no interactive
  310. debugger on screen; the <code>dbg</code> kernel command drives a
  311. serial monitor instead.
  312. </p>
  313. </section>
  314. <section id="limits">
  315. <h2>Limits</h2>
  316. <ul>
  317. <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>
  318. <li><strong>EHCI.</strong> High-speed root ports only; no split transactions for low/full-speed devices behind a high-speed hub.</li>
  319. <li><strong>xHCI.</strong> USB2 root ports only; USB3 SuperSpeed devices are not handled.</li>
  320. <li><strong>HID.</strong> Report IDs are not handled, absolute pointers/tablets are ignored, and there is no wheel support.</li>
  321. <li><strong>AHCI.</strong> First controller only, no hotplug after boot, disks above 2 TB are clamped to 32-bit LBA.</li>
  322. <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>
  323. </ul>
  324. </section>
  325. <section id="sources">
  326. <h2>Source map</h2>
  327. <ul class="filelist">
  328. <li><code>pci.c</code>, <code>pci.h</code> — enumeration</li>
  329. <li><code>blkdev.c</code> — block registry</li>
  330. <li><code>disk.c</code> — floppy / DMA</li>
  331. <li><code>ata.c</code>, <code>ahci.c</code> — PATA/SATA</li>
  332. <li><code>usb.c</code>, <code>usb_hcd.h</code> — USB core</li>
  333. <li><code>uhci.c</code>, <code>ohci.c</code>, <code>ehci.c</code>, <code>xhci.c</code></li>
  334. <li><code>usbhid.c</code>, <code>mouse.c</code>, <code>io.c</code> — input</li>
  335. <li><code>serial.c</code>, <code>serial_ring_buf.c</code></li>
  336. <li><code>thermal.c</code>, <code>it87.c</code>, <code>tpec.c</code>, <code>mtrr.c</code></li>
  337. <li><code>panic.c</code>, <code>timer.S</code> — fatal exceptions</li>
  338. </ul>
  339. </section>
  340. </main>
  341. <footer class="site-footer">
  342. <div class="inner">
  343. <p><strong>NebOS 0.2.0</strong> · Architecture documentation · <a href="index.html">overview</a></p>
  344. <p>Maintain alongside <code>AGENTS.md</code> and the source files listed on each page.</p>
  345. </div>
  346. </footer>
  347. </body>
  348. </html>