drivers.html 28 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506
  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="#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="#rtc">Wall clock (RTC)</a></li>
  59. <li><a href="#panic">Panic screen</a></li>
  60. <li><a href="#limits">Limits</a></li>
  61. <li><a href="#sources">Source map</a></li>
  62. </ul>
  63. </nav>
  64. <section id="inventory">
  65. <h2>Driver inventory</h2>
  66. <p>
  67. Every driver in the tree is small enough to read in one sitting. The
  68. table below is the quickest way to find the one responsible for a
  69. device.
  70. </p>
  71. <div class="table-wrap">
  72. <table>
  73. <thead>
  74. <tr><th>Subsystem</th><th>Driver</th><th>Bus / access</th><th>Service model</th></tr>
  75. </thead>
  76. <tbody>
  77. <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>
  78. <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>
  79. <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>
  80. <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>
  81. <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>
  82. <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>
  83. <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>
  84. <tr><td>Touchpad</td><td><span class="file">i2c.c</span>, <span class="file">touchpad.c</span></td><td>LPSS DesignWare I2C, slave <code>0x15</code></td><td>Polled input register every 25 ms; no GPIO interrupt driver</td></tr>
  85. <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>
  86. <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>
  87. <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>
  88. <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>
  89. </tbody>
  90. </table>
  91. </div>
  92. </section>
  93. <section id="pci">
  94. <h2>PCI &amp; discovery</h2>
  95. <p>
  96. <span class="file">pci.c</span> walks bus/device/function and exposes
  97. BAR and capability access. The USB scan checks all functions: real
  98. PIIX3/PIIX4/VIA layouts put the USB function at 0:07.2 or 0:01.2, not
  99. 0:07.0. Controllers with unassigned BARs are ignored rather than
  100. driven at address zero.
  101. </p>
  102. <p>
  103. MMIO regions are mapped through <code>paging_map_mmio()</code>. PCI
  104. interrupts are disabled before touching MMIO, so every driver polls
  105. its own status registers. <code>lspci</code> lists every function;
  106. with a filter it prints BAR type, size and address details.
  107. </p>
  108. </section>
  109. <section id="storage">
  110. <h2>Storage</h2>
  111. <p>
  112. <span class="file">blkdev.c</span> is a small registry of block
  113. devices. Each device exposes sector read/write plus geometry; FAT,
  114. the format command and the installer sit above that interface and
  115. never talk to a controller directly. Devices are named
  116. <code>floppy0</code>, <code>ide0</code>, <code>sata0</code>,
  117. <code>mmc0</code>, <code>usb0</code> and so on; partitions append
  118. <code>p1</code>, <code>p2</code>.
  119. </p>
  120. <figure class="figure">
  121. <svg viewBox="0 0 920 246" role="img" aria-labelledby="storage-title storage-desc">
  122. <title id="storage-title">Storage software layers</title>
  123. <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>
  124. <rect class="svg-box blue" x="40" y="30" width="230" height="62" rx="9"/>
  125. <text class="svg-text" x="60" y="57">VFS · FAT · format · install</text>
  126. <text class="svg-sub" x="60" y="77">files, or a whole-image clone</text>
  127. <rect class="svg-box accent" x="345" y="30" width="230" height="62" rx="9"/>
  128. <text class="svg-text" x="365" y="57">blkdev registry</text>
  129. <text class="svg-sub" x="365" y="77">sector read / write + geometry</text>
  130. <rect class="svg-box" x="650" y="30" width="230" height="62" rx="9"/>
  131. <text class="svg-text" x="670" y="57">driver</text>
  132. <text class="svg-sub" x="670" y="77">FDC · ATA · AHCI · SDHCI · USB</text>
  133. <path class="svg-line blue" d="M270 61h67"/>
  134. <path class="svg-line blue" d="M330 55l7 6-7 6"/>
  135. <path class="svg-line accent" d="M575 61h67"/>
  136. <path class="svg-line accent" d="M635 55l7 6-7 6"/>
  137. <rect class="svg-box green" x="40" y="142" width="230" height="62" rx="9"/>
  138. <text class="svg-text" x="60" y="169">floppy.img</text>
  139. <text class="svg-sub" x="60" y="189">CHS + ISA DMA</text>
  140. <rect class="svg-box green" x="345" y="142" width="230" height="62" rx="9"/>
  141. <text class="svg-text" x="365" y="169">ide0 / ide0pN</text>
  142. <text class="svg-sub" x="365" y="189">PIO, legacy or native BARs</text>
  143. <rect class="svg-box green" x="650" y="142" width="230" height="62" rx="9"/>
  144. <text class="svg-text" x="670" y="169">sata0 · mmc0 · usb0</text>
  145. <text class="svg-sub" x="670" y="189">AHCI · SDHCI · USB MSC</text>
  146. <path class="svg-line" d="M175 92v42"/>
  147. <path class="svg-line" d="M169 126l6 7 6-7"/>
  148. <path class="svg-line" d="M460 92v42"/>
  149. <path class="svg-line" d="M454 126l6 7 6-7"/>
  150. <path class="svg-line" d="M765 92v42"/>
  151. <path class="svg-line" d="M759 126l6 7 6-7"/>
  152. </svg>
  153. <figcaption>
  154. <strong>One narrow waist.</strong> Filesystems and tools only see
  155. <code>struct blk_dev</code>. The floppy still needs IRQ 6, but ATA,
  156. AHCI, SDHCI and USB MSC are polled; a FAT operation takes a
  157. non-preemptible section and <code>format_busy</code> keeps a
  158. destructive format/install exclusive. The installer clones the
  159. MBR and every used sector of the source image.
  160. </figcaption>
  161. </figure>
  162. <h3>Floppy</h3>
  163. <p>
  164. <span class="file">disk.c</span> drives the 8272-compatible FDC
  165. through ISA DMA channel 2, with the single-sector DMA buffer at
  166. <code>0x4000</code>. Retries handle the usual real-hardware flakiness.
  167. The second floppy slot can hold <code>root.img</code>.
  168. </p>
  169. <h3>PATA</h3>
  170. <p>
  171. <span class="file">ata.c</span> uses the legacy command block or the
  172. PCI IDE interface's native BARs. Multi-sector PIO waits for DRQ
  173. before every sector because drives drop it between sectors; it polls
  174. the command-block status rather than the alternate-status BAR, and
  175. falls back to single-sector commands when a bridge leaves DRQ pending.
  176. </p>
  177. <h3>SATA/AHCI</h3>
  178. <p>
  179. <span class="file">ahci.c</span> drives the first AHCI controller
  180. only, with no IRQs and no NCQ. It does COMRESET, IDENTIFY through the
  181. shared <code>ata_identify_parse()</code>, and READ/WRITE DMA EXT
  182. through a page-allocated bounce buffer. A disk added after boot needs
  183. a rescan; there is no COMRESET hotplug.
  184. </p>
  185. <h3>eMMC/SDHCI</h3>
  186. <p>
  187. <span class="file">sdhci.c</span> drives the Intel Braswell MMC
  188. function at PCI <code>00:10.0</code> (<code>8086:2294</code>, class
  189. <code>0805</code>), the HP Chromebook's eMMC. It resets the SDHCI
  190. host, selects the 1.8 V rail and Host Control 2's 1.8 V signalling,
  191. runs a 400 kHz initialization clock, then CMD0/1/2/3/7/16 and CMD8
  192. to read EXT_CSD (<code>SEC_COUNT</code> at 212,
  193. <code>CACHE_SIZE</code> at 249), and switches to a 25 MHz data clock.
  194. Sector I/O is CMD17/CMD24 through the polled PIO buffer port at
  195. 1-bit/25 MHz; there is no DMA, IRQ, bus-width/high-speed switch or
  196. hotplug. The read/write loops yield every 32 sectors so a long
  197. format does not starve the window manager. The eMMC appears as
  198. <code>mmc0</code>, and <code>format mmc0</code> writes an MBR + FAT
  199. partition exactly like an IDE/SATA disk. The write path flushes the
  200. card cache with CMD6 <code>FLUSH_CACHE</code> when EXT_CSD reports
  201. one.
  202. </p>
  203. </section>
  204. <section id="usb">
  205. <h2>USB stack</h2>
  206. <p>
  207. <span class="file">usb.c</span> is controller-agnostic. It handles
  208. enumeration, descriptor parsing, hub recursion, bus scans, per-controller
  209. addresses, the hotplug watcher and interrupt-IN consumers. Each host
  210. controller implements the <code>usb_hcd_ops</code> vtable in
  211. <span class="file">usb_hcd.h</span>.
  212. </p>
  213. <figure class="figure">
  214. <svg viewBox="0 0 920 300" role="img" aria-labelledby="usb-title usb-desc">
  215. <title id="usb-title">USB controller topology</title>
  216. <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, which drives HID input and USB mass storage.</desc>
  217. <rect class="svg-box accent" x="30" y="24" width="200" height="64" rx="9"/>
  218. <text class="svg-text" x="50" y="50">EHCI</text>
  219. <text class="svg-sub" x="50" y="70">high-speed root ports</text>
  220. <rect class="svg-box blue" x="252" y="24" width="200" height="64" rx="9"/>
  221. <text class="svg-text" x="272" y="50">UHCI</text>
  222. <text class="svg-sub" x="272" y="70">full/low speed · 1 instance</text>
  223. <rect class="svg-box blue" x="474" y="24" width="200" height="64" rx="9"/>
  224. <text class="svg-text" x="494" y="50">OHCI</text>
  225. <text class="svg-sub" x="494" y="70">full/low speed · up to 4</text>
  226. <rect class="svg-box green" x="696" y="24" width="194" height="64" rx="9"/>
  227. <text class="svg-text" x="716" y="50">xHCI</text>
  228. <text class="svg-sub" x="716" y="70">USB2 root ports only</text>
  229. <path class="svg-line accent" d="M130 88v40h330v28"/>
  230. <path class="svg-line blue" d="M352 88v68"/>
  231. <path class="svg-line blue" d="M574 88v68"/>
  232. <path class="svg-line green" d="M793 88v40H460v28"/>
  233. <rect class="svg-box" x="300" y="156" width="320" height="58" rx="9"/>
  234. <text class="svg-text" x="320" y="181">usb core</text>
  235. <text class="svg-sub" x="320" y="201">enumeration · hubs · hotplug · interrupt-IN slots</text>
  236. <path class="svg-line" d="M460 214v34"/>
  237. <path class="svg-line" d="M454 240l6 7 6-7"/>
  238. <rect class="svg-box" x="300" y="248" width="320" height="50" rx="9"/>
  239. <text class="svg-text" x="320" y="266">usbhid · keyboard + mouse</text>
  240. <text class="svg-text" x="320" y="286">usbmsc · mass storage</text>
  241. </svg>
  242. <figcaption>
  243. <strong>Companions are not optional.</strong> EHCI is scanned first
  244. so its port resets can hand non-high-speed devices back to a
  245. companion. There is no transaction translator: a low/full-speed
  246. device behind a high-speed hub is invisible to EHCI.
  247. </figcaption>
  248. </figure>
  249. <div class="table-wrap">
  250. <table>
  251. <thead>
  252. <tr><th>Controller</th><th>Transport</th><th>Instances</th><th>Implementation notes</th></tr>
  253. </thead>
  254. <tbody>
  255. <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>
  256. <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>
  257. <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>
  258. <tr><td>xHCI</td><td>PCI MMIO</td><td>—</td><td>USB2 root ports only; USB3 SuperSpeed devices are not handled. Halts and waits for <code>HCH</code> around <code>HCRST</code>; EP0 max packet comes from the port speed; EP0 stages are encoded as one TD per stage (EDK2 style) because chained control TDs stall on Braswell.</td></tr>
  259. </tbody>
  260. </table>
  261. </div>
  262. <p>
  263. Hubs are class-9 devices: <code>usb.c</code> sets their configuration,
  264. powers every downstream port (honouring <code>bPwrOn2PwrGood</code>),
  265. resets and waits for <code>PORT_ENABLE</code>, then enumerates
  266. recursively. This is what makes the X201's internal PCH hubs work.
  267. Hotplug watches root ports; a device behind a hub is only found when a
  268. full scan runs (<code>lsusb</code> also bumps the USB generation so
  269. <code>usbhid</code> re-attaches).
  270. </p>
  271. <h3>Mass storage</h3>
  272. <p>
  273. <span class="file">usbmsc.c</span> is a device-level probe alongside
  274. the ASIX Ethernet driver. It claims an interface with class 8,
  275. subclass 6 and protocol 0x50, parses its bulk IN/OUT endpoints and
  276. identifies the disk with SCSI INQUIRY + READ CAPACITY. Commands use
  277. Bulk-Only Transport with LUN 0 and 512-byte blocks: READ(10),
  278. WRITE(10), SYNCHRONIZE CACHE and a BOT reset/endpoint-halt recovery.
  279. Present devices are registered as <code>usb0..</code>
  280. (<code>BLK_USB</code>) by <code>blk_scan()</code>, so
  281. <code>storage</code>, the VFS, <code>format</code> and
  282. <code>install</code> can use them.
  283. </p>
  284. <p>
  285. Bulk transfers exist on EHCI and xHCI only; a mass-storage device on
  286. a UHCI/OHCI companion is left unclaimed, and the xHCI driver does not
  287. drive USB3 SuperSpeed ports. This is what makes the installer's
  288. <code>usb0</code> source possible on the supported hardware: it reads
  289. the live image from the stick and clones its used sectors to the
  290. target.
  291. </p>
  292. </section>
  293. <section id="hid">
  294. <h2>Input</h2>
  295. <p>
  296. <span class="file">usbhid.c</span> gives every HID class-3 interface
  297. with an interrupt-IN endpoint one of the six USB interrupt slots. Boot
  298. interfaces (subclass 1, protocol 1/2) are used as-is; other class-3
  299. interfaces are classified by reading their HID report descriptor.
  300. Composite receivers and several devices can coexist; mouse reports
  301. from all slots are merged.
  302. </p>
  303. <ul>
  304. <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>
  305. <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>
  306. <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>
  307. <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>
  308. </ul>
  309. <p>
  310. <code>mouseinfo</code> shows the active backend and whether a USB
  311. keyboard is attached. Headless regression tests inject mouse motion
  312. and keys through QMP and verify the result with screen dumps.
  313. </p>
  314. <h3>I2C touchpad</h3>
  315. <p>
  316. The HP Chromebook 11 G5 EE has no PS/2 port: its Elan touchpad is a
  317. HID-over-I2C device on LPSS I2C6. The LPSS I2C functions are hidden
  318. from PCI in ACPI mode, so <span class="file">touchpad.c</span> scans
  319. the two firmware BAR windows for a DesignWare component and
  320. <span class="file">i2c.c</span> drives that controller in fast mode,
  321. polled and without interrupts.
  322. </p>
  323. <ul>
  324. <li><strong>Probe.</strong> Slave address <code>0x15</code>: reset
  325. (<code>0x0100</code>), consume the 2-byte acknowledgement, read the
  326. HID descriptor, select absolute mode (<code>0x0300 = 1</code>) and
  327. wake the device (<code>0x0800</code>). Resetting last leaves it
  328. silent until the next power cycle.</li>
  329. <li><strong>Reports.</strong> The Elan vendor report <code>0x5D</code>
  330. carries a finger bitmask and five bytes per finger (X/Y high bits, X
  331. low, Y low, size, pressure). Successive absolute positions become
  332. PS/2 deltas; the clickpad bit becomes the left button.</li>
  333. <li><strong>Polling.</strong> The report GPIO has no driver yet, so
  334. the input register is read every 25 ms. Back-to-back reads stall the
  335. device, which is why the poll is throttled rather than run flat
  336. out.</li>
  337. <li><strong>Discovery.</strong> <code>touchpad</code> prints the
  338. probe result; <code>mouseinfo</code> lists the Elan vendor/product
  339. ID next to the PS/2 and USB backends.</li>
  340. </ul>
  341. </section>
  342. <section id="serial">
  343. <h2>Serial</h2>
  344. <p>
  345. <span class="file">serial.c</span> drives the 16550 at COM1, 115200
  346. 8N1, with an IRQ-driven receive ring buffer. It is used for the boot
  347. trace, the netlog mirror source, the <code>dbg</code> monitor and the
  348. <code>KXE2</code> kexec receiver.
  349. </p>
  350. <p>
  351. The transmitter is polled, so a machine without a serial port still
  352. boots normally. <code>serial_puthex</code> and
  353. <code>serial_putdec</code> are the structured dump helpers used by
  354. drivers.
  355. </p>
  356. </section>
  357. <section id="sensors">
  358. <h2>Sensors, power &amp; thermals</h2>
  359. <ul>
  360. <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, 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.</li>
  361. <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>
  362. <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>
  363. <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>
  364. <li><strong>MTRRs.</strong> <span class="file">mtrr.c</span> manages write-combining ranges for the framebuffer and reports the effective mapping.</li>
  365. </ul>
  366. <p>
  367. <code>sensors</code> prints DTS values on the 90/100/125 °C scales,
  368. board sensors and both EC types; <code>powerinfo</code> prints the
  369. source (<code>thinkpad</code> or <code>chrome ec</code>), the AC
  370. adapter, battery model/manufacturer/serial, capacities, voltage,
  371. rate and cycle count through <code>SYS_POWER_INFO</code>;
  372. <code>power</code> prints ratios, effective MHz and C-state hints.
  373. The WM top bar shows the AC adapter state and the first present
  374. battery with a valid percentage next to the CPU temperature on
  375. both ThinkPads and Chromebooks; machines without an EC show neither.
  376. </p>
  377. </section>
  378. <section id="rtc">
  379. <h2>Wall clock (RTC)</h2>
  380. <p>
  381. <span class="file">rtc.c</span> talks to the MC146818-compatible
  382. CMOS clock through ports <code>0x70/0x71</code>. Reads honour the
  383. register-B BCD/binary and 12/24-hour modes, retry when the
  384. update-in-progress bit is set, and decode the hour's PM flag. The
  385. RTC only stores a two-digit year, so the kernel expands it over a
  386. 1970–2069 window (70–99 → 1900s, 00–69 → 2000s); a board whose
  387. dead battery left 1980 or 1990 therefore reads correctly instead of
  388. being pushed a century forward. Writes validate the calendar (leap
  389. years included), raise the register-B SET bit, preserve the mode
  390. bits and write the computed weekday. On ACPI machines the FADT
  391. century register (offset 108, normally CMOS <code>0x32</code>) is
  392. written as well, so the firmware and other operating systems see
  393. the intended century; boards without ACPI get no arbitrary NVRAM
  394. write.
  395. </p>
  396. <p>
  397. <code>SYS_RTC_GET</code>/<code>SYS_RTC_SET</code> (104/105) expose
  398. the full <code>struct sys_datetime</code>; the older
  399. <code>SYS_RTC_HMS</code>/<code>SYS_RTC_DATETIME</code> calls remain
  400. the small read-only views. The WM’s top-bar date/time is a click
  401. target that opens <code>bin/settime</code>; its <em>Sync NTP</em>
  402. button fetches UTC through <code>SYS_NTP_SYNC</code> (106), backed
  403. by the SNTP client in <span class="file">ntp.c</span>, and writes
  404. it with <code>SYS_RTC_SET</code>. The <code>date</code> command
  405. prints the same clock in the classic Linux format.
  406. </p>
  407. </section>
  408. <section id="panic">
  409. <h2>Panic screen</h2>
  410. <p>
  411. On a ring-0 fault, <span class="file">panic.c</span> draws straight
  412. into the framebuffer — bypassing the shadow buffer and the WM — and
  413. mirrors the same data to COM1 before halting. The banner includes the
  414. vector and error code, GPRs, control registers, current pid/name,
  415. uptime, instruction bytes and stack return-address candidates in the
  416. kernel image.
  417. </p>
  418. <p>
  419. Faults from ring 3 do not halt: the process is killed with a short
  420. message in its terminal and serial log. There is no interactive
  421. debugger on screen; the <code>dbg</code> kernel command drives a
  422. serial monitor instead.
  423. </p>
  424. </section>
  425. <section id="limits">
  426. <h2>Limits</h2>
  427. <ul>
  428. <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>
  429. <li><strong>EHCI.</strong> High-speed root ports only; no split transactions for low/full-speed devices behind a high-speed hub.</li>
  430. <li><strong>xHCI.</strong> USB2 root ports only; USB3 SuperSpeed devices are not handled.</li>
  431. <li><strong>HID.</strong> Report IDs are not handled, absolute pointers/tablets are ignored, and there is no wheel support.</li>
  432. <li><strong>AHCI.</strong> First controller only, no hotplug after boot, disks above 2 TB are clamped to 32-bit LBA.</li>
  433. <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>
  434. <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>
  435. <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>
  436. <li><strong>Suspend.</strong> There is no S0ix/suspend path; package C-states and the EC sleep handshake remain firmware-managed.</li>
  437. </ul>
  438. </section>
  439. <section id="sources">
  440. <h2>Source map</h2>
  441. <ul class="filelist">
  442. <li><code>pci.c</code>, <code>pci.h</code> — enumeration</li>
  443. <li><code>blkdev.c</code> — block registry</li>
  444. <li><code>sdhci.c</code>, <code>sdhci.h</code> — Intel Braswell eMMC</li>
  445. <li><code>disk.c</code> — floppy / DMA</li>
  446. <li><code>ata.c</code>, <code>ahci.c</code> — PATA/SATA</li>
  447. <li><code>usb.c</code>, <code>usb_hcd.h</code> — USB core</li>
  448. <li><code>uhci.c</code>, <code>ohci.c</code>, <code>ehci.c</code>, <code>xhci.c</code></li>
  449. <li><code>usbmsc.c</code>, <code>usbmsc.h</code> — USB BOT/SCSI mass storage</li>
  450. <li><code>install.c</code> — live-image clone installer</li>
  451. <li><code>usbhid.c</code>, <code>mouse.c</code>, <code>io.c</code> — input</li>
  452. <li><code>i2c.c</code>, <code>i2c.h</code> — DesignWare/LPSS I2C master</li>
  453. <li><code>touchpad.c</code>, <code>touchpad.h</code> — Elan HID-over-I2C touchpad</li>
  454. <li><code>serial.c</code>, <code>serial_ring_buf.c</code></li>
  455. <li><code>thermal.c</code>, <code>it87.c</code>, <code>tpec.c</code>, <code>ec.c</code>, <code>cros_ec.c</code>, <code>power_src.c</code>, <code>mtrr.c</code></li>
  456. <li><code>rtc.c</code> — CMOS wall clock read/write</li>
  457. <li><code>panic.c</code>, <code>timer.S</code> — fatal exceptions</li>
  458. </ul>
  459. </section>
  460. </main>
  461. <footer class="site-footer">
  462. <div class="inner">
  463. <p><strong>NebOS 0.2.0</strong> · Architecture documentation · <a href="index.html">overview</a></p>
  464. <p>Maintain alongside <code>AGENTS.md</code> and the source files listed on each page.</p>
  465. </div>
  466. </footer>
  467. </body>
  468. </html>