userland.html 28 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427
  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>Userland | NebOS Architecture</title>
  7. <meta name="description" content="NebOS userland: ring-3 address space, ELF loading, the syscall ABI, the shell and PATH dispatch, the 45-command pack, GUI applications and the browser.">
  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">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" aria-current="page">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">Userland</p>
  34. <h1>Commands are ELFs. The shell is a dispatcher.</h1>
  35. <p class="lede">
  36. Ring-3 programs are static ELFs linked at <code>0x40000000</code>.
  37. The shell resolves a command name against builtins, the per-terminal
  38. PATH and the kernel command registry, then spawns it with one
  39. argument string. The command pack supplies 45 PATH commands by default.
  40. </p>
  41. <div class="meta">
  42. <span class="pill">int 0x80</span>
  43. <span class="pill">one string argument</span>
  44. <span class="pill">45 PATH commands</span>
  45. <span class="pill">8 TTYs · 8 windows</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="#model">Ring-3 model</a></li>
  52. <li><a href="#libc">Ring-3 libc</a></li>
  53. <li><a href="#spawn">Spawn path</a></li>
  54. <li><a href="#syscalls">Syscall ABI</a></li>
  55. <li><a href="#shell">Shell &amp; PATH</a></li>
  56. <li><a href="#registry">Kernel commands</a></li>
  57. <li><a href="#pack">Command pack</a></li>
  58. <li><a href="#apps">GUI applications</a></li>
  59. <li><a href="#browser">Browser</a></li>
  60. <li><a href="#sources">Source map</a></li>
  61. </ul>
  62. </nav>
  63. <section id="model">
  64. <h2>Ring-3 model</h2>
  65. <p>
  66. A user process gets a page directory cloned from the kernel identity
  67. map, a 4 MB image/stack window at <code>0x40000000</code>, an optional
  68. 4 MB canvas at <code>0x50000000</code> and a growable heap at
  69. <code>0x60000000</code>. The kernel remains mapped because paging is
  70. identity-mapped; this is isolation in privilege level only, not a
  71. separate address space.
  72. </p>
  73. <ul>
  74. <li><strong>Optional libc.</strong> Commands include <span class="file">ucmd_lib.h</span> for syscall wrappers; commands that need allocation or standard string/stdlib functions link the in-tree <span class="file">libc.a</span>.</li>
  75. <li><strong>One argument.</strong> The shell passes the raw remainder of the line as a C string at the top of the user stack; <code>_start(const char *arg)</code> needs no crt0.</li>
  76. <li><strong>Inherited context.</strong> Each process inherits the spawning terminal's cwd and TTY id; the file syscalls resolve relative paths against the PCB cwd.</li>
  77. <li><strong>Page-fault policy.</strong> A ring-3 fault kills the process and prints a short message; it does not halt the kernel.</li>
  78. </ul>
  79. <div class="note">
  80. <p><strong>Not a sandbox.</strong> Because physical and virtual addresses
  81. are identical and the kernel is mapped, a ring-3 bug can read or write
  82. any mapped kernel page. The privilege boundary protects against
  83. accidental corruption from ordinary code, not against malicious code.</p>
  84. </div>
  85. </section>
  86. <section id="libc">
  87. <h2>Ring-3 libc</h2>
  88. <p>
  89. <span class="file">libc.a</span> is optional: the Makefile links it
  90. only into commands that reference it, and the archive plus
  91. <code>--gc-sections</code> keeps unused members and functions out of
  92. the legacy command pack. The headers live in
  93. <span class="file">libc/include/</span> and cover
  94. <code>stddef</code>, <code>stdint</code>, <code>stdarg</code>,
  95. <code>stdlib</code>, <code>string</code>, <code>ctype</code>,
  96. <code>assert</code>, <code>setjmp</code>, <code>errno</code>,
  97. <code>stdio</code>, <code>math</code>, <code>time</code>,
  98. <code>sys/time</code>, <code>sys/types</code>, <code>float</code>,
  99. <code>limits</code>, <code>inttypes</code>, <code>alloca</code>
  100. and the OS-specific <code>ucmd_heap.h</code>.
  101. </p>
  102. <ul>
  103. <li><strong>malloc.</strong> Boundary-tag blocks, first-fit free
  104. list, immediate coalescing, 16-byte alignment. The heap maps 64 KB
  105. on first use and grows in page-rounded steps with 64 KB slack up to
  106. the 32 MB <code>SYS_MEM_*</code> arena cap; <code>calloc</code>
  107. zeroes and <code>realloc</code> grows in place when the next block
  108. is free.</li>
  109. <li><strong>heap_reset.</strong> Discards every allocation and
  110. unmaps the whole arena. Page-scoped programs such as the browser
  111. use it on navigation instead of tracking individual frees.</li>
  112. <li><strong>Ownership.</strong> Commands allocate through libc
  113. <code>malloc</code>; the <code>SYS_MEM_ALLOC/GROW/FREE</code>
  114. syscalls are the backend in <span class="file">libc/ucmd_mem.c</span>
  115. and are not called by application code.</li>
  116. <li><strong>stdio.</strong> <code>printf</code>,
  117. <code>snprintf</code>, <code>sprintf</code> and
  118. <code>vfprintf</code> share an exact decimal float formatter
  119. (<code>%f/%e/%g</code>, width/precision), and
  120. <code>fopen("rb")</code> provides read-only whole-file
  121. <code>FILE</code> objects with <code>fread</code>/<code>fseek</code>/
  122. <code>ftell</code>/<code>fclose</code>. stdout and stderr are
  123. console streams; stdin is EOF. There is no kernel fd layer yet: the
  124. <code>stdio_file.c</code> TODO records the future
  125. <code>SYS_OPEN/READ/WRITE/LSEEK/CLOSE</code> replacement.</li>
  126. <li><strong>time.</strong> <code>time</code>, <code>gmtime</code>,
  127. <code>localtime</code>, <code>mktime</code>, <code>strftime</code>,
  128. <code>gettimeofday</code>/<code>settimeofday</code> and
  129. <code>clock_gettime</code> use <code>SYS_RTC_GET</code>/<code>SET</code>.
  130. <code>time_t</code> is 64-bit, local time is UTC-only, and the RTC's
  131. 1970-2069 range is enforced.</li>
  132. <li><strong>math.</strong> The full MuJS set is provided with x87
  133. double arithmetic: <code>sqrt</code>, <code>pow</code>,
  134. <code>exp</code>/<code>log</code>, trig, <code>floor</code>/<code>ceil</code>/
  135. <code>round</code>, <code>fmod</code>, <code>ldexp</code>/
  136. <code>frexp</code> and the IEEE predicates. It is a compact
  137. double-rounding implementation, not a full fdlibm.</li>
  138. <li><strong>Limits.</strong> No threads or locking, no
  139. <code>free()</code>-to-page unmap, and requests near 32 MB fail
  140. because headers are charged against the same arena. The file layer
  141. is read-only and whole-file (4 MB cap); writable files and streaming
  142. need the kernel fd layer. There is no timezone database and no
  143. <code>long double</code>/<code>%a</code> support.</li>
  144. <li><strong>Tests.</strong> <code>make test-libc</code> covers the
  145. malloc arena, format/dtoa, math, 64-bit division helpers and
  146. <code>setjmp</code>/<code>longjmp</code> on the host.</li>
  147. </ul>
  148. </section>
  149. <section id="spawn">
  150. <h2>Spawn path</h2>
  151. <figure class="figure">
  152. <svg viewBox="0 0 920 232" role="img" aria-labelledby="spawn-title spawn-desc">
  153. <title id="spawn-title">Command spawn path</title>
  154. <desc id="spawn-desc">A shell line is matched against builtins, then the PATH, then the kernel registry. A PATH hit loads the ELF through the VFS and creates a ring-3 process; a kernel registry hit spawns a kernel thread.</desc>
  155. <rect class="svg-box" x="20" y="24" width="160" height="58" rx="9"/>
  156. <text class="svg-text" x="38" y="49">shell line</text>
  157. <text class="svg-sub" x="38" y="69">word + remainder</text>
  158. <rect class="svg-box blue" x="216" y="24" width="160" height="58" rx="9"/>
  159. <text class="svg-text" x="234" y="49">builtins</text>
  160. <text class="svg-sub" x="234" y="69">cd · path · help · clear</text>
  161. <rect class="svg-box accent" x="412" y="24" width="180" height="58" rx="9"/>
  162. <text class="svg-text" x="430" y="49">PATH lookup</text>
  163. <text class="svg-sub" x="430" y="69">/ramfs/bin by default</text>
  164. <rect class="svg-box" x="628" y="24" width="270" height="58" rx="9"/>
  165. <text class="svg-text" x="646" y="49">kernel registry</text>
  166. <text class="svg-sub" x="646" y="69">privileged / inline commands</text>
  167. <path class="svg-line" d="M180 53h24"/>
  168. <path class="svg-line" d="M196 47l7 6-7 6"/>
  169. <path class="svg-line" d="M376 53h24"/>
  170. <path class="svg-line" d="M392 47l7 6-7 6"/>
  171. <path class="svg-line" d="M592 53h24"/>
  172. <path class="svg-line" d="M608 47l7 6-7 6"/>
  173. <rect class="svg-box green" x="216" y="146" width="376" height="58" rx="9"/>
  174. <text class="svg-text" x="236" y="171">VFS load → process_create_user</text>
  175. <text class="svg-sub" x="236" y="191">ELF segments · page directory · 8-page stack · arg</text>
  176. <rect class="svg-box amber" x="628" y="146" width="270" height="58" rx="9"/>
  177. <text class="svg-text" x="646" y="171">kernel process</text>
  178. <text class="svg-sub" x="646" y="191">ring 0 · pinned to the BSP</text>
  179. <path class="svg-line accent" d="M502 82v54"/>
  180. <path class="svg-line accent" d="M496 128l6 7 6-7"/>
  181. <path class="svg-line" d="M763 82v54"/>
  182. <path class="svg-line" d="M757 128l6 7 6-7"/>
  183. </svg>
  184. <figcaption>
  185. <strong>A packed command can shadow a kernel command.</strong>
  186. The PATH is searched before the kernel registry, so a new
  187. <code>bin/&lt;name&gt;</code> changes behaviour without editing the
  188. kernel. Builtins are handled inline, before either lookup.
  189. </figcaption>
  190. </figure>
  191. </section>
  192. <section id="syscalls">
  193. <h2>Syscall ABI</h2>
  194. <p>
  195. The gate is <code>int 0x80</code>. <code>eax</code> carries the
  196. number, <code>ebx</code>/<code>ecx</code>/<code>edx</code> the first
  197. three arguments, and the negative <code>SYS_E*</code> codes are
  198. stable. The wrappers in <span class="file">ucmd_lib.h</span> cover
  199. zero to three arguments.
  200. </p>
  201. <div class="table-wrap">
  202. <table>
  203. <thead>
  204. <tr><th>Group</th><th>Numbers</th><th>Purpose</th></tr>
  205. </thead>
  206. <tbody>
  207. <tr><td>Console &amp; time</td><td>1–4, 56, 69, 104–105</td><td>putstr, ticks, sleep, exit, RTC time/date get/set</td></tr>
  208. <tr><td>Files</td><td>5–11, 48, 98</td><td>whole-file read/write, list, unlink, mkdir/rmdir, mounts, cwd, stat</td></tr>
  209. <tr><td>System info</td><td>12–16, 49–51, 91–92, 102–103, 107</td><td>memory, E820, mouse, storage, blkdev, procinfo, cursor, CPU temp, sensors, EC sensors, Chrome EC sensors, AC/battery</td></tr>
  210. <tr><td>Network</td><td>17–47, 106</td><td>NIC config/acquire, raw frames, DHCP/DNS/NTP, TCP client, ARP, cwd</td></tr>
  211. <tr><td>Window &amp; WM</td><td>55, 57–72, 80, 83–87</td><td>key poll, WM attach/info/map/present/create_term, window create/present/input/resize</td></tr>
  212. <tr><td>Process &amp; memory</td><td>73–79, 81, 88–90</td><td>TTY, spawn, alive, kill, chdir, scheduler info, heap alloc/grow/free</td></tr>
  213. <tr><td>TCP server</td><td>93–97, 99–101</td><td>listen, accept, server recv/send/close, peer, speed, MAC set</td></tr>
  214. </tbody>
  215. </table>
  216. </div>
  217. <p>
  218. The file service is whole-file, not stream-oriented. The network
  219. service has a single TCP connection and one NIC owner. There is no
  220. <code>fork</code>, <code>exec</code> or shared memory: a command
  221. either runs as its own process from an ELF or calls a kernel command.
  222. </p>
  223. </section>
  224. <section id="shell">
  225. <h2>Shell &amp; PATH</h2>
  226. <p>
  227. The windowed shell is <span class="file">ucmd_term.c</span>; the
  228. kernel-side <span class="file">terminal.c</span> holds the privileged
  229. command registry used through <code>SYS_SPAWN_KCMD</code>. There is
  230. no kernel terminal fallback; the WM spawns the first terminal once
  231. storage is ready. Each terminal has a current working directory and
  232. a PATH (default <code>/ramfs/bin</code>). Pressing Tab completes
  233. builtin and PATH names; <code>help</code> lists both.
  234. </p>
  235. <ul>
  236. <li><strong>Dispatch order.</strong> Builtins → PATH file → kernel command. A PATH hit loads the ELF through the VFS and spawns it as ring 3.</li>
  237. <li><strong>Builtins.</strong> <code>cd</code>, <code>path</code>, <code>help</code>, <code>clear</code>; the ring-3 shell also handles <code>ps</code> and <code>kill</code> inline. <code>bootlog</code> is a kernel command.</li>
  238. <li><strong>Arguments.</strong> The raw remainder of the line is passed verbatim; commands parse their own flags.</li>
  239. <li><strong>Working directory.</strong> The prompt shows <code>[dir] &gt;</code>; <code>cd</code> changes only the current terminal's cwd, and spawned commands inherit it.</li>
  240. <li><strong>Windows.</strong> A window receives keys through its window key queue (<code>SYS_WIN_KEY_WAIT</code>) or the generic <code>SYS_KEY_POLL</code>; closing the window kills its owner process.</li>
  241. </ul>
  242. </section>
  243. <section id="registry">
  244. <h2>Kernel commands</h2>
  245. <p>
  246. These commands must run in ring 0 or inline in the shell; they are not
  247. files in the pack. The split keeps privileged hardware access out of
  248. ring 3 while most user-facing tools remain replaceable ELFs.
  249. </p>
  250. <div class="table-wrap">
  251. <table>
  252. <thead>
  253. <tr><th>Group</th><th>Commands</th></tr>
  254. </thead>
  255. <tbody>
  256. <tr><td>Shell</td><td><code>cd</code> <code>path</code> <code>help</code> <code>clear</code> <code>bootlog</code></td></tr>
  257. <tr><td>Process / scheduler</td><td><code>ps</code> <code>sched</code> <code>renice</code> <code>kill</code> <code>idle</code> <code>cpufreq</code> <code>power</code></td></tr>
  258. <tr><td>Hardware / debug</td><td><code>display</code> <code>gfxbench</code> <code>lsusb</code> <code>lspci</code> <code>peek</code> <code>poke</code> <code>format</code> <code>install</code> <code>dbg</code> <code>serial</code></td></tr>
  259. <tr><td>Network control</td><td><code>netdev</code></td></tr>
  260. <tr><td>Boot / power</td><td><code>reboot</code> <code>poweroff</code> <code>kexec</code></td></tr>
  261. </tbody>
  262. </table>
  263. </div>
  264. <p>
  265. <code>format &lt;device&gt; [size]</code> creates a FAT filesystem.
  266. <code>install &lt;target&gt; [source]</code> clones the live NebOS
  267. image to a target disk: it auto-detects a source whose MBR and LBA-63
  268. boot sector carry the NebOS signature (preferring <code>usb0</code>),
  269. copies the image's used sectors, writes the MBR last and verifies the
  270. result. It installs the flashed image, so both the BIOS and UEFI boot
  271. paths are cloned as-is.
  272. </p>
  273. </section>
  274. <section id="pack">
  275. <h2>Command pack</h2>
  276. <p>
  277. The pack is built from the <code>UCMDS</code> list in the Makefile as
  278. <code>bin/&lt;name&gt;</code>, plus <code>hello</code> and the real
  279. <code>browser.app</code> and <code>gallery.app</code>. It is mounted
  280. read-only at <code>/ramfs</code>; the shell's default PATH points at
  281. <code>/ramfs/bin</code>.
  282. </p>
  283. <div class="grid">
  284. <div class="card">
  285. <h3>Files &amp; text</h3>
  286. <p><code>ls</code> <code>cat</code> <code>save</code> <code>rm</code> <code>mkdir</code> <code>rmdir</code> <code>edit</code> <code>files</code> <code>view</code></p>
  287. </div>
  288. <div class="card">
  289. <h3>System</h3>
  290. <p><code>cpuinfo</code> <code>meminfo</code> <code>storage</code> <code>top</code> <code>mouseinfo</code> <code>touchpad</code> <code>sensors</code> <code>powerinfo</code> <code>date</code> <code>spin</code> <code>clock</code> <code>colors</code></p>
  291. </div>
  292. <div class="card">
  293. <h3>Network</h3>
  294. <p><code>netinfo</code> <code>netip</code> <code>netdns</code> <code>host</code> <code>dhcp</code> <code>ping</code> <code>pong</code> <code>netsend</code> <code>netrecv</code> <code>netlog</code> <code>netconsole</code> <code>netregs</code> <code>netloop</code> <code>netreset</code> <code>net100</code> <code>netmac</code> <code>curl</code> <code>websrv</code></p>
  295. </div>
  296. <div class="card">
  297. <h3>GUI</h3>
  298. <p><code>wm</code> <code>term</code> <code>files</code> <code>view</code> <code>mines</code> <code>solitaire</code> <code>gallery</code> <code>browser</code> <code>clock</code> <code>colors</code> <code>settime</code></p>
  299. </div>
  300. </div>
  301. <p>
  302. The launchers <code>bin/browser</code> and <code>bin/gallery</code>
  303. forward their argument and cwd, and prefer a development copy under
  304. <code>/share</code> (<code>BROWSER</code> or <code>GALLERY</code>)
  305. before the pack copy and the FAT fallback on <code>root.img</code>.
  306. This lets <code>make browser-dev</code> and <code>make gallery-dev</code>
  307. update an app without rebuilding the pack.
  308. </p>
  309. </section>
  310. <section id="apps">
  311. <h2>GUI applications</h2>
  312. <ul>
  313. <li><strong>files</strong> — browser for the VFS; opens text in <code>edit</code>, images in <code>view</code>, HTML in <code>browser</code>. First user of ngui.</li>
  314. <li><strong>gallery</strong> — live widget and primitive showcase; the real app ships in the pack.</li>
  315. <li><strong>solitaire</strong> — Klondike with drag-and-drop, scoring and a win animation.</li>
  316. <li><strong>mines</strong> — second ngui canvas app; shares the toolkit and event model.</li>
  317. <li><strong>view</strong> — fit/1:1/zoom/pan image viewer, animated GIF playback.</li>
  318. <li><strong>edit</strong> — text editor that draws its own text with the 8x16 font.</li>
  319. <li><strong>clock</strong> / <strong>colors</strong> — small window canvas demos.</li>
  320. <li><strong>settime</strong> — Date &amp; Time editor opened by clicking the top-bar clock. It reads and writes the CMOS RTC through <code>SYS_RTC_GET</code>/<code>SYS_RTC_SET</code>; the <em>Sync NTP</em> button asks the kernel's SNTP client (<code>SYS_NTP_SYNC</code>, 106) for UTC and writes the result to the RTC. The two-digit RTC year is expanded over 1970–2069 so dead-battery defaults such as 1980/1990 can be corrected.</li>
  321. <li><strong>wm</strong> / <strong>term</strong> — the ring-3 window manager and terminal launcher used by the desktop.</li>
  322. </ul>
  323. <p>
  324. The WM chrome, ngui labels and the browser use the fixed-point
  325. TrueType engine in <span class="file">ufont.c</span> with the Arimo
  326. and Liberation Mono subsets in the pack. CSS and ngui can select
  327. regular/bold/italic/mono faces at 8–48 px; missing faces fall back to
  328. the 8×16 bitmap. Terminal contents and the editor stay bitmap;
  329. ngui text fields use the proportional face for text, caret,
  330. selection and horizontal scrolling. The browser detaches the font
  331. arena before <code>heap_reset()</code> and reattaches after the page
  332. heap is mapped.
  333. </p>
  334. </section>
  335. <section id="browser">
  336. <h2>Browser</h2>
  337. <p>
  338. The real browser is <code>bin/browser.app</code> in the pack. It links
  339. ngui, the image library, inflate, TLS, uhttp and the vendored MuJS
  340. engine. It opens at 1100×700 (960×640 and 780×540 fallbacks on
  341. smaller screens), with a URL bar, history, a status bar, inline
  342. images and inline/external scripts. Network
  343. work runs in a headless <code>curl __fetch</code> helper that writes
  344. the body and metadata under <code>/share</code>, so the UI keeps
  345. drawing and scrolling.
  346. </p>
  347. <ul>
  348. <li><strong>HTML/CSS subset.</strong> External and inline stylesheets, tag/class/id and descendant/child selectors, colours, backgrounds (solid and <code>background-image</code> with repeat/position/size and the <code>background</code> shorthand URL), real <code>font-size</code> (8–48 px), the <code>font</code> shorthand, bold/italic faces, <code>font-family: monospace</code> and one regular <code>@font-face</code> face per family (local or HTTP TTF), margins/padding (percentage sizes use the containing width; <code>em</code> uses the element font), per-side borders, alignment, explicit/percentage block widths with <code>min-width</code>/<code>max-width</code>/<code>min-height</code>/<code>max-height</code>, <code>box-sizing: border-box</code>, <code>margin: 0 auto</code>, nested <code>em</code>/<code>rem</code> sizes, basic floats, <code>position: relative</code>/<code>absolute</code>/<code>fixed</code>/<code>sticky</code>, <code>right</code>/<code>bottom</code>, <code>z-index</code>, <code>transform: translate</code>, flex rows with grow/wrap/justify/align, two-column grids, table rowspan/colspan and percentage columns, <code>calc(percent ± px)</code> widths, <code>white-space: nowrap</code> and <code>@media</code> blocks evaluated at the browser canvas width when the page is parsed. Text is Latin-1; there is no shaping, bidi, WOFF/unicode-range or full-Unicode fallback.</li>
  349. <li><strong>JavaScript.</strong> Inline and external <code>&lt;script src&gt;</code> blocks run on the vendored MuJS engine in document order. External scripts use the same local/network fetch path as pages and CSS (512 KB cap) and are cached under <code>/share/bjs-*</code> for the current boot; the parsed page is painted before scripts run. Classic scripts are sloppy by default, and the engine carries Annex B fixes for regex literals after control parentheses and identity escapes/braces. Math, Date and JSON are the engine's; each page gets one state, and an 8M-instruction limit turns a runaway loop into a <code>script ran too long</code> error instead of freezing the browser.</li>
  350. <li><strong>DOM.</strong> Nodes are interned MuJS userdata wrappers, so <code>===</code> and library expando caches behave. Elements support <code>getAttribute</code>/<code>setAttribute</code>/<code>hasAttribute</code>, <code>appendChild</code>/<code>insertBefore</code>/<code>removeChild</code>/<code>replaceChild</code>/<code>cloneNode</code>/<code>remove</code>, <code>querySelector(All)</code>, <code>getElementsByTagName</code>, <code>getElementsByClassName</code>, <code>classList</code>, <code>dataset</code>, inline <code>style</code> (<code>cssText</code>, property get/set, <code>getPropertyValue</code>/<code>setProperty</code>/<code>removeProperty</code>), <code>innerHTML</code> (fragment parser), <code>textContent</code>/<code>nodeValue</code>, traversal, <code>matches</code> and <code>getBoundingClientRect</code> (real block/table/absolute/image boxes; inline text boxes are still approximate). Form controls expose live <code>value</code>/<code>checked</code>/<code>selectedIndex</code> properties backed by the browser's control state; forms expose <code>elements</code>, <code>submit()</code> and <code>reset()</code>, and elements dispatch real <code>addEventListener</code>/<code>dispatchEvent</code> events with capture, bubbling and <code>preventDefault()</code>. <code>&lt;a&gt;</code> elements expose <code>href</code>/<code>protocol</code>/<code>host</code>/<code>hostname</code>/<code>port</code>/<code>pathname</code>/<code>search</code>/<code>hash</code>/<code>origin</code> resolved against the page URL. <code>document</code> has <code>createElement</code>, <code>createTextNode</code>, <code>createComment</code>, <code>createDocumentFragment</code>, <code>createAttribute</code>, <code>documentElement</code>/<code>body</code>/<code>head</code> and <code>readyState</code>; <code>navigator</code>, <code>history</code>, <code>matchMedia</code>, <code>getComputedStyle</code>, <code>setTimeout</code>/<code>setInterval</code>/<code>clearTimeout</code> and <code>requestAnimationFrame</code> exist, and due timers are pumped from the browser loop. jQuery 1.11, Bootstrap 3.2 tooltips and AngularJS 1.3 (with ngRoute/ngSanitize) initialize on a local test page.</li>
  351. <li><strong>Not supported.</strong> Inline event attributes (<code>onclick=</code>), <code>MouseEvent</code>/<code>CustomEvent</code> and <code>once</code>/<code>passive</code> listener options, <code>type="module"</code>, <code>defer</code>/<code>async</code>, <code>MutationObserver</code>/<code>IntersectionObserver</code>, <code>XMLHttpRequest</code>/<code>fetch</code>, <code>DOMParser</code>, canvas/2D contexts and pseudo-class/element selectors. Basic controls render, focus, edit, toggle, select, submit GET queries and POST <code>application/x-www-form-urlencoded</code> bodies (see the compatibility ladder); <code>getComputedStyle</code> is a stub and <code>outerHTML</code> only returns the string last assigned to <code>innerHTML</code>.</li>
  352. <li><strong>CSS gaps.</strong> Multiple background layers and <code>background-attachment</code> (a non-uniform <code>background-size</code> uses the width scale), the rest of <code>transform</code> (only <code>translate</code>), sticky beyond the top edge, pseudo-classes/elements, border-radius clipping of descendants, gradients/box-shadow/transitions and <code>color-mix</code>. Flex rows, card grids, tables with rowspan/colspan, inline SVG and CSS variables are supported.</li>
  353. <li><strong>Caps.</strong> 2 MB page body, 832 KB CSS, 6144 DOM nodes, 4608 rules, 16 images. Each image gets an <code>img_estimate()</code>-sized decode arena that is freed after the scaled bitmap is made; navigation calls <code>heap_reset()</code> and unmaps the page heap.</li>
  354. <li><strong>Fetching.</strong> Each network fetch starts a one-shot helper process and a fresh TCP/TLS connection; images load one per loop within the viewport plus 160 px.</li>
  355. <li><strong>URL entry.</strong> A dotted name without a scheme that is not a known local file extension is treated as a hostname, so <code>cloudron.io</code> does not hit the local-file stat. Origin-level redirects (the common <code>http://host</code> → <code>https://host</code> → <code>https://www.host</code> chain) are cached per process and in <code>/share/borigins</code>; the first visit still follows them, later visits go straight to the canonical origin. Remote stylesheets are cached under <code>/share/bcss-*</code> for the current boot, so a reload or a fresh browser launch skips the CSS downloads.</li>
  356. </ul>
  357. <p>
  358. The browser's default canvas is dark, matching the ngui theme. Pages
  359. that set dark text but rely on a white default background can be hard
  360. to read; pages with their own full background and colour rules are
  361. unaffected. See <a href="graphics.html#images">Graphics → Image
  362. library</a> for the decoder limits.
  363. </p>
  364. <p>
  365. <code>testdata/browser/compat/</code> is the browser compatibility
  366. ladder: numbered, self-contained pages with an A/B pair for each
  367. behaviour. Run <code>make compat-serve</code> and open
  368. <code>http://&lt;host&gt;:8000/</code> on the board (or
  369. <code>http://10.0.2.2:8000/</code> in QEMU's user network). The
  370. index records the current pass/fail status; pages 010–038 and 030a pass
  371. (036a needs the POST echo server), while
  372. the README lists the remaining gaps.
  373. </p>
  374. </section>
  375. <section id="sources">
  376. <h2>Source map</h2>
  377. <ul class="filelist">
  378. <li><code>syscall.c</code>, <code>syscall_stub.S</code>, <code>syscall.h</code></li>
  379. <li><code>sys_info.c</code> — kernel-state snapshots (memory, sensors, power)</li>
  380. <li><code>rtc.c</code> — CMOS RTC read/write, format decoding and the 1970–2069 year window</li>
  381. <li><code>process.c</code> — ELF load and spawn</li>
  382. <li><code>elf.c</code> — ELF parser</li>
  383. <li><code>ucmd_term.c</code> — windowed shell, scrollback, PATH</li>
  384. <li><code>terminal.c</code> — privileged kernel command registry</li>
  385. <li><code>install.c</code> — privileged live-image clone installer</li>
  386. <li><code>ucmd_lib.h</code> — user shim</li>
  387. <li><code>libc/</code> — headers, malloc, string/stdlib, setjmp/errno, stdio/dtoa, math, time and the <code>SYS_MEM_*</code> backend</li>
  388. <li><code>libc.a</code> — optional static ring-3 libc</li>
  389. <li><code>ucmd.ld</code> — ring-3 link address</li>
  390. <li><code>Makefile</code> — <code>UCMDS</code> and pack rules</li>
  391. <li><code>ucmd_*.c</code> — commands</li>
  392. <li><code>ufont.c</code>, <code>ufont_ttf.c</code> — fixed-point TrueType text</li>
  393. <li><code>ngui.c</code> — GUI toolkit; <code>fonts/*.ttf</code> — UI subsets</li>
  394. <li><code>browser.c</code>, <code>browser_html.c</code>, <code>js_browser.c/h</code>, <code>third_party/mujs/</code>, <code>gallery.c</code></li>
  395. </ul>
  396. </section>
  397. </main>
  398. <footer class="site-footer">
  399. <div class="inner">
  400. <p><strong>NebOS 0.2.0</strong> · Architecture documentation · <a href="index.html">overview</a></p>
  401. <p>Maintain alongside <code>AGENTS.md</code> and the source files listed on each page.</p>
  402. </div>
  403. </footer>
  404. </body>
  405. </html>