userland.html 61 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577
  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 54-command pack, init/services, 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 54 PATH commands by default, including the PID-1 <code>init</code> manager and the <code>service</code> client.
  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">54 PATH commands</span>
  45. <span class="pill">16 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="#services">Init &amp; services</a></li>
  53. <li><a href="#libc">Ring-3 libc</a></li>
  54. <li><a href="#spawn">Spawn path</a></li>
  55. <li><a href="#syscalls">Syscall ABI</a></li>
  56. <li><a href="#shell">Shell &amp; PATH</a></li>
  57. <li><a href="#registry">Kernel commands</a></li>
  58. <li><a href="#pack">Command pack</a></li>
  59. <li><a href="#apps">GUI applications</a></li>
  60. <li><a href="#browser">Browser</a></li>
  61. <li><a href="#sources">Source map</a></li>
  62. </ul>
  63. </nav>
  64. <section id="model">
  65. <h2>Ring-3 model</h2>
  66. <p>
  67. A user process gets a page directory cloned from the kernel identity
  68. map, a 4 MB image/stack window at <code>0x40000000</code>, an optional
  69. 4 MB canvas at <code>0x50000000</code> and a growable heap at
  70. <code>0x60000000</code>. Program, stack and heap frames come from
  71. highmem (above 1 GB) when the machine has it. The kernel remains mapped because paging is
  72. identity-mapped; this is isolation in privilege level only, not a
  73. separate address space.
  74. </p>
  75. <ul>
  76. <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>
  77. <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>
  78. <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>
  79. <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>
  80. </ul>
  81. <div class="note">
  82. <p><strong>Not a sandbox.</strong> Because physical and virtual addresses
  83. are identical and the kernel is mapped, a ring-3 bug can read or write
  84. any mapped kernel page. The privilege boundary protects against
  85. accidental corruption from ordinary code, not against malicious code.</p>
  86. </div>
  87. </section>
  88. <section id="services">
  89. <h2>Init &amp; services</h2>
  90. <p>
  91. The kernel starts <code>/ramfs/bin/init</code> as PID 1 after the
  92. ramfs and <code>/share</code> mounts, and before any WM exists.
  93. Init is a normal ring-3 process; the kernel only loads it, records
  94. <code>init_pid</code> before the process is runnable, refuses
  95. <code>SYS_KILL(init)</code> and restarts it from the kworker if it
  96. dies. A user-run <code>init</code> exits immediately because
  97. <code>SYS_IS_INIT</code> is false.
  98. </p>
  99. <ul>
  100. <li><strong>Init owns the WM.</strong> The kernel never starts a
  101. WM. Init spawns <code>/ramfs/bin/wm</code>, watches its pid and
  102. respawns it after an exit; the kernel's WM watchdog only kills a
  103. wedged WM. <code>SYS_WM_ATTACH</code> accepts only an init child
  104. named <code>wm</code>, maps the shadow and disables the boot
  105. console. If init or the WM binary is missing the boot console
  106. stays visible and there is no desktop.</li>
  107. <li><strong>Services.</strong> The static table lives in
  108. <span class="file">user/apps/service/service_defs.c</span>. The
  109. first unit is <code>websrv</code> (<code>/ramfs/bin/websrv
  110. 8080</code>, autostart off). Init allocates one tty per running
  111. service with <code>SYS_TTY_ALLOC</code>, drains it into a 32 KB
  112. <code>/share/svc-&lt;name&gt;.log</code> and writes
  113. <code>/share/svc-&lt;name&gt;.state</code> (state, desired, pid,
  114. tty, start time). The control tty and the WM pid are in
  115. <code>/share/init.state</code>; <code>/share/init.log</code> is
  116. the manager log.</li>
  117. <li><strong>Lifecycle.</strong> Start, stop, restart and kill are
  118. requests to init; a service that exits unexpectedly is marked
  119. stopped (no v1 auto-restart). There are no signals, so stop and
  120. kill both terminate the process; kill is the forced variant and
  121. init drains/closes the log tty when it observes the exit.
  122. On an init restart the new init first kills every leftover ring-3
  123. process (kernel threads survive), then restarts the WM and the
  124. services whose saved desired state is running.</li>
  125. <li><strong>Parent death and detach.</strong> Every process has a
  126. <code>parent_pid</code>; exit, kill and the reaper kill the
  127. descendant subtree. <code>SYS_SPAWN</code> is parented by default;
  128. <code>SYS_SPAWN_DETACH</code> attaches the child to the caller's
  129. parent (the terminal/WM session), so a file manager, chat window
  130. or WiFi helper can launch something that outlives it without
  131. leaking a root process. Terminal commands are parented and
  132. foreground; the browser and gallery launchers spawn the real app
  133. parented and wait for it, so Ctrl-C/terminal close kills it.
  134. <code>SYS_SPAWN_KCMD</code> stays parented.</li>
  135. <li><strong>CLI and GUI.</strong> <code>service</code> lists
  136. <code>init</code>, <code>wm</code> and the user services;
  137. <code>service status &lt;name&gt;</code>, <code>start</code>,
  138. <code>stop</code>, <code>restart</code>, <code>kill</code>,
  139. <code>logs &lt;name&gt;</code>, <code>logtail &lt;name&gt;</code>
  140. and <code>service --gui</code> are the client. The GUI has a
  141. service list, Start/Stop/Restart/Kill controls (Kill asks for a
  142. second click), a log pane and a refresh loop; closing it does not
  143. stop services. <code>wm</code> is a system service: Stop is
  144. refused, Restart/Kill respawn it and close its windows.</li>
  145. <li><strong>Protocol.</strong> A client allocates a response tty,
  146. reads <code>/share/init.state</code> and writes
  147. <code>NBI1 &lt;seq&gt; &lt;op&gt; &lt;name&gt; &lt;resp_tty&gt;</code>
  148. to init's control tty; init replies
  149. <code>NBI1 &lt;seq&gt; &lt;code&gt; &lt;pid&gt; &lt;message&gt;</code>.
  150. <code>SYS_TTY_WRITE</code> is non-blocking and never writes a
  151. partial message; <code>SYS_TTY_CLOSE</code> is owner-only.
  152. <code>TTY_MAX</code> is 16.</li>
  153. <li><strong>Not a service.</strong> <code>bootscan</code> is a
  154. kernel thread plus a log viewer; <code>netconsole</code> and
  155. <code>netkexec</code> are kernel facilities. The terminal is
  156. started by the WM.</li>
  157. </ul>
  158. <div class="note">
  159. <p><strong>NIC caveat.</strong> A running <code>websrv</code>
  160. owns the raw NIC receiver. Browser/curl TCP connections and
  161. <code>make net-dev</code> fail until <code>service stop
  162. websrv</code>. Logs, state and the service table's enabled state
  163. are RAM-only in this version; there is no persisted autostart.
  164. The kernel and command pack have no old-ABI compatibility after
  165. the spawn/tty changes.</p>
  166. </div>
  167. </section>
  168. <section id="libc">
  169. <h2>Ring-3 libc</h2>
  170. <p>
  171. <span class="file">libc.a</span> is optional: the Makefile links it
  172. only into commands that reference it, and the archive plus
  173. <code>--gc-sections</code> keeps unused members and functions out of
  174. the legacy command pack. The headers live in
  175. <span class="file">libc/include/</span> and cover
  176. <code>stddef</code>, <code>stdint</code>, <code>stdarg</code>,
  177. <code>stdlib</code>, <code>string</code>, <code>ctype</code>,
  178. <code>assert</code>, <code>setjmp</code>, <code>errno</code>,
  179. <code>stdio</code>, <code>math</code>, <code>time</code>,
  180. <code>sys/time</code>, <code>sys/types</code>, <code>float</code>,
  181. <code>limits</code>, <code>inttypes</code>, <code>alloca</code>
  182. and the OS-specific <code>ucmd_heap.h</code>.
  183. </p>
  184. <ul>
  185. <li><strong>malloc.</strong> Boundary-tag blocks, first-fit free
  186. list, immediate coalescing, 16-byte alignment. The heap maps 64 KB
  187. on first use and grows in page-rounded steps with 64 KB slack up to
  188. the 64 MB <code>SYS_MEM_*</code> arena cap; <code>calloc</code>
  189. zeroes and <code>realloc</code> grows in place when the next block
  190. is free.</li>
  191. <li><strong>heap_reset.</strong> Discards every allocation and
  192. unmaps the whole arena. Page-scoped programs such as the browser
  193. use it on navigation instead of tracking individual frees.</li>
  194. <li><strong>Ownership.</strong> Commands allocate through libc
  195. <code>malloc</code>; the <code>SYS_MEM_ALLOC/GROW/FREE</code>
  196. syscalls are the backend in <span class="file">libc/ucmd_mem.c</span>
  197. and are not called by application code.</li>
  198. <li><strong>stdio.</strong> <code>printf</code>,
  199. <code>snprintf</code>, <code>sprintf</code> and
  200. <code>vfprintf</code> share an exact decimal float formatter
  201. (<code>%f/%e/%g</code>, width/precision), and
  202. <code>fopen("rb")</code> provides read-only whole-file
  203. <code>FILE</code> objects with <code>fread</code>/<code>fseek</code>/
  204. <code>ftell</code>/<code>fclose</code>. stdout and stderr are
  205. console streams; stdin is EOF. There is no kernel fd layer yet: the
  206. <code>stdio_file.c</code> TODO records the future
  207. <code>SYS_OPEN/READ/WRITE/LSEEK/CLOSE</code> replacement.</li>
  208. <li><strong>time.</strong> <code>time</code>, <code>gmtime</code>,
  209. <code>localtime</code>, <code>mktime</code>, <code>strftime</code>,
  210. <code>gettimeofday</code>/<code>settimeofday</code> and
  211. <code>clock_gettime</code> use <code>SYS_RTC_GET</code>/<code>SET</code>.
  212. <code>time_t</code> is 64-bit, local time is UTC-only, and the RTC's
  213. 1970-2069 range is enforced.</li>
  214. <li><strong>math.</strong> The set QuickJS needs is provided with x87
  215. double arithmetic: <code>sqrt</code>, <code>pow</code>,
  216. <code>exp</code>/<code>log</code>, trig, <code>floor</code>/<code>ceil</code>/
  217. <code>round</code>, <code>fmod</code>, <code>ldexp</code>/
  218. <code>frexp</code> and the IEEE predicates. It is a compact
  219. double-rounding implementation, not a full fdlibm.</li>
  220. <li><strong>Limits.</strong> No threads or locking, no
  221. <code>free()</code>-to-page unmap, and requests near 64 MB fail
  222. because headers are charged against the same arena. The file layer
  223. is read-only and whole-file (4 MB cap); writable files and streaming
  224. need the kernel fd layer. There is no timezone database and no
  225. <code>long double</code>/<code>%a</code> support.</li>
  226. <li><strong>Tests.</strong> <code>make test-libc</code> covers the
  227. malloc arena, format/dtoa, math, 64-bit division helpers and
  228. <code>setjmp</code>/<code>longjmp</code> on the host.</li>
  229. </ul>
  230. </section>
  231. <section id="spawn">
  232. <h2>Spawn path</h2>
  233. <figure class="figure">
  234. <svg viewBox="0 0 920 232" role="img" aria-labelledby="spawn-title spawn-desc">
  235. <title id="spawn-title">Command spawn path</title>
  236. <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>
  237. <rect class="svg-box" x="20" y="24" width="160" height="58" rx="9"/>
  238. <text class="svg-text" x="38" y="49">shell line</text>
  239. <text class="svg-sub" x="38" y="69">word + remainder</text>
  240. <rect class="svg-box blue" x="216" y="24" width="160" height="58" rx="9"/>
  241. <text class="svg-text" x="234" y="49">builtins</text>
  242. <text class="svg-sub" x="234" y="69">cd · path · help · clear</text>
  243. <rect class="svg-box accent" x="412" y="24" width="180" height="58" rx="9"/>
  244. <text class="svg-text" x="430" y="49">PATH lookup</text>
  245. <text class="svg-sub" x="430" y="69">/ramfs/bin by default</text>
  246. <rect class="svg-box" x="628" y="24" width="270" height="58" rx="9"/>
  247. <text class="svg-text" x="646" y="49">kernel registry</text>
  248. <text class="svg-sub" x="646" y="69">privileged / inline commands</text>
  249. <path class="svg-line" d="M180 53h24"/>
  250. <path class="svg-line" d="M196 47l7 6-7 6"/>
  251. <path class="svg-line" d="M376 53h24"/>
  252. <path class="svg-line" d="M392 47l7 6-7 6"/>
  253. <path class="svg-line" d="M592 53h24"/>
  254. <path class="svg-line" d="M608 47l7 6-7 6"/>
  255. <rect class="svg-box green" x="216" y="146" width="376" height="58" rx="9"/>
  256. <text class="svg-text" x="236" y="171">VFS load → process_create_user</text>
  257. <text class="svg-sub" x="236" y="191">ELF segments · page directory · 32-page stack · arg</text>
  258. <rect class="svg-box amber" x="628" y="146" width="270" height="58" rx="9"/>
  259. <text class="svg-text" x="646" y="171">kernel process</text>
  260. <text class="svg-sub" x="646" y="191">ring 0 · pinned to the BSP</text>
  261. <path class="svg-line accent" d="M502 82v54"/>
  262. <path class="svg-line accent" d="M496 128l6 7 6-7"/>
  263. <path class="svg-line" d="M763 82v54"/>
  264. <path class="svg-line" d="M757 128l6 7 6-7"/>
  265. </svg>
  266. <figcaption>
  267. <strong>A packed command can shadow a kernel command.</strong>
  268. The PATH is searched before the kernel registry, so a new
  269. <code>bin/&lt;name&gt;</code> changes behaviour without editing the
  270. kernel. Builtins are handled inline, before either lookup.
  271. </figcaption>
  272. </figure>
  273. <p>
  274. <code>SYS_SPAWN</code> takes a <code>struct sys_spawn</code> with
  275. path, argument, cwd, tty and a flags word. The default parent is
  276. the caller; <code>SYS_SPAWN_DETACH</code> attaches the child to the
  277. caller's parent (the terminal/WM session), or to PID 0 when that
  278. parent is gone. Every process has a <code>parent_pid</code>: exit,
  279. kill and the reaper recursively kill descendants, so closing a
  280. terminal kills its commands, closing the WM kills its apps, and an
  281. init crash resets the userland tree. File managers, chat and the
  282. WiFi helpers use detached spawns for launched apps/daemons; terminal
  283. commands and <code>SYS_SPAWN_KCMD</code> stay parented. The browser
  284. and gallery launchers spawn the real app parented and wait for it,
  285. so a terminal launch is foreground and Ctrl-C kills the app.
  286. </p>
  287. </section>
  288. <section id="syscalls">
  289. <h2>Syscall ABI</h2>
  290. <p>
  291. The gate is <code>int 0x80</code>. <code>eax</code> carries the
  292. number, <code>ebx</code>/<code>ecx</code>/<code>edx</code> the first
  293. three arguments, and the negative <code>SYS_E*</code> codes are
  294. stable. The wrappers in <span class="file">ucmd_lib.h</span> cover
  295. zero to three arguments.
  296. </p>
  297. <div class="table-wrap">
  298. <table>
  299. <thead>
  300. <tr><th>Group</th><th>Numbers</th><th>Purpose</th></tr>
  301. </thead>
  302. <tbody>
  303. <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>
  304. <tr><td>Files</td><td>5–11, 48, 98</td><td>whole-file read/write, list, unlink, mkdir/rmdir, mounts, cwd, stat</td></tr>
  305. <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>
  306. <tr><td>Network</td><td>17–47, 106</td><td>NIC config/acquire, raw frames, DHCP/DNS/NTP, TCP client, ARP, cwd</td></tr>
  307. <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>
  308. <tr><td>Process &amp; memory</td><td>73–79, 81, 88–90, 108, 124–127</td><td>TTY create/alloc/read/write/close, spawn flags, getpid, alive, kill subtree, chdir, scheduler info, heap alloc/grow/free, is-init</td></tr>
  309. <tr><td>TCP server</td><td>93–97, 99–101</td><td>listen, accept, server recv/send/close, peer, speed, MAC set</td></tr>
  310. <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>
  311. <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>
  312. <tr><td>Hardware settings</td><td>113–114</td><td><code>SYS_BACKLIGHT(op, value)</code> get/set/step the panel PWM, <code>SYS_CPUFREQ(mode)</code> get/set the P-state mode (control panel sliders/tiles)</td></tr>
  313. <tr><td>Popover layout</td><td>115–116</td><td><code>SYS_WIN_RESIZE_SELF(w, h)</code> resizes the caller's canvas, <code>SYS_SCREEN_INFO(out)</code> returns the framebuffer dimensions (the control panel collapses/grows)</td></tr>
  314. <tr><td>Boot log</td><td>122</td><td><code>SYS_BOOTLOG(STAT|READ, ...)</code> returns the ring counters or one 1 KB chunk of the <code>bootscan</code> thread's captured COM1 output (the <code>bootscan</code> window)</td></tr>
  315. <tr><td>Storage</td><td>119–120</td><td><code>SYS_BLK_READ(index, lba, buf)</code> reads one raw sector, <code>SYS_MOUNT_CTL(op, ...)</code> sets/gets a mount policy (name, read-only, no automount); used by <code>disks</code></td></tr>
  316. <tr><td>Mouse cursor</td><td>117–118, 121</td><td><code>SYS_WIN_SET_CURSOR(shape)</code> sets the caller's content cursor, <code>SYS_WM_SET_CURSOR(shape | -1)</code> is the WM's override for its chrome, and <code>SYS_WM_MOUSE_CAPTURE(on)</code> takes/releases the pointer while the WM drags or resizes a window (shapes in <span class="file">cursor_abi.h</span>)</td></tr>
  317. <tr><td>Wallpaper</td><td>123</td><td><code>SYS_WM_WALLPAPER(1)</code> bumps <code>wm_status.wallpaper_seq</code> after a client writes the RGB565 wallpaper file; the WM reloads it and repaints the desktop</td></tr>
  318. </tbody>
  319. </table>
  320. </div>
  321. <p>
  322. The file service is whole-file, not stream-oriented. The network
  323. service has a per-process TCP client table (up to twelve connections)
  324. and a separate raw NIC lease for packet-level commands. There is no
  325. <code>fork</code>, <code>exec</code> or shared memory: a command
  326. either runs as its own process from an ELF or calls a kernel command.
  327. </p>
  328. </section>
  329. <section id="shell">
  330. <h2>Shell &amp; PATH</h2>
  331. <p>
  332. The windowed shell is <span class="file">ucmd_term.c</span>; the
  333. kernel-side <span class="file">terminal.c</span> holds the privileged
  334. command registry used through <code>SYS_SPAWN_KCMD</code>. There is
  335. no kernel terminal fallback; the WM spawns the <code>bootscan</code>
  336. log window first and the first terminal after it (the newest
  337. window, so it keeps the keyboard focus). Each terminal has a
  338. current working directory and a PATH (default
  339. <code>/ramfs/bin</code>). Pressing Tab completes builtin and PATH
  340. names; <code>help</code> lists both.
  341. </p>
  342. <ul>
  343. <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>
  344. <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 that dumps the early boot console; <code>bootscan</code> is the ring-3 live scan window.</li>
  345. <li><strong>Arguments.</strong> The raw remainder of the line is passed verbatim; commands parse their own flags.</li>
  346. <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>
  347. <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>
  348. </ul>
  349. </section>
  350. <section id="registry">
  351. <h2>Kernel commands</h2>
  352. <p>
  353. These commands must run in ring 0 or inline in the shell; they are not
  354. files in the pack. The split keeps privileged hardware access out of
  355. ring 3 while most user-facing tools remain replaceable ELFs.
  356. </p>
  357. <div class="table-wrap">
  358. <table>
  359. <thead>
  360. <tr><th>Group</th><th>Commands</th></tr>
  361. </thead>
  362. <tbody>
  363. <tr><td>Shell</td><td><code>cd</code> <code>path</code> <code>help</code> <code>clear</code> <code>bootlog</code></td></tr>
  364. <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>
  365. <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>backlight</code> <code>keytest</code> <code>format</code> <code>install</code> <code>dbg</code> <code>serial</code></td></tr>
  366. <tr><td>Network control</td><td><code>netdev</code></td></tr>
  367. <tr><td>Boot / power</td><td><code>reboot</code> <code>poweroff</code> <code>kexec</code></td></tr>
  368. </tbody>
  369. </table>
  370. </div>
  371. <p>
  372. <code>format &lt;device&gt; [size]</code> creates a FAT filesystem.
  373. <code>install &lt;target&gt; [source|self]</code> installs NebOS.
  374. Both take a leading <code>-y</code> that skips the y/n prompt; the
  375. <code>disks</code> app confirms in its own dialog and passes it.
  376. With a source it auto-detects a disk whose MBR and LBA-63 boot
  377. sector carry the NebOS signature (preferring <code>usb0</code>),
  378. reads P1..P3 into RAM, creates or keeps the <code>NEBOSDATA</code>
  379. partition at LBA 34816, writes the target from RAM, merges the data
  380. entry into the MBR, writes the MBR last and verifies the result. A
  381. source-read failure leaves the target untouched. <code>self</code>
  382. writes the running gzip pack and its bundled kernel without a USB
  383. stick; <code>auto</code> picks the only non-USB NebOS disk. The
  384. data partition survives both forms, while the P1..P3 OS image and
  385. the app pack are replaced. Both the BIOS and UEFI paths are cloned
  386. on a full install; a later self-update leaves the ESP alone.
  387. </p>
  388. </section>
  389. <section id="pack">
  390. <h2>Command pack</h2>
  391. <p>
  392. The pack is built from the <code>UCMDS</code> list in the Makefile
  393. (one <code>user/apps/&lt;name&gt;/</code> directory each) as
  394. <code>bin/&lt;name&gt;</code>, plus <code>hello</code> and the real
  395. <code>browser.app</code> (full pack only) and <code>gallery.app</code>. It is mounted
  396. read-only at <code>/ramfs</code>; the shell's default PATH points at
  397. <code>/ramfs/bin</code>.
  398. </p>
  399. <div class="grid">
  400. <div class="card">
  401. <h3>Files &amp; text</h3>
  402. <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>
  403. </div>
  404. <div class="card">
  405. <h3>System</h3>
  406. <p><code>init</code> <code>service</code> <code>cpuinfo</code> <code>meminfo</code> <code>storage</code> <code>top</code> <code>process</code> <code>mouseinfo</code> <code>touchpad</code> <code>sensors</code> <code>powerinfo</code> <code>date</code> <code>spin</code> <code>membench</code> <code>clock</code> <code>colors</code></p>
  407. </div>
  408. <div class="card">
  409. <h3>Network</h3>
  410. <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>
  411. </div>
  412. <div class="card">
  413. <h3>GUI</h3>
  414. <p><code>wm</code> <code>term</code> <code>bootscan</code> <code>files</code> <code>disks</code> <code>view</code> <code>mines</code> <code>solitaire</code> <code>process</code> <code>service --gui</code> <code>gallery</code> <code>browser</code> <code>chat</code> <code>clock</code> <code>colors</code> <code>settime</code></p>
  415. </div>
  416. </div>
  417. <p>
  418. The launchers <code>bin/browser</code> and <code>bin/gallery</code>
  419. forward their argument and cwd, and prefer a development copy under
  420. <code>/share</code> (<code>BROWSER</code> or <code>GALLERY</code>)
  421. before the pack copy and the FAT fallback on <code>root.img</code>.
  422. This lets <code>make browser-dev</code> and <code>make gallery-dev</code>
  423. update an app without rebuilding the pack. The launchers spawn
  424. the real app as a parented child and wait for it, so a terminal
  425. launch stays foreground and Ctrl-C/terminal close kills the app;
  426. when a GUI app launches them, that app uses a detached spawn so
  427. the launcher/app subtree survives the file manager or chat window
  428. but still dies with the terminal/WM session.
  429. </p>
  430. </section>
  431. <section id="apps">
  432. <h2>GUI applications</h2>
  433. <ul>
  434. <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>
  435. <li><strong>bootscan</strong> — live tail of the boot storage-scan kernel thread's output (the WM opens it before the terminal, flush right under the top bar). The kernel captures the thread's COM1 trail (mounts, probes, boot traces) into a ring exposed by <code>SYS_BOOTLOG</code>; the window follows the tail while the scan runs, keeps the scrollback afterwards, pauses the follow when scrolled up, and closes with Esc. The deferred USB mount pass runs after the window's ring closes, so its lines appear on COM1/netmon but not in the bootscan scrollback. Also startable from the shell.</li>
  436. <li><strong>process</strong> — graphical task manager (start menu <em>Tasks</em> entry or <code>process</code>), the ngui counterpart of <code>top</code>. It samples once per second into 60 s histories of CPU busy (<code>SYS_SCHEDINFO</code> idle ticks summed over all CPUs), physical memory in use (<code>SYS_MEMINFO</code>) and NIC throughput (<code>SYS_NET_INFO.rx_bytes</code>/<code>tx_bytes</code> from the netdev frame counters), then draws the three graphs with ngui rectangles and lines. The table is a process tree: it lists PID, state, CPU%, memory, total CPU time and name, indents children under their <code>parent_pid</code>, and still sorts sibling groups by PID, state, CPU, memory, time or name when a header is clicked; PgUp/PgDn or the wheel scrolls. Selecting a row shows its pid/ppid and details; <em>End task</em> asks for a second click and then calls <code>SYS_KILL</code> (which kills the subtree), while kernel threads (<code>kernel_thread</code> in the process snapshot), the monitor itself and init are protected. Esc closes it.</li>
  437. <li><strong>disks</strong> — storage manager (start menu <em>Disks</em> entry, or the <em>Disks</em> button in <code>files</code>): devices, MBR partitions and mounts; per-volume mount name, read-only and automount saved to <code>/data/MOUNTS.CFG</code>; Format and Install NebOS dialogs that run <code>format -y</code>/<code>install -y</code> on a private tty and show the log. See <a href="filesystems.html#disks">Filesystems → Storage manager</a>.</li>
  438. <li><strong>gallery</strong> — live widget and primitive showcase; the real app ships in the pack.</li>
  439. <li><strong>service</strong> — the init client: <code>service</code> lists <code>init</code>, <code>wm</code> and the user services, <code>status/start/stop/restart/kill/logs/logtail</code> act through init, and <code>service --gui</code> (or the start menu's <em>Services</em> entry) opens the ngui service list with Start/Stop/Restart/Kill (Kill needs a second click) and a live log pane. It is a stateless client: state and logs are read from <code>/share</code>, actions go over init's control tty.</li>
  440. <li><strong>chat</strong> — native Cloudron Chat client (start menu <em>Chat</em> entry, 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, inline image attachments, link-preview cards (click one to open it in the browser) and profile-picture avatars, sending, REST polling, read markers, browse/join and new DM. The session cookie (never the password) is saved in <code>/data/CHAT.CFG</code> when the persistent volume is mounted, or in the RAM-only <code>/share/chat.cfg</code> otherwise. 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>
  441. <li><strong>solitaire</strong> — Klondike with drag-and-drop, scoring and a win animation.</li>
  442. <li><strong>mines</strong> — second ngui canvas app; shares the toolkit and event model.</li>
  443. <li><strong>view</strong> — fit/1:1/zoom/pan image viewer, animated GIF playback. Its <em>Background</em> button (or <code>b</code>) cover-scales the image to a screen-aspect RGB565 wallpaper, writes <code>/data/WALLPAPR.BIN</code> when the data volume is mounted (otherwise the RAM-only <code>/share/wallpaper</code>), and signals the WM; the status bar reports the result.</li>
  444. <li><strong>edit</strong> — text editor that draws its own text with the 8x16 font.</li>
  445. <li><strong>clock</strong> / <strong>colors</strong> — small window canvas demos.</li>
  446. <li><strong>settime</strong> — the standalone Date &amp; Time editor (the control panel has an inline editor on its Date &amp; Time tile). 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>
  447. <li><strong>netmenu</strong> — the top-bar control panel, opened by clicking anywhere in the right top-bar status area (temperature, date/time, network and AC/battery items). It is a chromeless <code>WIN_F_POPOVER</code> canvas window, anchored flush under the bar at the right screen edge, dismissed by a click outside or <code>Esc</code>, and has no title bar, shadow or rounded outer corners. It opens collapsed: the battery/AC and clock summary, a brightness slider when the panel PWM is present, and Quick settings pills for Network, the P-state power mode (<code>SYS_CPUFREQ</code>) and Date &amp; Time. Clicking a pill expands that section in place and grows the window with <code>SYS_WIN_RESIZE_SELF</code>; the network section has the connection status card and NIC/WiFi lists, the power section has the three modes, and the date section has an inline editor (Set/Now/Sync NTP) instead of opening <code>settime</code>. It 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 the network is not saved 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. Networks in <code>/data/WIFI.CFG</code> are marked <em>saved</em> and join with the stored passphrase; a <em>Saved</em> view lists them with a <em>Forget</em> button each. A Connection section shows IP, gateway, DNS and MAC. On success the helper moves the SSID/passphrase to the front of the saved list; the next boot's <code>wifi autoconnect</code> helper joins any saved network found. Duplicate BSSIDs for one SSID are collapsed to the strongest entry (or the active one), and hidden networks are omitted.</li>
  448. <li><strong>wm</strong> / <strong>term</strong> — the ring-3 window manager and terminal launcher used by the desktop.</li>
  449. </ul>
  450. <p>
  451. The WM chrome, ngui labels and the browser use the fixed-point
  452. TrueType engine in <span class="file">ufont.c</span> with the Arimo
  453. and Liberation Mono subsets in the pack. CSS and ngui can select
  454. regular/bold/italic/mono faces at 8–48 px; missing faces fall back to
  455. the 8×16 bitmap. UTF-8 text APIs additionally fall back to the
  456. monochrome Noto Emoji subset for common emoji (format-12 cmap);
  457. the browser still uses the Latin-1 byte path. Terminal contents and
  458. the editor stay bitmap;
  459. ngui text fields use the proportional face for text, caret,
  460. selection and horizontal scrolling. The browser detaches the font
  461. arena before <code>heap_reset()</code> and reattaches after the page
  462. heap is mapped.
  463. </p>
  464. </section>
  465. <section id="browser">
  466. <h2>Browser</h2>
  467. <p>
  468. The real browser is <code>bin/browser.app</code> in the full pack; the
  469. floppy lite pack omits it and the <code>bin/browser</code> launcher runs
  470. <code>BROWSER</code> from <code>root.img</code> instead. It links
  471. ngui, the image library, inflate, TLS, uhttp and the vendored QuickJS
  472. engine. It opens at 1100×700 (960×640 and 780×540 fallbacks on
  473. smaller screens), with a URL bar, history, a status bar, inline
  474. images and inline/external scripts. Network work runs in up to four
  475. headless <code>curl __serve</code> workers, each with its own files
  476. under <code>/share</code>, so the UI keeps drawing and scrolling
  477. while several TCP/TLS connections are in flight. Images are
  478. decoded at their CSS/attribute box in the fetch helper (a JPEG
  479. gets a reduced IDCT) and cached at display size, so a repaint is
  480. a 1:1 blit; image repaints are coalesced and
  481. <code>/share/IMGSTAT</code> records where a load spent its time.
  482. </p>
  483. <ul>
  484. <li><strong>HTML/CSS subset.</strong> External and inline stylesheets; one selector engine for the cascade, <code>querySelector(All)</code> and <code>matches</code> (type/class/id, attribute values with <code>= ~= |= ^= $= *=</code> and the <code>i</code> flag, descendant/<code>&gt;</code>/<code>+</code>/<code>~</code> combinators, <code>:root</code>, <code>:link</code>, first/last/only child and of-type, <code>:nth-child</code>/<code>:nth-last-child</code>/<code>:nth-of-type</code>/<code>:nth-last-of-type</code>, <code>:empty</code>, <code>:checked</code>, <code>:disabled</code>/<code>:enabled</code>, <code>:required</code>/<code>:optional</code>, <code>:not</code>/<code>:is</code>/<code>:where</code> with selector lists and <code>:has</code>); <code>::before</code>/<code>::after</code> generated text (strings, <code>attr()</code>, quotes) emitted as literal runs that scripts never see; 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; <code>px</code>, <code>pt</code>, <code>%</code>, <code>em</code>, <code>rem</code>), the <code>font</code> shorthand, bold/italic faces, <code>font-family: monospace</code> and <code>@font-face</code> web fonts (local or HTTP TTF/OTF or WOFF&nbsp;1.0, picked from the <code>src</code> list by <code>format()</code>; one face per weight/style of a family, matched at layout; non-Latin <code>unicode-range</code> subsets skipped; only families the page names are downloaded, and cached in <code>/share</code> for the boot), 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>aspect-ratio</code>, <code>margin: 0 auto</code>, a definite-width table centred by a <code>&lt;center&gt;</code> parent or <code>align=center</code> (Hacker News), 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 (auto layout: min-content plus a share of the rest when the one-line widths do not fit, so long text cells wrap), <code>calc(percent ± px)</code> in widths, margins/padding, heights and min/max, <code>white-space: nowrap</code> and <code>@media</code> blocks (including the <code>(width &gt;= 997px)</code> range form) evaluated at the browser canvas width when the page is parsed, with <code>matchMedia()</code> giving scripts the same answers (environment features answer for a normal-contrast mouse screen: <code>forced-colors: none</code>, <code>hover: hover</code>, <code>pointer: fine</code>, no reduced motion). <code>@layer</code> blocks cascade in layer order (unlayered rules above every layer, <code>!important</code> reversed) and <code>@supports</code> blocks apply unless negated; Docusaurus ships its whole stylesheet in layers. After <code>var()</code> expansion each <code>calc()</code> is folded (<code>*</code>, <code>/</code>, nesting, %, px, rem/em, vw) into a length or <code>calc(P% + Npx)</code>, and <code>var()</code> keeps token boundaries in minified shorthands. A definite <code>flex-basis</code> sets a flex item's width and items honour <code>min-width</code>/<code>max-width</code>. A single-line flex row fills its container's definite height and stretches items without a height to the line (<code>align-items: stretch</code>); <code>flex-direction: column</code> distributes the free height with <code>justify-content</code> and shrinks <code>start</code>/<code>center</code>/<code>end</code> items to their content; absolute children of a flex container are out of flow. A box placed by <code>bottom</code> without a height uses its measured height, and a fixed box without <code>left</code>/<code>right</code> keeps its static x. The page has no gutter of its own: <code>body</code> carries the usual 8 px UA margin, so <code>body { margin: 0 }</code> starts at the canvas edge. The Cloudron login page (a full-height logo panel beside a centred form) lays out like in a desktop browser. A page whose markup starts <code>&lt;!doctype html&gt;&lt;html&gt;</code> keeps the root element's cascade (colour, font, line-height) for the whole page; <code>&lt;svg&gt;</code> is inline by default; weight 500 uses the regular face. Inline <code>&lt;style&gt;</code> text is collected up to 256 KB and URLs may be 4 KB long. Scripting is always on, so <code>&lt;noscript&gt;</code> content is inert raw text. Form controls with author CSS (background, border or radius) are painted and sized from the page's style, so google.com's search buttons and transparent search field look like the page intends; unstyled controls keep the theme look. Text is Latin-1; there is no shaping, bidi, WOFF2/CFF font or full-Unicode fallback.</li>
  485. <li><strong>JavaScript.</strong> Inline and external <code>&lt;script src&gt;</code> blocks run on the vendored QuickJS engine (2026-06-04, ES2025: classes and private fields, arrow functions, <code>let</code>/<code>const</code>, template literals, destructuring, spread, async/await, Promise, Map/Set, BigInt, optional chaining) in document order. <code>js_mu.c</code> keeps the MuJS-style value-stack API the DOM layer was written against, runs outermost engine entries on a private 1 MB stack (the ring-3 stack is 128 KB) and drains Promise jobs after each script, timer and event. External scripts use the same local/network fetch path as pages and CSS (2 MB cap) and are cached under <code>/share/bjs-*</code> for the current boot; the parsed page is painted before scripts run. <code>&lt;script type="module"&gt;</code> runs as an ES module: QuickJS resolves every import to an absolute URL and loads it synchronously through the browser (script cache first, then one helper fetch), <code>import()</code> and <code>import.meta.url</code> work, and the page's <code>&lt;link rel="modulepreload"&gt;</code> chunks are fetched on all helpers in parallel before the first script runs. Unhandled promise rejections are reported like uncaught exceptions, at the end of the job run, so a rejection whose handler is attached later in the same turn is not reported. Classic scripts are sloppy by default. Math, Date and JSON are the engine's; each page gets one state, and a 20 s wall-clock budget per script, timer or event turns a runaway loop into an <code>InternalError: interrupted</code> instead of freezing the browser. The Cloudron app store (AngularJS 1.3, a 666 KB inline catalogue and an ES2015 controller) renders its hero carousel, 26 sections and 308 cards.</li>
  486. <li><strong>Web APIs.</strong> <span class="file">js_prelude.js</span> (embedded by <span class="file">js_prelude.S</span> after <span class="file">tools/jsstrip.c</span> drops its comments and indentation) runs before each page's scripts and builds the platform in JavaScript on three C primitives: <code>fetch</code>/<code>Request</code>/<code>Response</code>/<code>Headers</code> and <code>XMLHttpRequest</code> (synchronous helper requests of any method, delivered through a Promise; the status and body come back for 4xx/5xx too), <code>URL</code>/<code>URLSearchParams</code>, <code>TextEncoder</code>/<code>TextDecoder</code>, <code>btoa</code>/<code>atob</code>, <code>Blob</code>/<code>FormData</code>, <code>AbortController</code>, <code>localStorage</code>/<code>sessionStorage</code> (kept in <code>/share</code> per origin, so they survive the page-heap reset of a navigation; with <code>/data</code> mounted, localStorage and the cookie jar are also saved to <code>/data/BSTORE.DAT</code> and <code>/data/BCOOKIES.BIN</code> at most every 3 s and restored after a reboot), <code>crypto.getRandomValues</code>/<code>subtle.digest("SHA-256")</code>, an en-US <code>Intl</code> (QuickJS has none: <code>DateTimeFormat</code> in UTC, <code>NumberFormat</code>, <code>RelativeTimeFormat</code>, <code>DurationFormat</code>, <code>DisplayNames</code>, <code>Collator</code>, <code>PluralRules</code>, <code>ListFormat</code>, plus ICU-like <code>localeCompare</code> and option-aware <code>toLocale*String</code>; the dashboard's Domains view formats its task dates with it), form constraint validation (<code>checkValidity</code>/<code>reportValidity</code>: required, length, pattern, email/url, number range), inert observers, <code>performance</code> (page-relative <code>now()</code>, <code>timing</code>, User Timing marks and measures), the <code>CSS</code> namespace (<code>escape</code>, <code>supports</code>), <code>NodeFilter</code>/<code>document.createNodeIterator</code>, prototype accessors for the node members DOMPurify reads through <code>Object.getOwnPropertyDescriptor</code>, <code>instanceof</code>-able DOM classes and the common Element methods (<code>closest</code>, <code>append</code>, <code>before</code>/<code>after</code>, <code>insertAdjacentHTML</code>, ...). Custom Elements (<code>customElements.define</code>, upgrades with <code>connectedCallback</code>) run web-component sites such as heise.de, whose <code>&lt;a-img&gt;</code> picks a scaled CDN image once visible. <code>document.currentScript</code>, the <code>document.scripts</code>/<code>images</code>/<code>forms</code>/<code>links</code> collections, inert <code>&lt;template&gt;</code> elements with a <code>content</code> fragment, and an inert detached document for <code>DOMParser</code>/<code>createHTMLDocument</code> (a parsed document is split at its head and body, and the page document's lookups called on it answer for it, so DOMPurify sanitizes the parsed copy and not the page) let jQuery 3 and Alpine.js boot arstechnica.com (a Tailwind page served over TLS 1.2): before, jQuery's support probe wrote two <code>&lt;form&gt;</code>s over the real body. A <code>#fragment</code>-only navigation (<code>location.hash</code>, <code>#...</code> links, back/forward) updates the URL in place and fires <code>hashchange</code> instead of reloading, which hash-routed apps rely on. With them the Cloudron dashboard (a Vite/Vue 3 app of 12 modules, 3.5 MB) boots, starts its PKCE login and renders the OIDC login form, which submits through <code>fetch()</code>.</li>
  487. <li><strong>DOM.</strong> Nodes are interned userdata wrappers that inherit from <code>Object.prototype</code>, 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; an inline span, or an inline-block that stays in the text line, reports the union of its placed line runs, one line box tall per line). 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. A geometry read after a DOM change runs a synchronous layout first (a forced reflow, at most eight per main-loop pass), and <code>documentElement.clientWidth</code>/<code>clientHeight</code> are the viewport. Moving the pointer dispatches <code>mouseover</code>/<code>mouseout</code> (bubbling, with <code>relatedTarget</code>) and <code>mouseenter</code>/<code>mouseleave</code> on the ancestors entered or left, so jQuery hover handlers and Bootstrap tooltips work; there is no <code>mousemove</code>. A transparent or <code>visibility: hidden</code> absolute/fixed box keeps a measurable box but is not painted or hit-tested. <code>opacity</code> is a real alpha: a translucent absolute/fixed box is painted and blended over what lies beneath it (a 50% modal backdrop), and <code>transition</code> animates <code>opacity</code> and <code>translate()</code> (percentages of the element's own box): the paint pass remembers each element's last value, a change on an element with a matching transition interpolates from the value on screen with the declared easing, the page re-renders until it ends, and <code>transitionend</code> fires. The start state is whatever the last paint saw, and a forced reflow is a paint pass, so Bootstrap's modal (shown, measured, then given <code>.in</code>) fades its backdrop in and slides its dialog down. Painted absolute/fixed boxes with a background or a <code>z-index</code> cover what is beneath them for clicks and hover (unless <code>pointer-events: none</code>), so a click on a modal's backdrop reaches the modal instead of the page.</li>
  488. <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>defer</code>/<code>async</code> ordering, Mutation/Resize observers that fire (the IntersectionObserver reports every target visible), streaming/binary/multipart <code>fetch</code> bodies and request headers other than <code>Content-Type</code>, an XML <code>DOMParser</code>, canvas/2D/WebGL contexts (<code>getContext()</code> returns <code>null</code>, so WebGL map libraries fail with their own message), user-state pseudo-classes (<code>:hover</code>, <code>:focus</code>; their rules are dropped at parse time) and pseudo-elements other than <code>::before</code>/<code>::after</code>. 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. <code>innerHTML</code>/<code>outerHTML</code> serialize the live tree.</li>
  489. <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), generated-content boxes beyond icons (<code>::before</code>/<code>::after</code> are text, or an empty box with a background colour and a <code>data:</code> background image such as Docusaurus' sidebar chevrons: no borders, counters, <code>content: url()</code> or remote images, and none inside flex/grid containers), <code>bottom</code>/percentage <code>left</code> placement of nested absolute boxes, border-radius clipping of descendants, gradients/box-shadow, transitions other than <code>opacity</code> and <code>translate()</code> (and translucency of in-flow elements) and <code>color-mix</code>. Flex rows, card grids, tables with rowspan/colspan, inline SVG and CSS variables are supported. Custom properties live in one document-wide table: <code>:root</code>/<code>html</code>/<code>body</code> definitions always apply, a component-level one only while no other rule disagrees (then <code>var()</code> falls back); a rule that uses such a name is re-expanded per element against that element's own matched rules (Infima's <code>.col--3</code> sets the column width another rule reads), but values set on ancestors are not inherited. Percentage heights resolve against the containing block's definite height (the viewport for <code>html</code>/<code>body</code>) and act as a minimum, because inner boxes do not scroll. A centred icon no longer centres the text that follows it, and <code>align-items: center</code> centres the lines of a flex column.</li>
  490. <li><strong>Inline SVG.</strong> <span class="file">svg_raster.c</span> flattens every path command (curves and arcs included), rects, circles, ellipses, lines, polylines and polygons through <code>transform</code> lists and the viewBox mapping, then fills (nonzero or even-odd) and strokes them with antialiased coverage into an RGB565 + alpha layer cached per node and size. <code>&lt;g&gt;</code>, nested <code>&lt;svg&gt;</code>, <code>&lt;use&gt;</code> of a <code>&lt;symbol&gt;</code>, opacity, <code>currentColor</code> and inherited <code>fill</code>/<code>stroke</code> work; a gradient paints the average of its stops, and patterns, clip paths, masks, filters and markers are not rendered. SVG paint has its own style state, so CSS <code>fill</code> on an HTML element no longer paints its background.</li>
  491. <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>
  492. <li><strong>Fetching.</strong> Up to four 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. Stylesheet and external-script bodies are downloaded in parallel but parsed/executed in document order, and one image starts before the script phase so it overlaps script loading. Idle helpers stay warm for same-origin navigations (they exit after ten idle seconds, and losing window focus stops them), while a cross-origin navigation closes them first so the old page's connections cannot stall the new fetch. A DNS failure is retried once. While loading, the status bar reports the page fetch's header and first-byte times; when the load is done it shows <code>Loaded in N ms: page P (headers H), parse, css, paint, js</code> for 12 s. On the Cloudron store under QEMU/TCG with e1000 that is 2572 ms, of which the scripts take 1911 ms; QuickJS is built <code>-O1</code>, which beat <code>-Os</code> and <code>-O2</code> there.</li>
  493. <li><strong>Downloads.</strong> Right-clicking the page opens a small context menu: over an <code>&lt;img&gt;</code> or a CSS <code>background-image</code> it offers <em>Save image</em>, over a link <em>Save link</em>, and anywhere <em>Save page</em>. A download is queued, fetched by a dedicated fifth <code>curl __serve</code> helper (so it survives navigation and the page workers stopping), then copied into <code>/data/DOWNLOAD</code>, or <code>/share/DOWNLOAD</code> when no installed data volume exists. Files use FAT-safe 8.3 names derived from the URL basename, with <code>~1</code> suffixes for collisions and a MIME-type extension when the URL has none; the 4 MB helper body cap applies. The toolbar's download button opens a panel with the newest twelve entries, live percentage and progress bar for the active one, sizes for finished files, and errors for failures. History is kept in <code>/share/bdownloads</code> and <code>/data/BDOWN.DAT</code> (<code>NBDL1</code>, then state/size/name/path records), so it survives a reload and, on installed boards, a reboot; <em>Clear</em> removes completed entries. One download runs at a time, and downloads continue in the background while the page scrolls or a new page loads.</li>
  494. <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>
  495. <li><strong>History and autocomplete.</strong> Every page that finishes loading is recorded in a 128-entry table (URL, title, visit count and a stamp counter that orders visits across windows and reboots without a clock). Browser windows of one boot share <code>/share/bhist</code>, merged and rewritten on each visit, and it is saved to <code>/data/BHIST.DAT</code> at most every 3 s. While the address bar has the focus a dropdown lists up to six matches: an empty bar shows the most visited and recent sites; typing ranks URL prefixes (with or without the scheme and <code>www.</code>) above URL and title substrings. Typing at the end completes inline to the next <code>/</code> of the best match (<code>clo</code> &rarr; <code>cloudron.io/</code>, the added part selected), and Enter opens the history URL it came from. Up/Down preview a row, Delete forgets it, Esc closes the list and a click opens a row.</li>
  496. </ul>
  497. <p>
  498. The browser's default canvas is dark, matching the ngui theme, but an
  499. <code>html</code>/<code>body</code> background fills the whole page
  500. canvas. Pages without one that set dark text can be hard to read;
  501. pages with their own background and colour rules are unaffected. See <a href="graphics.html#images">Graphics → Image
  502. library</a> for the decoder limits.
  503. </p>
  504. <p>
  505. <code>testdata/browser/compat/</code> is the browser compatibility
  506. ladder: numbered, self-contained pages with an A/B pair for each
  507. behaviour. Run <code>make compat-serve</code> and open
  508. <code>http://&lt;host&gt;:8000/</code> on the board (or
  509. <code>http://10.0.2.2:8000/</code> in QEMU's user network). The
  510. index records the current pass/fail status; pages 010–074 and 030a pass
  511. (036a needs the POST echo server), while
  512. the README lists the remaining gaps.
  513. </p>
  514. </section>
  515. <section id="sources">
  516. <h2>Source map</h2>
  517. <ul class="filelist">
  518. <li><code>kernel/syscall.c</code>, <code>kernel/syscall_stub.S</code>, <code>include/syscall.h</code></li>
  519. <li><code>kernel/sys_info.c</code> — kernel-state snapshots (memory, sensors, power)</li>
  520. <li><code>kernel/rtc.c</code> — CMOS RTC read/write, format decoding and the 1970–2069 year window</li>
  521. <li><code>kernel/process.c</code> — ELF load and spawn, parent tracking and subtree kill</li>
  522. <li><code>kernel/init.c/h</code> — PID-1 init bootstrap, protection and restart</li>
  523. <li><code>kernel/elf.c</code> — ELF parser</li>
  524. <li><code>user/apps/init/ucmd_init.c</code> — init service manager, WM supervisor, logs/state and control tty</li>
  525. <li><code>user/apps/service/ucmd_service.c</code>, <code>service_proto.c</code>, <code>service_defs.c</code>, <code>user/service_proto.h</code> — <code>service</code> CLI/GUI, shared units and the init protocol</li>
  526. <li><code>user/apps/term/ucmd_term.c</code> — windowed shell, scrollback, PATH</li>
  527. <li><code>kernel/terminal.c</code> — privileged kernel command registry</li>
  528. <li><code>kernel/install.c</code> — privileged live-image clone installer</li>
  529. <li><code>user/ucmd_lib.h</code> — user shim</li>
  530. <li><code>user/lib/libc/</code> — headers, malloc, string/stdlib, setjmp/errno, stdio/dtoa, math, time and the <code>SYS_MEM_*</code> backend</li>
  531. <li><code>libc.a</code> — optional static ring-3 libc</li>
  532. <li><code>user/ucmd.ld</code> — ring-3 link address</li>
  533. <li><code>Makefile</code> — <code>UCMDS</code> and pack rules</li>
  534. <li><code>user/apps/&lt;name&gt;/ucmd_&lt;name&gt;.c</code> — commands, one directory each</li>
  535. <li><code>user/lib/ufont/ufont.c</code>, <code>user/lib/ufont/ufont_ttf.c</code>, <code>user/lib/ufont/ufont_woff.c</code> — fixed-point TrueType text, WOFF 1.0 unwrapping</li>
  536. <li><code>user/lib/ngui/ngui.c</code> — GUI toolkit; <code>fonts/*.ttf</code> — UI and emoji subsets</li>
  537. <li><code>user/apps/browser/browser.c</code>, <code>user/apps/browser/browser_html.c</code>, <code>user/apps/browser/svg_raster.c/h</code> (+ <code>user/apps/browser/svg_test.c</code>), <code>user/apps/browser/js_browser.c/h</code>, <code>user/apps/browser/js_prelude.js</code> + <code>user/apps/browser/js_prelude.S</code> (+ <code>tools/jsstrip.c</code>), <code>user/apps/browser/js_mu.c/h</code>, <code>third_party/quickjs/</code>, <code>user/apps/gallery/gallery.c</code></li>
  538. <li><code>user/apps/chat/ucmd_chat.c</code>, <code>user/apps/chat/chat_login.c</code>, <code>user/lib/ujson/ujson.c</code>, <code>user/lib/uhttp/uhttp_cookie.c</code> — chat client</li>
  539. <li><code>user/apps/wifi/ucmd_wifi.c</code>, <code>user/lib/wifi/wpa.c</code>, <code>user/lib/tls/wpa_crypto.c</code> — <code>wifi</code> command and the WPA2-PSK supplicant</li>
  540. <li><code>user/apps/disks/ucmd_disks.c</code> — storage manager</li>
  541. <li><code>user/apps/process/ucmd_process.c</code> — graphical task manager and its history graphs</li>
  542. <li><code>user/apps/bootscan/ucmd_bootscan.c</code> — live boot-scan log window (<code>SYS_BOOTLOG</code>, <code>kernel/bootcon.c</code>)</li>
  543. <li><code>user/apps/netmenu/ucmd_netmenu.c</code>, <code>include/wifi_cfg.h</code>, <code>user/lib/wifi/wifi_store.c/h</code> — top-bar control panel, staged WiFi connect record and saved-network list</li>
  544. </ul>
  545. </section>
  546. </main>
  547. <footer class="site-footer">
  548. <div class="inner">
  549. <p><strong>NebOS 0.2.0</strong> · Architecture documentation · <a href="index.html">overview</a></p>
  550. <p>Maintain alongside <code>AGENTS.md</code> and the source files listed on each page.</p>
  551. </div>
  552. </footer>
  553. </body>
  554. </html>