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.

int 0x80 one string argument 47 PATH commands 8 TTYs · 8 windows

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.

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.

Spawn path

Command spawn path 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. shell line word + remainder builtins cd · path · help · clear PATH lookup /ramfs/bin by default kernel registry privileged / inline commands VFS load → process_create_user ELF segments · page directory · 8-page stack · arg kernel process ring 0 · pinned to the BSP
A packed command can shadow a kernel command. The PATH is searched before the kernel registry, so a new 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.

GroupNumbersPurpose
Console & time1–4, 56, 69, 104–105putstr, ticks, sleep, exit, RTC time/date get/set
Files5–11, 48, 98whole-file read/write, list, unlink, mkdir/rmdir, mounts, cwd, stat
System info12–16, 49–51, 91–92, 102–103, 107memory, E820, mouse, storage, blkdev, procinfo, cursor, CPU temp, sensors, EC sensors, Chrome EC sensors, AC/battery
Network17–47, 106NIC config/acquire, raw frames, DHCP/DNS/NTP, TCP client, ARP, cwd
Window & WM55, 57–72, 80, 83–87, 109key poll, WM attach/info/map/present/create_term, window create/present/input/resize/scroll
Process & memory73–79, 81, 88–90, 108TTY, spawn, getpid, alive, kill, chdir, scheduler info, heap alloc/grow/free
TCP server93–97, 99–101listen, accept, server recv/send/close, peer, speed, MAC set
WiFi110SYS_WIFI(op, a2, a3): up, status, scan/results, connect/disconnect, EAPOL RX/TX, set key, authorize, set/get PTK for the rekey helper (wifi.c)
NIC menu111–112SYS_NET_DEVLIST (present drivers with kind/active/link) and SYS_NET_SELECT (make a named netdev active)

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.

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.

GroupCommands
Shellcd path help clear bootlog
Process / schedulerps sched renice kill idle cpufreq power
Hardware / debugdisplay gfxbench lsusb lspci peek poke format install dbg serial
Network controlnetdev
Boot / powerreboot poweroff kexec

format <device> [size] creates a FAT filesystem. install <target> [source|self] installs NebOS. With a source it auto-detects a disk whose MBR and LBA-63 boot sector carry the NebOS signature (preferring usb0), reads P1..P3 into RAM, creates or keeps the NEBOSDATA 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. self writes the running gzip pack and its bundled kernel without a USB stick; auto 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.

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 netmenu

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

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. 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 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.

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