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 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.
- 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 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. - Limits. No threads or locking, no
free()-to-page unmap, and requests near 32 MB fail because headers are charged against the same arena. Consoleprintf/FILEI/O is not part of this layer; file access still uses the whole-file syscalls. - Test.
make test-libcruns a host stress test over a simulated 32 MB arena, checking alignment, coalescing,realloc/calloc, growth andheap_reset.
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–103 | memory, E820, mouse, storage, blkdev, procinfo, cursor, CPU temp, sensors, EC sensors, AC/battery |
| 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 powerinfo 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.
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 and uhttp. It opens at
1100×700 (960×640 and 780×540 fallbacks on smaller screens), with 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, real
font-size(8–48 px), bold/italic faces,font-family: monospace, margins, padding, borders, alignment, percentage widths, basic floats and@mediablocks evaluated at the browser canvas width when the page is parsed. Text is Latin-1; there is no shaping, bidi or@font-faceyet. - Not supported. JavaScript, forms, pseudo-classes, border-radius clipping of descendants, gradients/box-shadow/transitions and CSS
color-mix. Flex rows, card grids, basic tables, 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. 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.hsys_info.c— kernel-state snapshots (memory, sensors, power)process.c— ELF load and spawnelf.c— ELF parserucmd_term.c— windowed shell, scrollback, PATHterminal.c— privileged kernel command registryucmd_lib.h— user shimlibc/— headers, malloc, string/stdlib support 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,gallery.c