userland.html 32 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439
  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 47-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 47 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">47 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, 109</td><td>key poll, WM attach/info/map/present/create_term, window create/present/input/resize/scroll</td></tr>
  212. <tr><td>Process &amp; memory</td><td>73–79, 81, 88–90, 108</td><td>TTY, spawn, getpid, 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. <tr><td>WiFi</td><td>110</td><td><code>SYS_WIFI(op, a2, a3)</code>: up, status, scan/results, connect/disconnect, EAPOL RX/TX, set key, authorize, set/get PTK for the rekey helper (<span class="file">wifi.c</span>)</td></tr>
  215. <tr><td>NIC menu</td><td>111–112</td><td><code>SYS_NET_DEVLIST</code> (present drivers with kind/active/link) and <code>SYS_NET_SELECT</code> (make a named netdev active)</td></tr>
  216. </tbody>
  217. </table>
  218. </div>
  219. <p>
  220. The file service is whole-file, not stream-oriented. The network
  221. service has a per-process TCP client table (up to twelve connections)
  222. and a separate raw NIC lease for packet-level commands. There is no
  223. <code>fork</code>, <code>exec</code> or shared memory: a command
  224. either runs as its own process from an ELF or calls a kernel command.
  225. </p>
  226. </section>
  227. <section id="shell">
  228. <h2>Shell &amp; PATH</h2>
  229. <p>
  230. The windowed shell is <span class="file">ucmd_term.c</span>; the
  231. kernel-side <span class="file">terminal.c</span> holds the privileged
  232. command registry used through <code>SYS_SPAWN_KCMD</code>. There is
  233. no kernel terminal fallback; the WM spawns the first terminal once
  234. storage is ready. Each terminal has a current working directory and
  235. a PATH (default <code>/ramfs/bin</code>). Pressing Tab completes
  236. builtin and PATH names; <code>help</code> lists both.
  237. </p>
  238. <ul>
  239. <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>
  240. <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>
  241. <li><strong>Arguments.</strong> The raw remainder of the line is passed verbatim; commands parse their own flags.</li>
  242. <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>
  243. <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>
  244. </ul>
  245. </section>
  246. <section id="registry">
  247. <h2>Kernel commands</h2>
  248. <p>
  249. These commands must run in ring 0 or inline in the shell; they are not
  250. files in the pack. The split keeps privileged hardware access out of
  251. ring 3 while most user-facing tools remain replaceable ELFs.
  252. </p>
  253. <div class="table-wrap">
  254. <table>
  255. <thead>
  256. <tr><th>Group</th><th>Commands</th></tr>
  257. </thead>
  258. <tbody>
  259. <tr><td>Shell</td><td><code>cd</code> <code>path</code> <code>help</code> <code>clear</code> <code>bootlog</code></td></tr>
  260. <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>
  261. <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>
  262. <tr><td>Network control</td><td><code>netdev</code></td></tr>
  263. <tr><td>Boot / power</td><td><code>reboot</code> <code>poweroff</code> <code>kexec</code></td></tr>
  264. </tbody>
  265. </table>
  266. </div>
  267. <p>
  268. <code>format &lt;device&gt; [size]</code> creates a FAT filesystem.
  269. <code>install &lt;target&gt; [source]</code> clones the live NebOS
  270. image to a target disk: it auto-detects a source whose MBR and LBA-63
  271. boot sector carry the NebOS signature (preferring <code>usb0</code>),
  272. reads the source image into RAM, then writes the target from RAM,
  273. writes the MBR last and verifies the result. A source-read failure
  274. leaves the target untouched. It installs the flashed image, so both
  275. the BIOS and UEFI boot paths are cloned as-is.
  276. </p>
  277. </section>
  278. <section id="pack">
  279. <h2>Command pack</h2>
  280. <p>
  281. The pack is built from the <code>UCMDS</code> list in the Makefile as
  282. <code>bin/&lt;name&gt;</code>, plus <code>hello</code> and the real
  283. <code>browser.app</code> and <code>gallery.app</code>. It is mounted
  284. read-only at <code>/ramfs</code>; the shell's default PATH points at
  285. <code>/ramfs/bin</code>.
  286. </p>
  287. <div class="grid">
  288. <div class="card">
  289. <h3>Files &amp; text</h3>
  290. <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>
  291. </div>
  292. <div class="card">
  293. <h3>System</h3>
  294. <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>
  295. </div>
  296. <div class="card">
  297. <h3>Network</h3>
  298. <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> <code>wifi</code> <code>netmenu</code></p>
  299. </div>
  300. <div class="card">
  301. <h3>GUI</h3>
  302. <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>chat</code> <code>clock</code> <code>colors</code> <code>settime</code></p>
  303. </div>
  304. </div>
  305. <p>
  306. The launchers <code>bin/browser</code> and <code>bin/gallery</code>
  307. forward their argument and cwd, and prefer a development copy under
  308. <code>/share</code> (<code>BROWSER</code> or <code>GALLERY</code>)
  309. before the pack copy and the FAT fallback on <code>root.img</code>.
  310. This lets <code>make browser-dev</code> and <code>make gallery-dev</code>
  311. update an app without rebuilding the pack.
  312. </p>
  313. </section>
  314. <section id="apps">
  315. <h2>GUI applications</h2>
  316. <ul>
  317. <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>
  318. <li><strong>gallery</strong> — live widget and primitive showcase; the real app ships in the pack.</li>
  319. <li><strong>chat</strong> — native Cloudron Chat client (top-bar <em>Chat</em> button, or <code>chat [config-path]</code>): username/password/TOTP login through the Cloudron OIDC API or a pasted session cookie, channels and DMs with unread badges and presence, history with older paging, sending, REST polling, read markers, browse/join and new DM. The session cookie (never the password) is saved in <code>/share/chat.cfg</code> by default. Keys: Enter sends, PgUp/PgDn scroll, Home at the top pages in older history, Ctrl+B browse, Ctrl+N new DM, Ctrl+R refresh, and with the composer unfocused (Esc) Up/Down switch conversations. See <a href="network.html#chat">Network → Chat client</a>.</li>
  320. <li><strong>solitaire</strong> — Klondike with drag-and-drop, scoring and a win animation.</li>
  321. <li><strong>mines</strong> — second ngui canvas app; shares the toolkit and event model.</li>
  322. <li><strong>view</strong> — fit/1:1/zoom/pan image viewer, animated GIF playback.</li>
  323. <li><strong>edit</strong> — text editor that draws its own text with the 8x16 font.</li>
  324. <li><strong>clock</strong> / <strong>colors</strong> — small window canvas demos.</li>
  325. <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>
  326. <li><strong>netmenu</strong> — network menu opened by the top-bar status icon. Lists the present NICs from <code>SYS_NET_DEVLIST</code> (Ethernet, USB Ethernet, RNDIS tethering), selects one with <code>SYS_NET_SELECT</code> and runs DHCP. Its WiFi section scans through <code>SYS_WIFI_SCAN</code>/<code>RESULTS</code>, asks for a WPA2 passphrase when needed and starts the <code>wifi</code> helper through a <code>/share/netmenu.wifi</code> request, because the 64-byte <code>SYS_SPAWN</code> argument cannot hold a long SSID plus passphrase. On success the helper saves the SSID/passphrase to <code>/data/WIFI.CFG</code>; the next boot's <code>wifi autoconnect</code> helper reconnects from it. Duplicate BSSIDs for one SSID are collapsed to the strongest entry (or the active one), and hidden networks are omitted.</li>
  327. <li><strong>wm</strong> / <strong>term</strong> — the ring-3 window manager and terminal launcher used by the desktop.</li>
  328. </ul>
  329. <p>
  330. The WM chrome, ngui labels and the browser use the fixed-point
  331. TrueType engine in <span class="file">ufont.c</span> with the Arimo
  332. and Liberation Mono subsets in the pack. CSS and ngui can select
  333. regular/bold/italic/mono faces at 8–48 px; missing faces fall back to
  334. the 8×16 bitmap. UTF-8 text APIs additionally fall back to the
  335. monochrome Noto Emoji subset for common emoji (format-12 cmap);
  336. the browser still uses the Latin-1 byte path. Terminal contents and
  337. the editor stay bitmap;
  338. ngui text fields use the proportional face for text, caret,
  339. selection and horizontal scrolling. The browser detaches the font
  340. arena before <code>heap_reset()</code> and reattaches after the page
  341. heap is mapped.
  342. </p>
  343. </section>
  344. <section id="browser">
  345. <h2>Browser</h2>
  346. <p>
  347. The real browser is <code>bin/browser.app</code> in the pack. It links
  348. ngui, the image library, inflate, TLS, uhttp and the vendored MuJS
  349. engine. It opens at 1100×700 (960×640 and 780×540 fallbacks on
  350. smaller screens), with a URL bar, history, a status bar, inline
  351. images and inline/external scripts. Network work runs in up to three
  352. headless <code>curl __serve</code> workers, each with its own files
  353. under <code>/share</code>, so the UI keeps drawing and scrolling
  354. while several TCP/TLS connections are in flight.
  355. </p>
  356. <ul>
  357. <li><strong>HTML/CSS subset.</strong> External and inline stylesheets, tag/class/id and descendant/child selectors, colours (including legacy <code>bgcolor</code> attributes), 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> (top/bottom, containing-block clamp), <code>right</code>/<code>bottom</code>, <code>z-index</code> (including relative boxes), <code>overflow: hidden</code> clipping, <code>transform: translate</code>/<code>scale</code>/<code>rotate</code> with <code>transform-origin</code> (paint-time box and image transforms), flex rows with grow/wrap/justify (including <code>space-evenly</code>)/align, two-column grids, table rowspan/colspan and percentage columns, <code>calc(percent ± px)</code> in widths, margins/padding, heights and min/max, <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>
  358. <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>
  359. <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>
  360. <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> covers the engine's properties, and <code>outerHTML</code> only returns the string last assigned to <code>innerHTML</code>.</li>
  361. <li><strong>CSS gaps.</strong> Multiple background layers and <code>background-attachment</code> (a non-uniform <code>background-size</code> uses the width scale), 3D/perspective transforms and transformed text/descendants (scale/rotate paint the box and inline images), 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>
  362. <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>
  363. <li><strong>Fetching.</strong> Up to three worker processes prefetch images in parallel within the viewport plus 160 px; each worker keeps its own TCP/TLS connection and its own request/body/meta files (keyed by browser pid and worker slot, so multiple windows do not collide). Completed images are decoded as jobs finish. Page, CSS and script fetches stay ordered.</li>
  364. <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. A typed hostname is tried as <code>https://</code> first, skipping the common <code>http://host</code> → <code>https://host</code> hop; if the https connection is refused, reset, times out or fails the TLS handshake, the browser retries once over <code>http://</code> and replaces the history entry. Origin-level redirects (such as <code>https://host</code> → <code>https://www.host</code>) 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>
  365. </ul>
  366. <p>
  367. The browser's default canvas is dark, matching the ngui theme, but an
  368. <code>html</code>/<code>body</code> background fills the whole page
  369. canvas. Pages without one that set dark text can be hard to read;
  370. pages with their own background and colour rules are unaffected. See <a href="graphics.html#images">Graphics → Image
  371. library</a> for the decoder limits.
  372. </p>
  373. <p>
  374. <code>testdata/browser/compat/</code> is the browser compatibility
  375. ladder: numbered, self-contained pages with an A/B pair for each
  376. behaviour. Run <code>make compat-serve</code> and open
  377. <code>http://&lt;host&gt;:8000/</code> on the board (or
  378. <code>http://10.0.2.2:8000/</code> in QEMU's user network). The
  379. index records the current pass/fail status; pages 010–046 and 030a pass
  380. (036a needs the POST echo server), while
  381. the README lists the remaining gaps.
  382. </p>
  383. </section>
  384. <section id="sources">
  385. <h2>Source map</h2>
  386. <ul class="filelist">
  387. <li><code>syscall.c</code>, <code>syscall_stub.S</code>, <code>syscall.h</code></li>
  388. <li><code>sys_info.c</code> — kernel-state snapshots (memory, sensors, power)</li>
  389. <li><code>rtc.c</code> — CMOS RTC read/write, format decoding and the 1970–2069 year window</li>
  390. <li><code>process.c</code> — ELF load and spawn</li>
  391. <li><code>elf.c</code> — ELF parser</li>
  392. <li><code>ucmd_term.c</code> — windowed shell, scrollback, PATH</li>
  393. <li><code>terminal.c</code> — privileged kernel command registry</li>
  394. <li><code>install.c</code> — privileged live-image clone installer</li>
  395. <li><code>ucmd_lib.h</code> — user shim</li>
  396. <li><code>libc/</code> — headers, malloc, string/stdlib, setjmp/errno, stdio/dtoa, math, time and the <code>SYS_MEM_*</code> backend</li>
  397. <li><code>libc.a</code> — optional static ring-3 libc</li>
  398. <li><code>ucmd.ld</code> — ring-3 link address</li>
  399. <li><code>Makefile</code> — <code>UCMDS</code> and pack rules</li>
  400. <li><code>ucmd_*.c</code> — commands</li>
  401. <li><code>ufont.c</code>, <code>ufont_ttf.c</code> — fixed-point TrueType text</li>
  402. <li><code>ngui.c</code> — GUI toolkit; <code>fonts/*.ttf</code> — UI and emoji subsets</li>
  403. <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>
  404. <li><code>ucmd_chat.c</code>, <code>chat_login.c</code>, <code>ujson.c</code>, <code>uhttp_cookie.c</code> — chat client</li>
  405. <li><code>ucmd_wifi.c</code>, <code>wpa.c</code>, <code>wpa_crypto.c</code> — <code>wifi</code> command and the WPA2-PSK supplicant</li>
  406. <li><code>ucmd_netmenu.c</code>, <code>wifi_cfg.h</code> — top-bar network menu and its staged WiFi connect record</li>
  407. </ul>
  408. </section>
  409. </main>
  410. <footer class="site-footer">
  411. <div class="inner">
  412. <p><strong>NebOS 0.2.0</strong> · Architecture documentation · <a href="index.html">overview</a></p>
  413. <p>Maintain alongside <code>AGENTS.md</code> and the source files listed on each page.</p>
  414. </div>
  415. </footer>
  416. </body>
  417. </html>