drivers.html 26 KB

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