Moved verbatim from CLAUDE.md (2026-09-29 compaction); CLAUDE.md keeps the rules and hazards and indexes this file.
The system spans this repository plus one sibling checkout per external
source: the toolchain (miniGCC,
ld,
cvm), the interpreters
(lua,
micropython,
cpython), the UI and
audio libraries (nuklear,
nuked-opl3), the browser
(FreeDom) and the reference-only
raycastlib. Every one of them
carries an addons/<name>.yaml (see Addon doctrine); DOOM, Quake 2 and
doomedit live in-repo or nested and carry one too. The build must be
reproducible from those upstreams alone, so:
make sourcesclones the missing ones andmake sources-updatepulls them. Neither ever modifies a directory that already exists, so a checkout with local work is never clobbered.- Every location is overridable (
MINIGCC_DIR,LD_DIR,CVM_REPO_DIR,CVM_DIR,LUA_DIR,MICROPYTHON_DIR,NUKLEAR_DIR,NUKED_OPL3_DIR,FREEDOM_DIR,RAYCASTLIB_DIR) and so is every origin (*_URL, plusMICROPYTHON_REF/LUA_REFwhere a release is pinned). Nothing in the build assumes an absolute path. - Everything on the ramdisk is regenerated from source:
minigcc.o,ld.oandcvm.ofrom the sibling checkouts, and the demo programs from this repository's own C sources inprogs/, driven through miniGCC andld. The prebuilt objects inprogs/are a convenience for a first boot, never an input the build depends on. - Ramdisk content is owned here. Reaching into another project's test
fixtures for files to ship would break the moment that project reorganizes
them, which is exactly what happened when the image was built from
ld/tests/*.s. ramdisk.binlists theMakefileamong its prerequisites: the file list lives there, so editing it must invalidate the image even when no individual file changed.minifs.bincarries the same rule for the same reason.tools/mkramdisk.pydeflate-compresses every payload (zlib stream, decoded by the kernel's miniz) and stores raw only when compression does not pay, withraw_size/stored_size/data_offset/flagsper entry.ramdisk_setup_frominflates every entry once at boot into the working area, so the on-disk/embedded image drops to ~28% of the raw size (kernel image 957 KB -> 569 KB) while reads, writes and resizes see plain bytes and lose no performance. A payload that fails to inflate aborts setup rather than publishing a torn file.progs/bin/ships the command-path utilities:cp,freedom,lzssandunlzss, compiled from this repository's own sources inprogs/src/through the miniGCC-to-ld chain, with the sources on the ramdisk too so the OS can rebuild the utilities from scratch without leaving the machine. The ramdisk tree is organized by kind:objects/(ET_REL toolchain),bin/(Linux ELFs + command path),cvm/(CVM modules),src/(C sources),asm/(miniGCC assembly),docs/.
MiniOS is one of four projects that together make the system: this repository holds the kernel, the boot path and the ramdisk, and the toolchain it carries lives next door.
| Repository | Role |
|---|---|
| miniOS | this repository: kernel, two-stage boot path, ramdisk, shell, editor |
| miniGCC | C compiler: C to x86-64 AT&T assembly |
| ld | assembler and linker: assembly to a Linux ELF or a CVM module |
| cvm | the CVM / cvm2 bytecode interpreter |
To build the whole system from source, clone the other three next to this one:
make sources # clone the missing repositories from GitHub
make toolchain # build minigcc, ld and cvm2 from those sources
make # rebuild every ramdisk object and os.imgmake sources never touches a directory that already exists, so a checkout
with local work is left alone. make sources-update pulls the latest commit
of each before rebuilding, and make sources-status shows which revision
each one is sitting on.
make sources answers "where do the sources come from"; make update
answers "bring me the newest ones". The updater lives in
tools/update_sources.py and drives every checkout the build consumes, not
just the toolchain trio:
make update # every checkout: toolchain, browser, interpreters, libraries
make update freedom # only the browser
make update freedom ld # only those two
make update-status # the revision each checkout sits on, no network
make update-list # the managed checkouts, their mode and their path
make update-rollback # restore the revisions the last update replacedThe fleet is: minigcc, ld, cvm (the toolchain), freedom (the
browser), micropython, cpython, lua (the interpreters), nuklear,
nuked-opl3 (the UI and audio libraries), raycastlib, quake2 and
pokemon (the reference sources). Each one keeps its mode:
| Mode | Checkouts | What "update" means |
|---|---|---|
| track | minigcc, ld, cvm, freedom, nuklear, nuked-opl3 | fast-forward to the upstream tip |
| pinned | micropython (v1.28.0), cpython (v3.12.11), lua (v5.4.7) | held at the release tag; the tag is re-verified and restored when it drifted |
| reference | raycastlib, quake2, pokemon | tracked like track, but never required: a missing checkout is reported, not fetched |
Freedom is the one checkout that carries a commit of its own: the platform
seam (gui/platform.h, the local commit that lets the same browser link
against Wayland or MiniOS) that freedom-gui depends on. Upstream keeps
rewriting gui/browser_ui.c, so the two meet in a conflict that is
resolved by hand inside the FreeDom repository: the seam wins for the
host-specific parts, upstream's features enter through the seam's API, and
browser_ui.c keeps zero host references.
The safety rules are the contract, not a side effect:
- Local work is never discarded. A dirty worktree is reported as
skippedand left exactly as it is; nothing is ever reset, stashed or force-updated. The Quake 2 upstream carries the MiniOS bug fixes as local edits for exactly that reason. - History is never rewritten. A checkout that carries local commits is
merged with the upstream tip, so a local commit and the upstream work
coexist. A merge that conflicts is aborted, the conflicted files are
named, and the checkout is left clean; the port is then done by hand in
the sibling repository.
UPDATE_STRATEGY=rebasereplays the local commits instead,UPDATE_STRATEGY=ffreports a divergence and touches nothing. - Every update records the pre-update revision in
build/sources-snapshot.json, somake update-rollbackputs the fleet back exactly where it was (git reset --keep, which refuses to discard local changes). - A shallow checkout is deepened by a bounded number of steps until the fast-forward becomes provable; the depth never grows without a budget.
Each checkout reports one line: the state (updated, current, pinned,
repinned, skipped, diverged, conflict, absent, not-a-clone,
would-update, failed), the path, and a short detail. The command exits
nonzero when a checkout failed or conflicted, so a scripted update never
reports success over a broken fleet.
Expected layout: the directory holding this repository can have any name:
src/
├── miniOS/ (this repository)
├── miniGCC/
├── ld/
└── cvm/ with cvm/cvm2 inside
The defaults are MINIGCC_DIR=../miniGCC, LD_DIR=../ld,
CVM_REPO_DIR=../cvm and CVM_DIR=$(CVM_REPO_DIR)/cvm2. Point the build
somewhere else with MINIGCC_DIR=, LD_DIR=, CVM_REPO_DIR= or CVM_DIR=;
change where make sources clones from with MINIGCC_URL=, LD_URL= or
CVM_URL=.
Nothing on the ramdisk is a binary you have to take on trust:
objects/minigcc.o, objects/ld.o and objects/cvm.o are compiled from
the sibling checkouts, and the demo programs (fib, w1, ldhello) are
compiled from this repository's own C sources in progs/src/ through the
full miniGCC-to-ld chain. The objects under progs/objects/ are build
products, not tracked files, so a fresh clone runs make sources first.
The compiler on the ramdisk is self-hosted, in three generations: the
host-built generation 1 compiles the miniGCC source, ld links that into
the generation 2 compiler, and the generation 2 compiler compiles the
source again into the generation 3 assembly that ld links into
bin/minigcc.elf, the compiler that ships on the ramdisk. No GNU as/ld is
involved anywhere after generation 1. make selfhost verifies the
bootstrap fixed point on the host (g3.s == g4.s: the generation 3 binary
reproduces its own output of its own source). Inside the OS the
self-hosted compiler drives the same edit/compile/link/run loop as
objects/minigcc.o.
| File | Role |
|---|---|
headers/arch/x86/boot/bootdefs.h |
every constant shared by the boot path |
arch/x86/boot/stage1.S |
512-byte boot sector: loads stage 2 over LBA |
arch/x86/boot/stage2.S |
loads the kernel above 1 MB, enters long mode |
kernel.c / headers/kernel.h |
kernel: console, heap, ramdisk, loaders, shell |
kernel/shell.c / headers/shell.h |
shell prompt, command resolution, builtins |
kernel/editor.c / headers/editor.h |
line editor (nano-like: status, goto, search, range listing) |
kernel/syscalls.c |
Linux ABI syscall dispatcher, user pointer validation |
kernel/syscalls_proc.c / headers/syscalls_proc.h |
process syscalls: clone, seccomp, nice, yield, getpid/tid, exit, wait4, kill |
kernel/redirect.c |
shell I/O redirection (>, >>) |
kernel/sched.c |
process management, timer ISR, desktop tick |
kernel/vga_fb.c |
VESA framebuffer desktop, windowed terminal, mouse, WM |
net/rtl8139.c / headers/net/rtl8139.h |
rtl8139 NIC driver: port I/O, PCI, TX/RX, TSC clock |
net/net.c / headers/net.h |
protocol stack: ARP/IP/ICMP/UDP/DNS/TCP, sockets |
net/tls.c / net/tls_crypto.c / net/tls_x509.c |
kernel TLS 1.2 client, crypto, X.509 |
vma.c / headers/vma.h |
VMA red-black tree for mmap tracking |
fs/ramdisk.c |
ramdisk filesystem driver |
fs/minifs.c |
MiniFS filesystem driver |
fs/kfile.c |
unified file API (ramdisk + MiniFS) |
fs/vfs.c |
VFS dispatch layer |
fs/zip.c |
ZIP archive read/write (miniz) |
drivers/ide.c |
IDE PIO disk driver |
drivers/pcspk.c |
PC speaker driver (tone, volume) |
drivers/sb16.c |
Sound Blaster 16 DMA driver |
drivers/rtc.c |
CMOS RTC clock driver |
tls_roots_src/ + tools/mkroots.sh |
the 8 embedded CA roots and their generator |
tools/tls_test.py / tls_test.c |
host TLS suite: vectors + full handshakes |
kernel/cvm_host.c |
CVM interpreter + JIT integration in MiniOS |
progs/lua/lua_main.c |
Lua 5.4 entry point (REPL, -e, -l, script modes) |
progs/lua/minios.c |
Lua bindings for MiniOS kernel services |
progs/lisp/lisp.c |
self-contained Lisp interpreter + MiniOS primitives (ring-3 static ELF) |
progs/lisp/minigcc.lisp |
subset C compiler in Lisp (v0.3: multi-function, params, calls, usage/version CLI, ld-ready asm) |
progs/src/test.lisp |
in-OS Lisp suite: language, primitives, toolchain roundtrip |
progs/wl/wl_mini.h |
Wayland-mini wire contract (header-only, ADR-0024) |
progs/wl/wlcomp.c |
ring-3 Wayland-mini compositor (max 8 surfaces) |
tools/test_lisp.py |
host Lisp suite: 49 vectors, zero-warning build |
tools/lisp_scoped.sh |
scoped Lisp gate: rebuild plus 13 targeted mutants |
progs/topogpt3/topogpt3.c |
TopoGPT3 C inference engine (1,999 lines) |
progs/topogpt3/topogpt3.fp16 |
TopoGPT3 float16 model weights (48,930,967 bytes) |
progs/topogpt3/vocab.bin |
GPT-2 BPE vocabulary (50,257 tokens, 421,349 bytes) |
progs/ |
ramdisk contents organized by kind: objects/, bin/, cvm/, src/, asm/, docs/ |
tools/mkramdisk.py |
packs progs/ into the ramdisk image |
tools/test_bdd.sh / tools/test_http_server.py |
behavioural suite and its HTTP fixture |
progs/src/test_all.sh |
one-boot comprehensive non-interactive test (103 PASS markers) |
mcp/minios_mcp.py |
MCP bridge: boots the OS and exposes its console as tools |
mcp/test_minios_mcp.py |
unit + QEMU BDD suite for the bridge |
mcp/mutate_mcp.sh |
mutation testing for the bridge |
skills/minios/SKILL.md |
agent skill: the edit/compile/link/run workflow over the bridge |
tools/mutate.sh |
mutation testing |
The end state is that the kernel itself builds through the hosted chain
(minigcc.o + ld.o on the ramdisk), with cvm in lockstep: any asm
miniGCC emits, ld assembles/links into both ELF and CVM, and cvm2
runs every bytecode ld generates. The three repos move as one; a gap
lands in all three specs together. Feature demand is survey-verified, not
assumed: tools/kernel_feature_survey.py scans this tree for function
pointers, asm constraints, wide calls, unions, long long, bitfields,
privileged mnemonics and section attributes, and every SDD claim about a
gap must reproduce through it first.
- miniGCC landed:
D/Sextended-asm constraints (fixed homes%rdi/%rsi, scratch pool excludes pinned registers, overflow is fail-closedtoo many register asm operands,=&earlyclobber accepted; template%Nstays full-width, narrow outputs go through literal%%dil/%%di/%%edistores). Proven bytests/t_asm_ds.c(+neg_asm_ds.c) intest_all.sh, 42/42 green, 5 scoped mutants dead. Still open, in survey order: function pointers (kernel tablesvfs_ops_t/syscall dispatch; landed:(*name)(params)declarators for locals/globals/params/members/arrays,call *%r10codegen, fail-closed arithmetic/callability, proven bytests/t_fnptr.c(+4neg_fnptr*.c) with 13 scoped mutants dead), >6-arg stack spill (ksyscalltakes 7; landed: any fixed count through registers plus ordered stack spill with static parity padding, proven bytests/t_args7.cplus thetools/test_call_align.pyprobe, pad-inversion mutant dead),unsigned/signed/long longplus usertypedefand struct-member capture (lexer folding with multi-declarator reseeds in statements, typedefs andfor-init; structunsignedcapture withlong-as-8; scalar/chained/fnptr alias records; proven bytests/t_unsigned.c+t_struct_ul.c+t_longlong.c+neg_typedef_arrcont.cwith 12 scoped mutants dead, 2 documented equivalents); unions/bitfields are deferred with survey proof (only ring-3 host-built programs use them). Standing gate found while proving A7: miniGCC models plainintas 8 bytes (sizeof(int) == 8, 64-bit wrap) but the kernel needs LP64 (minifs.hsuperblockunsigned intfields are 4 bytes on disk), so an LP64 follow-up (A8) gates B1; integer</>also stay signed-only (u64 >= 2^63 compares wrong). Reusable probes live intools/by contract:tools/kernel_feature_survey.py(survey-verified feature demand, the single source every SDD gap claim must reproduce through) andtools/test_call_align.py(6/7/8-arg direct plus 7-arg indirect stack alignment reporting). - ld open:
call */jmp *encodings, privileged EA forms (in/out/lidt/lgdt/mov-cr, today documented future work), kernel object/link mode per its own spec. - cvm open: indirect-call opcode +
ld -f cvmlowering + parity matrix. - Method per milestone: SDD spec, TDD failing test, scoped suite +
scoped mutants on touched files only; full
mutate.sh+test_bdd.shrun once at the very end because they take hours.
progs/src/lzss.c is a single source that builds two command-path binaries:
the linker emits the same program as bin/lzss and bin/unlzss, and the
program selects its mode from argv[0] (any invocation path containing
unlzss decodes; -d forces decode explicitly).
- The codec is Okumura LZSS (window
LZSS_N2048, lookaheadLZSS_F17, thresholdLZSS_P1, MSB-first bit stream) so in-OS output interops with a host reference implementation; the window is pre-filled with 0x20 exactly as the reference. - The on-disk format is fail-closed: 4-byte magic
LZS1, then the original size as a little-endian u32, then the bit stream.unlzssrejects a bad magic, a truncated stream and any declared size larger than the expansion bound derived from the input length (LZSS_EXPAND_NUM/LZSS_EXPAND_DEN), so a hostile header can never drive an oversized allocation, and a stream that would write past the declared size aborts before touching the output file. - The codec works whole-file in memory (bounded, one
mallocper side, sized from the input file and the derived expansion bound), compresses only when the result is reported with exact byte counts, and every I/O shortfall is a diagnostic plus a nonzero exit code, never a partial silent write. Past the first input MB the encoder prints onelzss: <bytes>...heartbeat per MB (the match search is O(window) per byte, so a multi-MB file takes a while and must never look wedged); small-file output is a single result line. Proven onDOOM1.WAD(4196020 -> 2349321 bytes,unlzssback byte-identical byhash).
progs/src/lz4.c builds bin/lz4 and bin/unlz4 from a single source, with
the same argv[0] dispatch as lzss (any invocation path containing
unlz4 decodes; -d forces decode). The codec itself lives in the kernel
(lz4_kernel.c, the same one MiniFS uses), so the tools are thin syscall
front-ends over two MiniOS syscalls, 216 lz4_compress and 255
lz4_decompress, which mirror minifs_compress/minifs_decompress byte
for byte. A call passes a user pointer validated to lie inside the user
window; a violating pointer returns -EFAULT.
- The on-disk block is the MiniFS block format, so
lz4output interops with the filesystem's own LZ4 blocks: a 4-byte little-endian original size, then the raw LZ4 stream.lz4_compressrefuses to write (returns 0) unless the compressed stream is strictly shorter than the input, andlz4_decompressrefuses a header whose declared size exceeds the output capacity or a stream that fails to decode to exactly that size. - The front-ends work whole-file in memory (one
mallocper side, the output side sized fromLZ4_COMPRESSBOUNDor the declared size), report exact byte counts, and every I/O shortfall or implausible declared size is a diagnostic plus a nonzero exit code, never a partial silent write. - The ld stub set grows the
lz4_compress/lz4_decompressentries (216, 217) beside the other MiniOS syscalls, so the toolchain and the ramdisk binary rebuild together. - The kernel
lz4_kernel.cdecompressor handles the literal-only tail of a stream correctly (a valid LZ4 block may end with a final literal sequence and no trailing match), so its own compressor round-trips and its output interops with a host reference decoder.
The shell's unzip and zip builtins read and write ZIP archives through
the miniz zip library, compiled into the kernel as a pristine upstream
amalgamation (3.0.2) in third_party/miniz/ with the allocator redirected to
the kernel heap and stdio/time stripped (MINIZ_NO_STDIO, MINIZ_NO_TIME).
miniz_impl.c applies every knob through macros, the same pattern as the stb
wrapper; the amalgamated header forward-declares the writer's internal state,
so the heap writer's output buffer is exposed through two accessors
(mz_zip_writer_mem_ptr/mz_zip_writer_mem_size) defined where the full
struct is visible.
- Usage:
zip <out.zip> <file...>stores each file (under its sanitized relative name) with the default compression level;unzip <archive.zip> [dir]extracts intodir(default the cwd), creating missing directories, andunzip -l <archive.zip>lists the entries. Both builtins work whole-file in memory over the unified file API (ramdisk first, MiniFS fallback), matching the compression tools contract: the archive is fully validated before any entry is published, output is written only after the whole archive was read, and every failure path reports a diagnostic and releases. The ld stub set is untouched: the builtins are shell features, not toolchain programs. - Entry names are hostile data. Each is normalized to forward slashes,
stripped of leading
/and./repetitions, and rejected when a component is./..or empty (zip_sanitize_name), so a crafted archive can never write outside the directory the user named — an absolute name degrades to a relative one, a traversal name is skipped. The BDD fixtureetc/hostile.zip(generated bytools/gen_zip_fixtures.py, one entry../escape.txtbeside a plain file, a directory marker and an absolute name) provesescape.txtis never created. etc/host.zipis a second generated fixture: a host-produced archive with a nested directory, proving the extractor interops with a reference ZIP writer and not just its own output. Both fixtures are regenerated from source at build time (fixed timestamps, reproducible) like the desktop icons.- Fail-closed surface: a non-zip input is
unzip: <f>: not a zip archive, a missing file isunzip: <f>: cannot read, an entry whose declared size does not match what the extractor produced aborts that entry, and a destination that is an existing file is refused. The mutation suite kills a traversal bypass (the hostile fixture), a bad-magic accept and a skipped finalize.
bin/json is a self-contained JSON validator, pretty-printer and query tool
built from progs/src/json.c through the miniGCC-to-ld chain; like DOOM and
MicroPython it ships on MiniFS (bare-name command at the MiniFS root), not on
the size-budgeted ramdisk. It is written
in the miniGCC subset, which has no structs, so the parsed value is a flat
node table of parallel arrays (js_type/js_num/js_str/js_key/
js_first/js_count/js_next); object members keep their key in js_key
and their value in the node itself.
- Usage:
json <file>validates and pretty-prints;json <file> <path>prints the value at a dotted path (.a.b,.a.3, bare.a). A missing path isjson: <path>: not foundwith exit 1, never a crash. - The parser is fail-closed: truncated input, a trailing non-whitespace
token, an unbalanced
}/]and an unknown escape all reportjson: <file>: invalid JSONwith exit 1. String escapes (\n \t \r \b \f \" \\ \/, and\umapped to?) decode into a bounded string pool, and the pretty-printer re-escapes them so its output is itself valid JSON. - The node table, string pool and query segment are all size-bounded by named
constants (
JS_MAX_NODES,JS_POOL); an input that would exceed a bound is a diagnostic plus exit 1, never a silent overflow. - cJSON (single-file, struct-based) was tried as a portable engine and does
not compile under miniGCC (structs,
->,double,CJSON_PUBLIC), which is why this hand-rolled flat-table parser exists.
progs/src/aes.c builds bin/aes and bin/un aes from a single source with
the same argv[0] dispatch as the other command pairs (a path containing
unaes decrypts; -d forces decrypt). Like DOOM, MicroPython and json it
ships on MiniFS (bare-name commands at the MiniFS root) instead of the
size-budgeted ramdisk.
- The cipher is AES-256 (NIST FIPS-197) written in the miniGCC subset: no structs, flat int arrays masked to bytes at every step, and an S-box generated procedurally from the GF(2^8) multiplicative inverse plus the FIPS-197 affine transform, so the file carries no magic tables. Round expansion follows FIPS-197 for Nk=8/Nr=14, including the extra SubWord pass every Nk/2 words.
- The mode is CTR (NIST SP 800-38A): no padding, encrypt and decrypt share
one code path, and the big-endian counter increments over the full block.
Usage:
aes [-d] <key-hex64> <nonce-hex32> <src> <dst>; a nonce must never repeat under the same key. CTR gives confidentiality only, not authentication - a flipped ciphertext byte flips the matching plaintext byte, so integrity needs a MAC layered above this tool. - The container is fail-closed: 4-byte magic
AES1, then the original size as a little-endian u32, then the raw keystream XOR. Decoding refuses a bad magic, a truncated header, and any body whose length does not equal the declared size exactly; key and nonce hex are length- and alphabet- validated before anything runs. - Host verification lives in
tests/host_aes.sh: the NIST F.5.5 CTR-AES256 known answer, byte-for-byte ciphertext equality against OpenSSL across a multi-block stream, reverse-direction interop (OpenSSL ciphertext decoded byunaes), dispatch modes, empty input, and the fail-closed set. Five one-line mutants of the codec (ShiftRows drop, polynomial, affine constant, AES-256 extra SubWord, size-mismatch check) all die against it.
progs/src/mtop.c builds bin/mtop.elf plus the bare-name copy
bin/mtop (the topogpt3 idiom, so plain mtop resolves through the
command path) through the miniGCC-to-ld chain from the same
conservative subset as json/cp (int/long/char only, no structs,
output through write so layout never depends on puts newline
behavior, raw syscall inline asm only with 3 or fewer arguments,
which is all miniGCC supports: register pinning such as
register long r10 __asm__("r10") is rejected, so every MINFO call
carries at most a selector plus two out-words). Usage
mtop [frames] [interval_ms] (0 runs until quit, -1 draws one
snapshot, interval clamped to 100..5000 ms); quit keys are q/Q/
ESC plus Ctrl+C/Ctrl+D through a nonblocking SYS_GETC_RAW (236)
poll, so while it runs the monitor owns the keyboard focus like the
fullscreen games do. Panels speak plain language (RAM ocupada X de Y,
CPU en uso Z%, no syscall jargon); etc/alias carries the matching
mtop=bin/mtop entry.
- Figures come from the MINFO syscall (251,
MINIOS_SYS_MINFO): 0 = heap used/free KB, 1 = ramdisk used/cap KB, 2 = MiniFS free/total blocks, 3 = cpu total/idle 100 Hz ticks, 4 = cpu count/uptime seconds, 5 = clear the caller's terminal view, 6 = sleep milliseconds. CPU busy percent is (dt-didle)*100/dt between two reads of selector 3; idle ticks come from a per-CPU counter bumped in the timer ISR when it finds no process on that CPU. Every value is range-checked before display, so a foreign kernel answering 251 with other semantics degrades to plain unavailable instead of showing garbage. - Selector 6 exists because a polling refresh loop never lets the
CPU idle and would pin its own meter at 100%: the caller parks on
a wait queue (
sleep_on, futex discipline) woken by a 100 Hz audio-tick listener, in chunks of at most 50 ms so key checks stay responsive. Registration happens at boot next to the other tick listeners; without it sel 6 fails closed with -EIO. Number 251 shadows Linuxioprio_set: documented DEVIATION (no port traps ioprio, trapped calls fail closed on selector validation), listed intools/check_abi_numbers.py, ABI bumped to v11 with the manifest regenerated at build time. - Frames after the first clear the screen through selector 5, which
calls the new
term_clear(framebuffer logical-line ring plus in-progress line reset, viewport snapped live, repaint; parked twin snapshots are unaffected until they refocus): a true redraw where the terminal is live, ANSI clear on the serial console as fallback. Theclearbuiltin was a silent no-op on the desktop (it only wiped the legacy text buffer), so it takes the same path plus the ANSI sequence, which the framebuffer terminal swallows without garbage. - DISK throughput is measured live by reading a ramdisk probe opened
once and rewound every frame: the ld
fopenstub keeps a 5-slot table thatfclosenever releases (sibling-ld bug, tracked here), so open-per-frame dies on the 5th frame. NET is a TCP socket create/close plus alocalhostDNS round trip, probed on frame 1 and every 10th frame and cached between (an unanswered DNS costs seconds). - Each sampled panel keeps a 32-deep history drawn as an auto-scaled
sparkline (
.:-=+*#%@) beside a[####--]bar scaled to the observed maximum; UPTIME and CMOS clock (SYS_RTC212) head every frame. - Degradation is total: on a host without MiniOS syscalls (or before
the network is up) every failed probe prints
n/awith its cause and the program still renders and exits 0, so the same binary smoke-tests on Linux (mtop -1) and live under QEMU (run bin/mtop.elf 3 200, BDD-pinned output shape).