userland.html 33 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444
  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|self]</code> installs NebOS.
  270. With a source it auto-detects a disk whose MBR and LBA-63 boot
  271. sector carry the NebOS signature (preferring <code>usb0</code>),
  272. reads P1..P3 into RAM, creates or keeps the <code>NEBOSDATA</code>
  273. partition at LBA 34816, writes the target from RAM, merges the data
  274. entry into the MBR, writes the MBR last and verifies the result. A
  275. source-read failure leaves the target untouched. <code>self</code>
  276. writes the running gzip pack and its bundled kernel without a USB
  277. stick; <code>auto</code> picks the only non-USB NebOS disk. The
  278. data partition survives both forms, while the P1..P3 OS image and
  279. the app pack are replaced. Both the BIOS and UEFI paths are cloned
  280. on a full install; a later self-update leaves the ESP alone.
  281. </p>
  282. </section>
  283. <section id="pack">
  284. <h2>Command pack</h2>
  285. <p>
  286. The pack is built from the <code>UCMDS</code> list in the Makefile as
  287. <code>bin/&lt;name&gt;</code>, plus <code>hello</code> and the real
  288. <code>browser.app</code> and <code>gallery.app</code>. It is mounted
  289. read-only at <code>/ramfs</code>; the shell's default PATH points at
  290. <code>/ramfs/bin</code>.
  291. </p>
  292. <div class="grid">
  293. <div class="card">
  294. <h3>Files &amp; text</h3>
  295. <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>
  296. </div>
  297. <div class="card">
  298. <h3>System</h3>
  299. <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>
  300. </div>
  301. <div class="card">
  302. <h3>Network</h3>
  303. <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>
  304. </div>
  305. <div class="card">
  306. <h3>GUI</h3>
  307. <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>
  308. </div>
  309. </div>
  310. <p>
  311. The launchers <code>bin/browser</code> and <code>bin/gallery</code>
  312. forward their argument and cwd, and prefer a development copy under
  313. <code>/share</code> (<code>BROWSER</code> or <code>GALLERY</code>)
  314. before the pack copy and the FAT fallback on <code>root.img</code>.
  315. This lets <code>make browser-dev</code> and <code>make gallery-dev</code>
  316. update an app without rebuilding the pack.
  317. </p>
  318. </section>
  319. <section id="apps">
  320. <h2>GUI applications</h2>
  321. <ul>
  322. <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>
  323. <li><strong>gallery</strong> — live widget and primitive showcase; the real app ships in the pack.</li>
  324. <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>
  325. <li><strong>solitaire</strong> — Klondike with drag-and-drop, scoring and a win animation.</li>
  326. <li><strong>mines</strong> — second ngui canvas app; shares the toolkit and event model.</li>
  327. <li><strong>view</strong> — fit/1:1/zoom/pan image viewer, animated GIF playback.</li>
  328. <li><strong>edit</strong> — text editor that draws its own text with the 8x16 font.</li>
  329. <li><strong>clock</strong> / <strong>colors</strong> — small window canvas demos.</li>
  330. <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>
  331. <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>
  332. <li><strong>wm</strong> / <strong>term</strong> — the ring-3 window manager and terminal launcher used by the desktop.</li>
  333. </ul>
  334. <p>
  335. The WM chrome, ngui labels and the browser use the fixed-point
  336. TrueType engine in <span class="file">ufont.c</span> with the Arimo
  337. and Liberation Mono subsets in the pack. CSS and ngui can select
  338. regular/bold/italic/mono faces at 8–48 px; missing faces fall back to
  339. the 8×16 bitmap. UTF-8 text APIs additionally fall back to the
  340. monochrome Noto Emoji subset for common emoji (format-12 cmap);
  341. the browser still uses the Latin-1 byte path. Terminal contents and
  342. the editor stay bitmap;
  343. ngui text fields use the proportional face for text, caret,
  344. selection and horizontal scrolling. The browser detaches the font
  345. arena before <code>heap_reset()</code> and reattaches after the page
  346. heap is mapped.
  347. </p>
  348. </section>
  349. <section id="browser">
  350. <h2>Browser</h2>
  351. <p>
  352. The real browser is <code>bin/browser.app</code> in the pack. It links
  353. ngui, the image library, inflate, TLS, uhttp and the vendored MuJS
  354. engine. It opens at 1100×700 (960×640 and 780×540 fallbacks on
  355. smaller screens), with a URL bar, history, a status bar, inline
  356. images and inline/external scripts. Network work runs in up to three
  357. headless <code>curl __serve</code> workers, each with its own files
  358. under <code>/share</code>, so the UI keeps drawing and scrolling
  359. while several TCP/TLS connections are in flight.
  360. </p>
  361. <ul>
  362. <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>
  363. <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>
  364. <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>
  365. <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>
  366. <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>
  367. <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>
  368. <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. Idle helpers stay warm across navigations (they exit after ten idle seconds, and losing window focus stops them), so a second page on the same origin reuses its connection. Page, CSS and script fetches stay ordered. The status bar reports the page fetch's header and first-byte times.</li>
  369. <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>
  370. </ul>
  371. <p>
  372. The browser's default canvas is dark, matching the ngui theme, but an
  373. <code>html</code>/<code>body</code> background fills the whole page
  374. canvas. Pages without one that set dark text can be hard to read;
  375. pages with their own background and colour rules are unaffected. See <a href="graphics.html#images">Graphics → Image
  376. library</a> for the decoder limits.
  377. </p>
  378. <p>
  379. <code>testdata/browser/compat/</code> is the browser compatibility
  380. ladder: numbered, self-contained pages with an A/B pair for each
  381. behaviour. Run <code>make compat-serve</code> and open
  382. <code>http://&lt;host&gt;:8000/</code> on the board (or
  383. <code>http://10.0.2.2:8000/</code> in QEMU's user network). The
  384. index records the current pass/fail status; pages 010–046 and 030a pass
  385. (036a needs the POST echo server), while
  386. the README lists the remaining gaps.
  387. </p>
  388. </section>
  389. <section id="sources">
  390. <h2>Source map</h2>
  391. <ul class="filelist">
  392. <li><code>syscall.c</code>, <code>syscall_stub.S</code>, <code>syscall.h</code></li>
  393. <li><code>sys_info.c</code> — kernel-state snapshots (memory, sensors, power)</li>
  394. <li><code>rtc.c</code> — CMOS RTC read/write, format decoding and the 1970–2069 year window</li>
  395. <li><code>process.c</code> — ELF load and spawn</li>
  396. <li><code>elf.c</code> — ELF parser</li>
  397. <li><code>ucmd_term.c</code> — windowed shell, scrollback, PATH</li>
  398. <li><code>terminal.c</code> — privileged kernel command registry</li>
  399. <li><code>install.c</code> — privileged live-image clone installer</li>
  400. <li><code>ucmd_lib.h</code> — user shim</li>
  401. <li><code>libc/</code> — headers, malloc, string/stdlib, setjmp/errno, stdio/dtoa, math, time and the <code>SYS_MEM_*</code> backend</li>
  402. <li><code>libc.a</code> — optional static ring-3 libc</li>
  403. <li><code>ucmd.ld</code> — ring-3 link address</li>
  404. <li><code>Makefile</code> — <code>UCMDS</code> and pack rules</li>
  405. <li><code>ucmd_*.c</code> — commands</li>
  406. <li><code>ufont.c</code>, <code>ufont_ttf.c</code> — fixed-point TrueType text</li>
  407. <li><code>ngui.c</code> — GUI toolkit; <code>fonts/*.ttf</code> — UI and emoji subsets</li>
  408. <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>
  409. <li><code>ucmd_chat.c</code>, <code>chat_login.c</code>, <code>ujson.c</code>, <code>uhttp_cookie.c</code> — chat client</li>
  410. <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>
  411. <li><code>ucmd_netmenu.c</code>, <code>wifi_cfg.h</code> — top-bar network menu and its staged WiFi connect record</li>
  412. </ul>
  413. </section>
  414. </main>
  415. <footer class="site-footer">
  416. <div class="inner">
  417. <p><strong>NebOS 0.2.0</strong> · Architecture documentation · <a href="index.html">overview</a></p>
  418. <p>Maintain alongside <code>AGENTS.md</code> and the source files listed on each page.</p>
  419. </div>
  420. </footer>
  421. </body>
  422. </html>