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 45 PATH commands by default.

int 0x80 one string argument 45 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–103memory, E820, mouse, storage, blkdev, procinfo, cursor, CPU temp, sensors, EC sensors, AC/battery
Network17–47NIC config/acquire, raw frames, DHCP/DNS, TCP client, ARP, cwd
Window & WM55, 57–72, 80, 83–87key poll, WM attach/info/map/present/create_term, window create/present/input/resize
Process & memory73–79, 81, 88–90TTY, spawn, alive, kill, chdir, scheduler info, heap alloc/grow/free
TCP server93–97, 99–101listen, accept, server recv/send/close, peer, speed, MAC set

The file service is whole-file, not stream-oriented. The network service has a single TCP connection and one NIC owner. 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 dbg serial
Network controlnetdev
Boot / powerreboot poweroff kexec

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

GUI

wm term files view mines solitaire gallery browser 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. 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 scripts. Network work runs in a headless curl __fetch helper that writes the body and metadata under /share, so the UI keeps drawing and scrolling.

The browser's default canvas is dark, matching the ngui theme. Pages that set dark text but rely on a white default background can be hard to read; pages with their own full background and colour rules are unaffected. See Graphics → Image library for the decoder limits.

Source map