| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444 |
- <!doctype html>
- <html lang="en">
- <head>
- <meta charset="utf-8">
- <meta name="viewport" content="width=device-width, initial-scale=1">
- <title>Userland | NebOS Architecture</title>
- <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.">
- <link rel="icon" href="favicon.svg" type="image/svg+xml">
- <link rel="stylesheet" href="style.css">
- </head>
- <body>
- <a class="skip" href="#main">Skip to content</a>
- <header class="site-header">
- <a class="brand" href="index.html">
- <span class="brand-mark" aria-hidden="true"></span>
- <span>NebOS <span class="brand-sub">Architecture</span></span>
- </a>
- <nav class="site-nav" aria-label="Architecture sections">
- <a href="index.html">Overview</a>
- <a href="boot.html">Boot</a>
- <a href="memory.html">Memory</a>
- <a href="cpu.html">CPU</a>
- <a href="drivers.html">Drivers</a>
- <a href="filesystems.html">Filesystems</a>
- <a href="graphics.html">Graphics</a>
- <a href="network.html">Network</a>
- <a href="userland.html" aria-current="page">Userland</a>
- <a href="development.html">Development</a>
- </nav>
- </header>
- <main id="main" class="page">
- <div class="page-head">
- <p class="kicker">Userland</p>
- <h1>Commands are ELFs. The shell is a dispatcher.</h1>
- <p class="lede">
- Ring-3 programs are static ELFs linked at <code>0x40000000</code>.
- The shell resolves a command name against builtins, the per-terminal
- PATH and the kernel command registry, then spawns it with one
- argument string. The command pack supplies 47 PATH commands by default.
- </p>
- <div class="meta">
- <span class="pill">int 0x80</span>
- <span class="pill">one string argument</span>
- <span class="pill">47 PATH commands</span>
- <span class="pill">8 TTYs · 8 windows</span>
- </div>
- </div>
- <nav class="toc" aria-label="On this page">
- <h2>On this page</h2>
- <ul>
- <li><a href="#model">Ring-3 model</a></li>
- <li><a href="#libc">Ring-3 libc</a></li>
- <li><a href="#spawn">Spawn path</a></li>
- <li><a href="#syscalls">Syscall ABI</a></li>
- <li><a href="#shell">Shell & PATH</a></li>
- <li><a href="#registry">Kernel commands</a></li>
- <li><a href="#pack">Command pack</a></li>
- <li><a href="#apps">GUI applications</a></li>
- <li><a href="#browser">Browser</a></li>
- <li><a href="#sources">Source map</a></li>
- </ul>
- </nav>
- <section id="model">
- <h2>Ring-3 model</h2>
- <p>
- A user process gets a page directory cloned from the kernel identity
- map, a 4 MB image/stack window at <code>0x40000000</code>, an optional
- 4 MB canvas at <code>0x50000000</code> and a growable heap at
- <code>0x60000000</code>. The kernel remains mapped because paging is
- identity-mapped; this is isolation in privilege level only, not a
- separate address space.
- </p>
- <ul>
- <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>
- <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>
- <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>
- <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>
- </ul>
- <div class="note">
- <p><strong>Not a sandbox.</strong> Because physical and virtual addresses
- are identical and the kernel is mapped, a ring-3 bug can read or write
- any mapped kernel page. The privilege boundary protects against
- accidental corruption from ordinary code, not against malicious code.</p>
- </div>
- </section>
- <section id="libc">
- <h2>Ring-3 libc</h2>
- <p>
- <span class="file">libc.a</span> is optional: the Makefile links it
- only into commands that reference it, and the archive plus
- <code>--gc-sections</code> keeps unused members and functions out of
- the legacy command pack. The headers live in
- <span class="file">libc/include/</span> and cover
- <code>stddef</code>, <code>stdint</code>, <code>stdarg</code>,
- <code>stdlib</code>, <code>string</code>, <code>ctype</code>,
- <code>assert</code>, <code>setjmp</code>, <code>errno</code>,
- <code>stdio</code>, <code>math</code>, <code>time</code>,
- <code>sys/time</code>, <code>sys/types</code>, <code>float</code>,
- <code>limits</code>, <code>inttypes</code>, <code>alloca</code>
- and the OS-specific <code>ucmd_heap.h</code>.
- </p>
- <ul>
- <li><strong>malloc.</strong> Boundary-tag blocks, first-fit free
- list, immediate coalescing, 16-byte alignment. The heap maps 64 KB
- on first use and grows in page-rounded steps with 64 KB slack up to
- the 32 MB <code>SYS_MEM_*</code> arena cap; <code>calloc</code>
- zeroes and <code>realloc</code> grows in place when the next block
- is free.</li>
- <li><strong>heap_reset.</strong> Discards every allocation and
- unmaps the whole arena. Page-scoped programs such as the browser
- use it on navigation instead of tracking individual frees.</li>
- <li><strong>Ownership.</strong> Commands allocate through libc
- <code>malloc</code>; the <code>SYS_MEM_ALLOC/GROW/FREE</code>
- syscalls are the backend in <span class="file">libc/ucmd_mem.c</span>
- and are not called by application code.</li>
- <li><strong>stdio.</strong> <code>printf</code>,
- <code>snprintf</code>, <code>sprintf</code> and
- <code>vfprintf</code> share an exact decimal float formatter
- (<code>%f/%e/%g</code>, width/precision), and
- <code>fopen("rb")</code> provides read-only whole-file
- <code>FILE</code> objects with <code>fread</code>/<code>fseek</code>/
- <code>ftell</code>/<code>fclose</code>. stdout and stderr are
- console streams; stdin is EOF. There is no kernel fd layer yet: the
- <code>stdio_file.c</code> TODO records the future
- <code>SYS_OPEN/READ/WRITE/LSEEK/CLOSE</code> replacement.</li>
- <li><strong>time.</strong> <code>time</code>, <code>gmtime</code>,
- <code>localtime</code>, <code>mktime</code>, <code>strftime</code>,
- <code>gettimeofday</code>/<code>settimeofday</code> and
- <code>clock_gettime</code> use <code>SYS_RTC_GET</code>/<code>SET</code>.
- <code>time_t</code> is 64-bit, local time is UTC-only, and the RTC's
- 1970-2069 range is enforced.</li>
- <li><strong>math.</strong> The full MuJS set is provided with x87
- double arithmetic: <code>sqrt</code>, <code>pow</code>,
- <code>exp</code>/<code>log</code>, trig, <code>floor</code>/<code>ceil</code>/
- <code>round</code>, <code>fmod</code>, <code>ldexp</code>/
- <code>frexp</code> and the IEEE predicates. It is a compact
- double-rounding implementation, not a full fdlibm.</li>
- <li><strong>Limits.</strong> No threads or locking, no
- <code>free()</code>-to-page unmap, and requests near 32 MB fail
- because headers are charged against the same arena. The file layer
- is read-only and whole-file (4 MB cap); writable files and streaming
- need the kernel fd layer. There is no timezone database and no
- <code>long double</code>/<code>%a</code> support.</li>
- <li><strong>Tests.</strong> <code>make test-libc</code> covers the
- malloc arena, format/dtoa, math, 64-bit division helpers and
- <code>setjmp</code>/<code>longjmp</code> on the host.</li>
- </ul>
- </section>
- <section id="spawn">
- <h2>Spawn path</h2>
- <figure class="figure">
- <svg viewBox="0 0 920 232" role="img" aria-labelledby="spawn-title spawn-desc">
- <title id="spawn-title">Command spawn path</title>
- <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>
- <rect class="svg-box" x="20" y="24" width="160" height="58" rx="9"/>
- <text class="svg-text" x="38" y="49">shell line</text>
- <text class="svg-sub" x="38" y="69">word + remainder</text>
- <rect class="svg-box blue" x="216" y="24" width="160" height="58" rx="9"/>
- <text class="svg-text" x="234" y="49">builtins</text>
- <text class="svg-sub" x="234" y="69">cd · path · help · clear</text>
- <rect class="svg-box accent" x="412" y="24" width="180" height="58" rx="9"/>
- <text class="svg-text" x="430" y="49">PATH lookup</text>
- <text class="svg-sub" x="430" y="69">/ramfs/bin by default</text>
- <rect class="svg-box" x="628" y="24" width="270" height="58" rx="9"/>
- <text class="svg-text" x="646" y="49">kernel registry</text>
- <text class="svg-sub" x="646" y="69">privileged / inline commands</text>
- <path class="svg-line" d="M180 53h24"/>
- <path class="svg-line" d="M196 47l7 6-7 6"/>
- <path class="svg-line" d="M376 53h24"/>
- <path class="svg-line" d="M392 47l7 6-7 6"/>
- <path class="svg-line" d="M592 53h24"/>
- <path class="svg-line" d="M608 47l7 6-7 6"/>
- <rect class="svg-box green" x="216" y="146" width="376" height="58" rx="9"/>
- <text class="svg-text" x="236" y="171">VFS load → process_create_user</text>
- <text class="svg-sub" x="236" y="191">ELF segments · page directory · 8-page stack · arg</text>
- <rect class="svg-box amber" x="628" y="146" width="270" height="58" rx="9"/>
- <text class="svg-text" x="646" y="171">kernel process</text>
- <text class="svg-sub" x="646" y="191">ring 0 · pinned to the BSP</text>
- <path class="svg-line accent" d="M502 82v54"/>
- <path class="svg-line accent" d="M496 128l6 7 6-7"/>
- <path class="svg-line" d="M763 82v54"/>
- <path class="svg-line" d="M757 128l6 7 6-7"/>
- </svg>
- <figcaption>
- <strong>A packed command can shadow a kernel command.</strong>
- The PATH is searched before the kernel registry, so a new
- <code>bin/<name></code> changes behaviour without editing the
- kernel. Builtins are handled inline, before either lookup.
- </figcaption>
- </figure>
- </section>
- <section id="syscalls">
- <h2>Syscall ABI</h2>
- <p>
- The gate is <code>int 0x80</code>. <code>eax</code> carries the
- number, <code>ebx</code>/<code>ecx</code>/<code>edx</code> the first
- three arguments, and the negative <code>SYS_E*</code> codes are
- stable. The wrappers in <span class="file">ucmd_lib.h</span> cover
- zero to three arguments.
- </p>
- <div class="table-wrap">
- <table>
- <thead>
- <tr><th>Group</th><th>Numbers</th><th>Purpose</th></tr>
- </thead>
- <tbody>
- <tr><td>Console & time</td><td>1–4, 56, 69, 104–105</td><td>putstr, ticks, sleep, exit, RTC time/date get/set</td></tr>
- <tr><td>Files</td><td>5–11, 48, 98</td><td>whole-file read/write, list, unlink, mkdir/rmdir, mounts, cwd, stat</td></tr>
- <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>
- <tr><td>Network</td><td>17–47, 106</td><td>NIC config/acquire, raw frames, DHCP/DNS/NTP, TCP client, ARP, cwd</td></tr>
- <tr><td>Window & 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>
- <tr><td>Process & 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>
- <tr><td>TCP server</td><td>93–97, 99–101</td><td>listen, accept, server recv/send/close, peer, speed, MAC set</td></tr>
- <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>
- <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>
- </tbody>
- </table>
- </div>
- <p>
- The file service is whole-file, not stream-oriented. The network
- service has a per-process TCP client table (up to twelve connections)
- and a separate raw NIC lease for packet-level commands. There is no
- <code>fork</code>, <code>exec</code> or shared memory: a command
- either runs as its own process from an ELF or calls a kernel command.
- </p>
- </section>
- <section id="shell">
- <h2>Shell & PATH</h2>
- <p>
- The windowed shell is <span class="file">ucmd_term.c</span>; the
- kernel-side <span class="file">terminal.c</span> holds the privileged
- command registry used through <code>SYS_SPAWN_KCMD</code>. There is
- no kernel terminal fallback; the WM spawns the first terminal once
- storage is ready. Each terminal has a current working directory and
- a PATH (default <code>/ramfs/bin</code>). Pressing Tab completes
- builtin and PATH names; <code>help</code> lists both.
- </p>
- <ul>
- <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>
- <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>
- <li><strong>Arguments.</strong> The raw remainder of the line is passed verbatim; commands parse their own flags.</li>
- <li><strong>Working directory.</strong> The prompt shows <code>[dir] ></code>; <code>cd</code> changes only the current terminal's cwd, and spawned commands inherit it.</li>
- <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>
- </ul>
- </section>
- <section id="registry">
- <h2>Kernel commands</h2>
- <p>
- These commands must run in ring 0 or inline in the shell; they are not
- files in the pack. The split keeps privileged hardware access out of
- ring 3 while most user-facing tools remain replaceable ELFs.
- </p>
- <div class="table-wrap">
- <table>
- <thead>
- <tr><th>Group</th><th>Commands</th></tr>
- </thead>
- <tbody>
- <tr><td>Shell</td><td><code>cd</code> <code>path</code> <code>help</code> <code>clear</code> <code>bootlog</code></td></tr>
- <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>
- <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>
- <tr><td>Network control</td><td><code>netdev</code></td></tr>
- <tr><td>Boot / power</td><td><code>reboot</code> <code>poweroff</code> <code>kexec</code></td></tr>
- </tbody>
- </table>
- </div>
- <p>
- <code>format <device> [size]</code> creates a FAT filesystem.
- <code>install <target> [source|self]</code> installs NebOS.
- With a source it auto-detects a disk whose MBR and LBA-63 boot
- sector carry the NebOS signature (preferring <code>usb0</code>),
- reads P1..P3 into RAM, creates or keeps the <code>NEBOSDATA</code>
- partition at LBA 34816, writes the target from RAM, merges the data
- entry into the MBR, writes the MBR last and verifies the result. A
- source-read failure leaves the target untouched. <code>self</code>
- writes the running gzip pack and its bundled kernel without a USB
- stick; <code>auto</code> picks the only non-USB NebOS disk. The
- data partition survives both forms, while the P1..P3 OS image and
- the app pack are replaced. Both the BIOS and UEFI paths are cloned
- on a full install; a later self-update leaves the ESP alone.
- </p>
- </section>
- <section id="pack">
- <h2>Command pack</h2>
- <p>
- The pack is built from the <code>UCMDS</code> list in the Makefile as
- <code>bin/<name></code>, plus <code>hello</code> and the real
- <code>browser.app</code> and <code>gallery.app</code>. It is mounted
- read-only at <code>/ramfs</code>; the shell's default PATH points at
- <code>/ramfs/bin</code>.
- </p>
- <div class="grid">
- <div class="card">
- <h3>Files & text</h3>
- <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>
- </div>
- <div class="card">
- <h3>System</h3>
- <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>
- </div>
- <div class="card">
- <h3>Network</h3>
- <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>
- </div>
- <div class="card">
- <h3>GUI</h3>
- <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>
- </div>
- </div>
- <p>
- The launchers <code>bin/browser</code> and <code>bin/gallery</code>
- forward their argument and cwd, and prefer a development copy under
- <code>/share</code> (<code>BROWSER</code> or <code>GALLERY</code>)
- before the pack copy and the FAT fallback on <code>root.img</code>.
- This lets <code>make browser-dev</code> and <code>make gallery-dev</code>
- update an app without rebuilding the pack.
- </p>
- </section>
- <section id="apps">
- <h2>GUI applications</h2>
- <ul>
- <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>
- <li><strong>gallery</strong> — live widget and primitive showcase; the real app ships in the pack.</li>
- <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>
- <li><strong>solitaire</strong> — Klondike with drag-and-drop, scoring and a win animation.</li>
- <li><strong>mines</strong> — second ngui canvas app; shares the toolkit and event model.</li>
- <li><strong>view</strong> — fit/1:1/zoom/pan image viewer, animated GIF playback.</li>
- <li><strong>edit</strong> — text editor that draws its own text with the 8x16 font.</li>
- <li><strong>clock</strong> / <strong>colors</strong> — small window canvas demos.</li>
- <li><strong>settime</strong> — Date & 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>
- <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>
- <li><strong>wm</strong> / <strong>term</strong> — the ring-3 window manager and terminal launcher used by the desktop.</li>
- </ul>
- <p>
- The WM chrome, ngui labels and the browser use the fixed-point
- TrueType engine in <span class="file">ufont.c</span> with the Arimo
- and Liberation Mono subsets in the pack. CSS and ngui can select
- regular/bold/italic/mono faces at 8–48 px; missing faces fall back to
- the 8×16 bitmap. UTF-8 text APIs additionally fall back to the
- monochrome Noto Emoji subset for common emoji (format-12 cmap);
- the browser still uses the Latin-1 byte path. Terminal contents and
- the editor stay bitmap;
- ngui text fields use the proportional face for text, caret,
- selection and horizontal scrolling. The browser detaches the font
- arena before <code>heap_reset()</code> and reattaches after the page
- heap is mapped.
- </p>
- </section>
- <section id="browser">
- <h2>Browser</h2>
- <p>
- The real browser is <code>bin/browser.app</code> in the pack. It links
- ngui, the image library, inflate, TLS, uhttp and the vendored MuJS
- engine. It opens at 1100×700 (960×640 and 780×540 fallbacks on
- smaller screens), with a URL bar, history, a status bar, inline
- images and inline/external scripts. Network work runs in up to three
- headless <code>curl __serve</code> workers, each with its own files
- under <code>/share</code>, so the UI keeps drawing and scrolling
- while several TCP/TLS connections are in flight.
- </p>
- <ul>
- <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>
- <li><strong>JavaScript.</strong> Inline and external <code><script src></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>
- <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><a></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>
- <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>
- <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>
- <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>
- <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>
- <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>
- </ul>
- <p>
- The browser's default canvas is dark, matching the ngui theme, but an
- <code>html</code>/<code>body</code> background fills the whole page
- canvas. Pages without one that set dark text can be hard to read;
- pages with their own background and colour rules are unaffected. See <a href="graphics.html#images">Graphics → Image
- library</a> for the decoder limits.
- </p>
- <p>
- <code>testdata/browser/compat/</code> is the browser compatibility
- ladder: numbered, self-contained pages with an A/B pair for each
- behaviour. Run <code>make compat-serve</code> and open
- <code>http://<host>:8000/</code> on the board (or
- <code>http://10.0.2.2:8000/</code> in QEMU's user network). The
- index records the current pass/fail status; pages 010–046 and 030a pass
- (036a needs the POST echo server), while
- the README lists the remaining gaps.
- </p>
- </section>
- <section id="sources">
- <h2>Source map</h2>
- <ul class="filelist">
- <li><code>syscall.c</code>, <code>syscall_stub.S</code>, <code>syscall.h</code></li>
- <li><code>sys_info.c</code> — kernel-state snapshots (memory, sensors, power)</li>
- <li><code>rtc.c</code> — CMOS RTC read/write, format decoding and the 1970–2069 year window</li>
- <li><code>process.c</code> — ELF load and spawn</li>
- <li><code>elf.c</code> — ELF parser</li>
- <li><code>ucmd_term.c</code> — windowed shell, scrollback, PATH</li>
- <li><code>terminal.c</code> — privileged kernel command registry</li>
- <li><code>install.c</code> — privileged live-image clone installer</li>
- <li><code>ucmd_lib.h</code> — user shim</li>
- <li><code>libc/</code> — headers, malloc, string/stdlib, setjmp/errno, stdio/dtoa, math, time and the <code>SYS_MEM_*</code> backend</li>
- <li><code>libc.a</code> — optional static ring-3 libc</li>
- <li><code>ucmd.ld</code> — ring-3 link address</li>
- <li><code>Makefile</code> — <code>UCMDS</code> and pack rules</li>
- <li><code>ucmd_*.c</code> — commands</li>
- <li><code>ufont.c</code>, <code>ufont_ttf.c</code> — fixed-point TrueType text</li>
- <li><code>ngui.c</code> — GUI toolkit; <code>fonts/*.ttf</code> — UI and emoji subsets</li>
- <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>
- <li><code>ucmd_chat.c</code>, <code>chat_login.c</code>, <code>ujson.c</code>, <code>uhttp_cookie.c</code> — chat client</li>
- <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>
- <li><code>ucmd_netmenu.c</code>, <code>wifi_cfg.h</code> — top-bar network menu and its staged WiFi connect record</li>
- </ul>
- </section>
- </main>
- <footer class="site-footer">
- <div class="inner">
- <p><strong>NebOS 0.2.0</strong> · Architecture documentation · <a href="index.html">overview</a></p>
- <p>Maintain alongside <code>AGENTS.md</code> and the source files listed on each page.</p>
- </div>
- </footer>
- </body>
- </html>
|