Userland
Commands are ELFs. The shell is a dispatcher.
Ring-3 programs are static ELFs linked at 0x40000000.
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.
Ring-3 model
A user process gets a page directory cloned from the kernel identity
map, a 4 MB image/stack window at 0x40000000, an optional
4 MB canvas at 0x50000000 and a growable heap at
0x60000000. The kernel remains mapped because paging is
identity-mapped; this is isolation in privilege level only, not a
separate address space.
- Optional libc. Commands include ucmd_lib.h for syscall wrappers; commands that need allocation or standard string/stdlib functions link the in-tree libc.a.
- One argument. The shell passes the raw remainder of the line as a C string at the top of the user stack;
_start(const char *arg)needs no crt0. - Inherited context. Each process inherits the spawning terminal's cwd and TTY id; the file syscalls resolve relative paths against the PCB cwd.
- Page-fault policy. A ring-3 fault kills the process and prints a short message; it does not halt the kernel.
Not a sandbox. 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.
Ring-3 libc
libc.a is optional: the Makefile links it
only into commands that reference it, and the archive plus
--gc-sections keeps unused members and functions out of
the legacy command pack. The headers live in
libc/include/ and cover
stddef, stdint, stdarg,
stdlib, string, ctype,
assert, setjmp, errno,
stdio, math, time,
sys/time, sys/types, float,
limits, inttypes, alloca
and the OS-specific ucmd_heap.h.
- malloc. 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
SYS_MEM_*arena cap;calloczeroes andreallocgrows in place when the next block is free. - heap_reset. Discards every allocation and unmaps the whole arena. Page-scoped programs such as the browser use it on navigation instead of tracking individual frees.
- Ownership. Commands allocate through libc
malloc; theSYS_MEM_ALLOC/GROW/FREEsyscalls are the backend in libc/ucmd_mem.c and are not called by application code. - stdio.
printf,snprintf,sprintfandvfprintfshare an exact decimal float formatter (%f/%e/%g, width/precision), andfopen("rb")provides read-only whole-fileFILEobjects withfread/fseek/ftell/fclose. stdout and stderr are console streams; stdin is EOF. There is no kernel fd layer yet: thestdio_file.cTODO records the futureSYS_OPEN/READ/WRITE/LSEEK/CLOSEreplacement. - time.
time,gmtime,localtime,mktime,strftime,gettimeofday/settimeofdayandclock_gettimeuseSYS_RTC_GET/SET.time_tis 64-bit, local time is UTC-only, and the RTC's 1970-2069 range is enforced. - math. The full MuJS set is provided with x87
double arithmetic:
sqrt,pow,exp/log, trig,floor/ceil/round,fmod,ldexp/frexpand the IEEE predicates. It is a compact double-rounding implementation, not a full fdlibm. - Limits. No threads or locking, no
free()-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 nolong double/%asupport. - Tests.
make test-libccovers the malloc arena, format/dtoa, math, 64-bit division helpers andsetjmp/longjmpon the host.
Spawn path
bin/<name> changes behaviour without editing the
kernel. Builtins are handled inline, before either lookup.
Syscall ABI
The gate is int 0x80. eax carries the
number, ebx/ecx/edx the first
three arguments, and the negative SYS_E* codes are
stable. The wrappers in ucmd_lib.h cover
zero to three arguments.
| Group | Numbers | Purpose |
|---|---|---|
| Console & time | 1–4, 56, 69, 104–105 | putstr, ticks, sleep, exit, RTC time/date get/set |
| Files | 5–11, 48, 98 | whole-file read/write, list, unlink, mkdir/rmdir, mounts, cwd, stat |
| System info | 12–16, 49–51, 91–92, 102–103, 107 | memory, E820, mouse, storage, blkdev, procinfo, cursor, CPU temp, sensors, EC sensors, Chrome EC sensors, AC/battery |
| Network | 17–47, 106 | NIC config/acquire, raw frames, DHCP/DNS/NTP, TCP client, ARP, cwd |
| Window & WM | 55, 57–72, 80, 83–87, 109 | key poll, WM attach/info/map/present/create_term, window create/present/input/resize/scroll |
| Process & memory | 73–79, 81, 88–90, 108 | TTY, spawn, getpid, alive, kill, chdir, scheduler info, heap alloc/grow/free |
| TCP server | 93–97, 99–101 | listen, accept, server recv/send/close, peer, speed, MAC set |
| WiFi | 110 | SYS_WIFI(op, a2, a3): up, status, scan/results, connect/disconnect, EAPOL RX/TX, set key, authorize (wifi.c) |
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
fork, exec or shared memory: a command
either runs as its own process from an ELF or calls a kernel command.
Shell & PATH
The windowed shell is ucmd_term.c; the
kernel-side terminal.c holds the privileged
command registry used through SYS_SPAWN_KCMD. 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 /ramfs/bin). Pressing Tab completes
builtin and PATH names; help lists both.
- Dispatch order. Builtins → PATH file → kernel command. A PATH hit loads the ELF through the VFS and spawns it as ring 3.
- Builtins.
cd,path,help,clear; the ring-3 shell also handlespsandkillinline.bootlogis a kernel command. - Arguments. The raw remainder of the line is passed verbatim; commands parse their own flags.
- Working directory. The prompt shows
[dir] >;cdchanges only the current terminal's cwd, and spawned commands inherit it. - Windows. A window receives keys through its window key queue (
SYS_WIN_KEY_WAIT) or the genericSYS_KEY_POLL; closing the window kills its owner process.
Kernel commands
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.
| Group | Commands |
|---|---|
| Shell | cd path help clear bootlog |
| Process / scheduler | ps sched renice kill idle cpufreq power |
| Hardware / debug | display gfxbench lsusb lspci peek poke format install dbg serial |
| Network control | netdev |
| Boot / power | reboot poweroff kexec |
format <device> [size] creates a FAT filesystem.
install <target> [source] clones the live NebOS
image to a target disk: it auto-detects a source whose MBR and LBA-63
boot sector carry the NebOS signature (preferring usb0),
reads the source image into RAM, then writes the target from RAM,
writes the MBR last and verifies the result. A source-read failure
leaves the target untouched. It installs the flashed image, so both
the BIOS and UEFI boot paths are cloned as-is.
Command pack
The pack is built from the UCMDS list in the Makefile as
bin/<name>, plus hello and the real
browser.app and gallery.app. It is mounted
read-only at /ramfs; the shell's default PATH points at
/ramfs/bin.
Files & text
ls cat save rm mkdir rmdir edit files view
System
cpuinfo meminfo storage top mouseinfo touchpad sensors powerinfo date spin clock colors
Network
netinfo netip netdns host dhcp ping pong netsend netrecv netlog netconsole netregs netloop netreset net100 netmac curl websrv wifi
GUI
wm term files view mines solitaire gallery browser chat clock colors settime
The launchers bin/browser and bin/gallery
forward their argument and cwd, and prefer a development copy under
/share (BROWSER or GALLERY)
before the pack copy and the FAT fallback on root.img.
This lets make browser-dev and make gallery-dev
update an app without rebuilding the pack.
GUI applications
- files — browser for the VFS; opens text in
edit, images inview, HTML inbrowser. First user of ngui. - gallery — live widget and primitive showcase; the real app ships in the pack.
- chat — native Cloudron Chat client (top-bar Chat button, or
chat [config-path]): 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/share/chat.cfgby 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 Network → Chat client. - solitaire — Klondike with drag-and-drop, scoring and a win animation.
- mines — second ngui canvas app; shares the toolkit and event model.
- view — fit/1:1/zoom/pan image viewer, animated GIF playback.
- edit — text editor that draws its own text with the 8x16 font.
- clock / colors — small window canvas demos.
- settime — Date & Time editor opened by clicking the top-bar clock. It reads and writes the CMOS RTC through
SYS_RTC_GET/SYS_RTC_SET; the Sync NTP button asks the kernel's SNTP client (SYS_NTP_SYNC, 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. - wm / term — the ring-3 window manager and terminal launcher used by the desktop.
The WM chrome, ngui labels and the browser use the fixed-point
TrueType engine in ufont.c 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. 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 heap_reset() and reattaches after the page
heap is mapped.
Browser
The real browser is bin/browser.app 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 curl __serve workers, each with its own files
under /share, so the UI keeps drawing and scrolling
while several TCP/TLS connections are in flight.
- HTML/CSS subset. External and inline stylesheets, tag/class/id and descendant/child selectors, colours (including legacy
bgcolorattributes), backgrounds (solid andbackground-imagewith repeat/position/size and thebackgroundshorthand URL), realfont-size(8–48 px), thefontshorthand, bold/italic faces,font-family: monospaceand one regular@font-faceface per family (local or HTTP TTF), margins/padding (percentage sizes use the containing width;emuses the element font), per-side borders, alignment, explicit/percentage block widths withmin-width/max-width/min-height/max-height,box-sizing: border-box,margin: 0 auto, nestedem/remsizes, basic floats,position: relative/absolute/fixed/sticky(top/bottom, containing-block clamp),right/bottom,z-index(including relative boxes),overflow: hiddenclipping,transform: translate/scale/rotatewithtransform-origin(paint-time box and image transforms), flex rows with grow/wrap/justify (includingspace-evenly)/align, two-column grids, table rowspan/colspan and percentage columns,calc(percent ± px)in widths, margins/padding, heights and min/max,white-space: nowrapand@mediablocks 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. - JavaScript. Inline and external
<script src>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/share/bjs-*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 ascript ran too longerror instead of freezing the browser. - DOM. Nodes are interned MuJS userdata wrappers, so
===and library expando caches behave. Elements supportgetAttribute/setAttribute/hasAttribute,appendChild/insertBefore/removeChild/replaceChild/cloneNode/remove,querySelector(All),getElementsByTagName,getElementsByClassName,classList,dataset, inlinestyle(cssText, property get/set,getPropertyValue/setProperty/removeProperty),innerHTML(fragment parser),textContent/nodeValue, traversal,matchesandgetBoundingClientRect(real block/table/absolute/image boxes; inline text boxes are still approximate). Form controls expose livevalue/checked/selectedIndexproperties backed by the browser's control state; forms exposeelements,submit()andreset(), and elements dispatch realaddEventListener/dispatchEventevents with capture, bubbling andpreventDefault().<a>elements exposehref/protocol/host/hostname/port/pathname/search/hash/originresolved against the page URL.documenthascreateElement,createTextNode,createComment,createDocumentFragment,createAttribute,documentElement/body/headandreadyState;navigator,history,matchMedia,getComputedStyle,setTimeout/setInterval/clearTimeoutandrequestAnimationFrameexist, 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. - Not supported. Inline event attributes (
onclick=),MouseEvent/CustomEventandonce/passivelistener options,type="module",defer/async,MutationObserver/IntersectionObserver,XMLHttpRequest/fetch,DOMParser, canvas/2D contexts and pseudo-class/element selectors. Basic controls render, focus, edit, toggle, select, submit GET queries and POSTapplication/x-www-form-urlencodedbodies (see the compatibility ladder);getComputedStylecovers the engine's properties, andouterHTMLonly returns the string last assigned toinnerHTML. - CSS gaps. Multiple background layers and
background-attachment(a non-uniformbackground-sizeuses 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 andcolor-mix. Flex rows, card grids, tables with rowspan/colspan, inline SVG and CSS variables are supported. - Caps. 2 MB page body, 832 KB CSS, 6144 DOM nodes, 4608 rules, 16 images. Each image gets an
img_estimate()-sized decode arena that is freed after the scaled bitmap is made; navigation callsheap_reset()and unmaps the page heap. - Fetching. Up to three worker processes prefetch images in parallel within the viewport plus 160 px; each worker keeps its own TCP/TLS connection and its own request/body/meta files (keyed by browser pid and worker slot, so multiple windows do not collide). Completed images are decoded as jobs finish. Page, CSS and script fetches stay ordered.
- URL entry. A dotted name without a scheme that is not a known local file extension is treated as a hostname, so
cloudron.iodoes not hit the local-file stat. A typed hostname is tried ashttps://first, skipping the commonhttp://host→https://hosthop; if the https connection is refused, reset, times out or fails the TLS handshake, the browser retries once overhttp://and replaces the history entry. Origin-level redirects (such ashttps://host→https://www.host) are cached per process and in/share/borigins; the first visit still follows them, later visits go straight to the canonical origin. Remote stylesheets are cached under/share/bcss-*for the current boot, so a reload or a fresh browser launch skips the CSS downloads.
The browser's default canvas is dark, matching the ngui theme, but an
html/body 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 Graphics → Image
library for the decoder limits.
testdata/browser/compat/ is the browser compatibility
ladder: numbered, self-contained pages with an A/B pair for each
behaviour. Run make compat-serve and open
http://<host>:8000/ on the board (or
http://10.0.2.2:8000/ 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.
Source map
syscall.c,syscall_stub.S,syscall.hsys_info.c— kernel-state snapshots (memory, sensors, power)rtc.c— CMOS RTC read/write, format decoding and the 1970–2069 year windowprocess.c— ELF load and spawnelf.c— ELF parserucmd_term.c— windowed shell, scrollback, PATHterminal.c— privileged kernel command registryinstall.c— privileged live-image clone installerucmd_lib.h— user shimlibc/— headers, malloc, string/stdlib, setjmp/errno, stdio/dtoa, math, time and theSYS_MEM_*backendlibc.a— optional static ring-3 libcucmd.ld— ring-3 link addressMakefile—UCMDSand pack rulesucmd_*.c— commandsufont.c,ufont_ttf.c— fixed-point TrueType textngui.c— GUI toolkit;fonts/*.ttf— UI subsetsbrowser.c,browser_html.c,js_browser.c/h,third_party/mujs/,gallery.cucmd_chat.c,chat_login.c,ujson.c,uhttp_cookie.c— chat clientucmd_wifi.c,wpa.c,wpa_crypto.c—wificommand and the WPA2-PSK supplicant