From fc4c563ca14ddec3de3aeef5a861f9707eaae389 Mon Sep 17 00:00:00 2001 From: salmonik Date: Fri, 21 Aug 2026 17:18:09 +0200 Subject: docs: ADR 0006 (executable binaries) + implementation plan + glossary terms MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ADR 0006: PE32+ loader in rsnix, versioned exports-table ABI constructed per invocation, task-per-binary, single dd-able system image with /bin/cli and /bin/gui, shell-owned grammar with injected line streams, per-terminal input discipline as prerequisite phase, frozen built-in core, 0.6.0 at first exec. Plan: five phases (image → input discipline → loader/exec → streams + migration → GUI binaries), each with a QEMU verification gate. Glossary: Binary, Loader, Exports table, System image; kind = launch surface. --- CONTEXT.md | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) (limited to 'CONTEXT.md') diff --git a/CONTEXT.md b/CONTEXT.md index c27f059..01f5c69 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -116,6 +116,41 @@ message queue. A GUI program is an app; there is no separate "process" concept — the app is its task plus its window. The home terminal is app 0 (window 0). +## Binary + +A PE32+ file holding executable code that the kernel can load and run +without being recompiled into the kernel image. A binary runs against +the kernel's exported interface, never by linking kernel state directly. +Binaries come in two kinds, separated by **launch surface** rather than +implementation: **CLI binaries** live in /bin/cli and run inside a +terminal session (invoked by a shell, inheriting its input/output); +**GUI binaries** live in /bin/gui and are launchable with no terminal at +all — they own their windows — which makes enumerating launchable apps +as simple as listing /bin/gui. Every binary runs as its own task — a CLI binary's task is +waited on by the calling terminal, a GUI binary's task owns its window. + +## System image + +The single dd-able FAT filesystem image the build produces: bootloader, +kernel, /bin, /etc and seed content on one volume. Imaging it onto a disk +yields a complete installed system. Binaries live on the system image +under /bin/cli and /bin/gui; the shell finds them by scanning mounted +volumes — no volume is privileged. + +## Loader + +The kernel facility that takes a binary from disk, places it in memory, +and starts it. Loading changes no address-space setup — binaries run in +the one shared identity-mapped space. + +## Exports table + +The interface between a binary and the kernel: a versioned table of +functions the kernel hands to a binary at entry (output, filesystem, +memory, …). The caller constructs it per invocation, so the same binary's +output can be aimed at a terminal or into the shell's filter pipeline. +All kernel state stays behind the table — a binary never owns a copy of it. + ## Terminal A program that presents a command line in a window: a text terminal -- cgit v1.2.3