Userland
Commands are ELFs. The shell is a dispatcher.
Ring-3 programs are freestanding 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 42 PATH commands by default.
Ring-3 model
A user process gets a page directory cloned from the kernel identity
map, a 2 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.
- No libc. Commands include ucmd_lib.h for syscall wrappers and string helpers.
- 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.
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 | putstr, ticks, sleep, exit, RTC time/date |
| 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 | memory, E820, mouse, storage, blkdev, procinfo, cursor, CPU temp, sensors, EC |
| Network | 17–47 | NIC config/acquire, raw frames, DHCP/DNS, TCP client, ARP, cwd |
| Window & WM | 55, 57–72, 80, 83–87 | key poll, WM attach/info/map/present/create_term, window create/present/input/resize |
| Process & memory | 73–79, 81, 88–90 | TTY, spawn, 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 |
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.
- 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 dbg serial |
| Network control | netdev |
| Boot / power | reboot 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 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
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.
- 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.
- wm / term — the ring-3 window manager and terminal launcher used by the desktop.
Browser
The real browser is bin/browser.app in the pack. It links
ngui, the image library, inflate, TLS and uhttp. It owns a 960×640
window, a URL bar, history, a status bar and inline images. Network
work runs in a headless curl __fetch helper that writes
the body and metadata under /share, so the UI keeps
drawing and scrolling.
- HTML/CSS subset. External and inline stylesheets, tag/class/id and descendant/child selectors, colours, backgrounds, font size, weights, margins, padding, borders, alignment, percentage widths, basic floats and
@mediablocks evaluated at a fixed 1000 px viewport. - Not supported. JavaScript, forms, flex/grid, CSS variables, absolute/fixed positioning, standalone image documents, tables with column widths, video/audio.
- Caps. 2 MB page body, 832 KB CSS, 6144 DOM nodes, 2304 rules, 16 images; images are downscaled to at most 1000 px wide and decoded into a 24 MB shared arena.
- Fetching. Each network fetch starts a one-shot helper process and a fresh TCP/TLS connection; images load one per loop within the viewport plus 160 px.
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
syscall.c,syscall_stub.S,syscall.hprocess.c— ELF load and spawnelf.c— ELF parserucmd_term.c— windowed shell, scrollback, PATHterminal.c— privileged kernel command registryucmd_lib.h— user shimucmd.ld— ring-3 link addressMakefile—UCMDSand pack rulesucmd_*.c— commandsbrowser.c,browser_html.c,gallery.c