MPOS

Imported from sgj123456/MPOS (AGENTS.md). Install upstream with npx skills add sgj123456/MPOS. Copyright stays with the author.

AGENTS.md

How to work in this repository. Read this before your first edit. The other docs split the rest: README.md = what MPOS is; docs/ARCHITECTURE.md = how it is put together, the module graph and where the layering is violated; docs/ROADMAP.md = the plan - the phase-by-phase roadmap, the status board, the remaining work and what to do next; docs/notes/ = the evidence behind it (one file per phase plus an index, split from the old single NOTES.md; a §N.M pointer routes through docs/notes/index.md) — the measured status of every phase, the ledger of every gate run and measurement, and the home of any new plan; docs/uapi/ = the userspace-visible surface as one row per promise. This file is only how to work here, and points at those rather than repeating them.

1. Repository map

Root Cargo.toml: default-members = ["."] is load-bearing — without it a plain cargo build would build the musl user programs for the host.

2. Build, run, verify

Prereqs: the six targets and the host tools (qemu-system-{x86_64,aarch64}, OVMF/AAVMF, the image and musl toolchain pieces) are listed in full in xtask/README.md — check them there. rootfs/initramfs fetch Alpine packages over the network.

cargo fmt --check
cargo clippy --target x86_64-unknown-none            # kernel, bare metal
cargo clippy --target x86_64-unknown-linux-gnu       # kernel, host
cargo clippy -p mpos-xtask --target x86_64-unknown-linux-gnu
cargo clippy --target aarch64-unknown-none           # everything under arch/src/arch/aarch64/ is
(cd boot && cargo clippy --target aarch64-unknown-uefi)   # #[cfg]-ed out of every x86 target above

Two build traps. (1) --target is mandatory for host work: .cargo/config.toml pins [build] target = "x86_64-unknown-none", so a bare cargo test builds for bare metal and cannot run. (2) The aarch64 target links in --release only: a debug build fails with relocation R_AARCH64_ABS64 … from the sysroot's liballoc, and no gate notices — anything hand-verifying an aarch64 change must pass --release.

The self-test protocol. Stage 1 = host unit tests. Stage 2 = builds the test kernel (--features selftest, copied out of the shared target dir by utils::build_test_kernel — a production build carries neither the boot's check families nor the harness that runs them, docs/notes/ §15.19), packs both user suites into a throwaway initramfs with a generated /init, and parses the serial log for the kernel's own mpos-kunit: N passed, M failed line plus === RUN/PASS/FAIL t-name / === SUMMARY pass=N fail=N / === END. Both halves are asserted: the sweep must end with a summary and QEMU exit code 33 (isa-debug-exit), and the kernel's line must be there and say zero failed — a suite that silently never ran leaves its cases out of the count. A test that hangs, crashes or never prints === PASS counts as failed — no #[ignore] escape hatch; a test that cannot work is deleted or made to pass.

Both machines read the protocol from the same TEST_INIT runner and the same verdict reader; what differs is where the payload sits — the first machine's programs ride in that throwaway archive (its boot keeps it as its root), the second machine's ride on the root partition of a medium the sweep lays for itself (disk::sweep_medium, its own build/<arch>-sweep.img, so it cannot overwrite the image run installed), because its boot switches root. The selection is one question on both arms now: a program runs when it is in no group or in a group the run asked for, --groups/--all-groups mean the same thing on either machine, and the only group neither may ask for is a machine's own gaps — its list of what it cannot serve yet (§15.36).

tests.toml picks which programs run. All are built; grouped ones are left of the default sweep. It is written in the three sections every config file here uses: [default] holds the groups both machines read — external (needs the host network or a listener), slow (measurement/seconds), diagnostic (not a check at all) — and [x86_64]/[aarch64] hold each machine's own half, added to the baseline's group of the same name rather than replacing it. The one group that is an exclusion rather than a reason is a machine's gaps: what that machine cannot serve yet, invisible to the other's sweep and refused by name on its own. --groups <a,b> replaces the file's default; --all-groups runs every group a machine can see; an undefined group name is an error — a sweep that quietly runs fewer tests than asked is the one failure this must not have. A new test lands with a group decision; silence is the default. Nothing a test runs can leak into the image cargo xtask run boots (test artefacts live under build/).

Reporting the gate — never from a stale run. This file carries no test counts and no sweep composition figures: a snapshot here goes stale within a commit or two (the last such snapshot — per-arm program counts — sat wrong for whole sessions). The measured state lives in docs/notes/ (its latest §12.4a summary line; every phase records what it measured). Re-run the gate and quote the summary line + exit code — or say plainly it did not get there.

3. Code conventions

Every design here is Linux's behaviour — never a toy of it

This governs everything below. MPOS exists so unmodified Linux binaries run, which makes failure asymmetric: a wrong shape sends the caller down a path it cannot recover from; an honest errno sends it down its own fallback. Nearly-right is worse than absent.

1. Measure before designing. A behaviour a real program depends on is observed on real Linux first, and the observation is written down with the number beside the claim. A man page does not say which half of the rule the caller branches on.
2. Answer truthfully, or refuse. ENOSYS (call absent here), EOPNOTSUPP (present, cannot do that), EINVAL (argument refused), EACCES/EPERM (will not grant). The _ => ENOSYS arm in src/syscall/linux/mod.rs should stay crowded. Returning success for something not implemented is the single worst thing this codebase can do.
3. No private dialects. A flag, struct or protocol gets its Linux shape, not a convenient one.
4. Refuse rather than approximate. When the honest alternative to doing it properly is doing it nearly, refuse.
5. A gap gets a name, not a stub. Whatever cannot be built today is a named gap in docs/ROADMAP.md, with its measurement and missing prerequisite in docs/notes/. A TODO in shipped code, a handler that returns 0, and a shape that looks finished while doing less are the same violation.
6. A gap gets a pin, or it is not done. Host test, t-* program, or both. "Works, verified by hand once" is how this repo lost the same bug four times.

Five standing checklist rules (before anything lands)

1. Kernel-space discipline. What Linux runs in userspace is not this kernel's job — it provides the ABI userspace expects and nothing more.
2. High cohesion, low coupling. Before adding a feature, locate the module that owns the concept. A change reaching into another module's internals is in the wrong module. This and #5 below are governing rule 1 and the downward-only boundary as review questions.
3. No toy or temporary designs. Governing rule 3 + 4 as a checklist item; never waived for convenience.
4. Every behaviour ships with a pin that would fail without it. Counterfactual as the criterion: a test that passes with and without the change pins nothing.
5. Respect the designed dependency graph. Modules depend on each other only along the edges the design allows; update docs/ARCHITECTURE.md (§2 + §3) before adding an edge, not after.

Module boundaries

The table, the enforcement story and the two rules that make it usable (violation-is-not-precedent; a needed edge changes the design record in the same commit) are in docs/ARCHITECTURE.md §2/§3 — that file and this one move together. The working copy of the rule: a module may call downward only; cargo xtask depgraph re-measures every crate:: reference and fails on an unrecorded edge; the purest leaves live in crates/ so an upward edge from them is a compile error.

Seven extended rules (what a change carries, what it may not touch)

Each exists because of a failure this repo has actually paid for.

1. A test is a contract, not an obstacle. When the gate goes red, the code changes, not the test. Where a test's expectation is genuinely wrong, the commit body carries the measurement proving the kernel's answer is Linux's.
2. Every new parser gets a fuzz target. Any place the kernel reads user- or wire-supplied bytes joins the targets in fuzz/ in the same commit, or docs/notes/ says why not.
3. A published ABI is append-only. Syscall numbers, struct layouts and ioctl encodings are contracts once shipped. Renumber/repack/reinterpret only with an explicit migration in docs/notes/.
4. Worst-case rule. The global allocator still panics on failure (docs/notes/ §8.0), so until that closes, any new path whose allocation volume a user can steer carries a bound — capped count, checked length, or ENOMEM at the limit.
5. Interrupt context does none of: sleep, allocate, walk an unbounded structure. Bounded work, no lock a preempted task may hold, defer the rest. On one core, spinning on a preempted holder is a deadlock with the machine stopped on it.
6. A performance change ships with before/after numbers. docs/notes/ §10 is only true if entries are measurements.
7. One intent per commit. A refactor and a behaviour change in one diff have no single why. Split: the refactor lands first, green on its own, then the change.

The no_std split is the central convention

Arch-independent logic lives in the library and is host-tested; anything touching port I/O, descriptor tables, virtio rings, firmware or a real clock is gated behind #[cfg(target_os = "none")] (and target_arch = "x86_64" where the hardware is). Pure logic belongs host-side even when its only caller is bare metal. The per-module rule (home: src/lib.rs's header): a module is host-compiled when its logic touches no hardware, no port I/O, no virtio ring and no real clock — and then its dependencies must be host-compiled too, transitively. The transitive half is what gets forgotten. cargo xtask test opens with a mechanical check for the failure the compiler cannot see — a #[cfg(test)] module behind a target_os = "none" parent (xtask/src/gates.rs).

Concurrency

• Uniprocessor: disabling interrupts is mutual exclusion.
• Shared state is critical_section::Mutex<RefCell<T>>. Never spin::Mutex — busy-waiting on a lock held by a task this core preempted is a deadlock (spin::Once only for one-time gdt/idt).
• Never sleep holding a lock. The pattern is lock, poll, try, unlock, park — see src/net/mod.rs and docs/ARCHITECTURE.md §7.
• The idle halt belongs to the scheduler's loop; a task that hlts while staying runnable costs a whole tick on every wake (docs/notes/ §10.2).

Comments, errors, panics

House style is long-form prose doc comments explaining why, not what: //! headers run to paragraphs, and a non-obvious decision names the rejected alternative and the evidence. Match that. Don't add a comment that restates code; don't delete an existing rationale comment while editing around it. Panic ends the machine (panic = "abort" + a handler that exits QEMU). Syscall handlers return Linux errno constants through err and never unwrap user input.

4. Recipes

Add/change a Linux syscall. (1) src/syscall/linux/nr.rs — the number and pub const (the test harness #[path]-includes this file). (2) src/syscall/linux/mod.rs — the dispatch arm. (3) the handler in fs/file.rs (path/file/device calls) or fs/ioctl.rs (the device-ioctl entry point), plus proc.rs (memory/process/time) or posix.rs (identity/capabilities/scheduling/clocks); validation with the handler, pure ABI facts in host-compiled abi.rs. (4) an unimplemented call falls to _ => ENOSYS (§3). (5) a conformance program + its [[bin]] entry (next recipe). (6) update docs/ROADMAP.md (the status board + "Remaining ABI support") and docs/uapi/, and docs/notes/ when a measurement or a lesson is added — a call moving between served / refused / wrong-shape belongs in both.

Add a user test program. std/rustix → user/tests/src/bin/t-<name>.rs (flat, auto-discovered) — the shape a new test belongs in, because it runs on both machines and takes its per-claim printing and exit status from the crate's own Report (user/tests/src/lib.rs) instead of a local copy. Use rustix first; drop to libc only where the crate's rule allows it, and read that rule where it is owned — user/tests/Cargo.toml's header states the measured clauses (unbound call, wrong wrapper syscall, shape cannot express the claim, plus the bitflags-vs-enum distinction and the numbers-from-rustix convention), each with its measurement beside it. The no_std raw-syscall suite this used to point at finished moving across and was deleted (§15.11's last batch), so user/tests is the whole ABI suite now. Print ok:/FAIL: per check and a final PASS/FAILED (Report::finish does both). Keep the t- name (the test /init globs /bin/t-*). Decide its group in tests.toml — under [default] it binds both machines, under a machine's own section it is that machine's alone, and a name in a machine's gaps must be a program that machine actually builds (§5's trap).

Add a kernel unit test. A #[cfg(test)] mod tests at the bottom of the file it tests, with the parent module compiled for the host (§3). Assert on the contract (value, errno, count), not a log line; prefer a test that would fail if the policy differed.

Add a boot self-test. Something that can only be checked on a booted machine goes in a suite beside the module it tests: #[cfg(all(target_os = "none", feature = "selftest"))] pub mod kunit; in that module, a pub const SUITE naming its phase and its cases, and one line in the wiring layer's SUITES (src/board/kunit.rs) — the only place that lists them. Being a child of the module is the point: it reads the module's private state, so no accessor is added to mm/sched/vfs for a test's sake. A case answers Result<(), String> through case_check! rather than asserting — panic = "abort" means an assert! would end the machine and hide every case after it — and it declares the [Phase] it needs (the boot step, not a position), because a suite that runs too early asserts against a machine that is not ready. cargo xtask test is the only thing that builds them (--features selftest) and the only thing that asserts the harness's own mpos-kunit line (docs/notes/ §15.19 for the mechanism, §15.20 for a suite that already moved).

Change the guest image. A file that must exist → the assets/rootfs/<machine>/ (or assets/initramfs/<machine>/) tree (overlays apply after anything the toml writes). A package → rootfs.toml/initramfs.toml (under assets/configs/), under the section of the machine it is for: [default] where both want it, [x86_64]/[aarch64] where only one does — and a key is dotted by what it belongs to (rootfs.mirror, system.hostname, user.name). An account a package's own post-install script would make (dbus's messagebus, busybox's klogd, seatd's seat, weston's weston-launch) → SYSTEM_GROUPS/SYSTEM_USERS in xtask/src/rootfs.rs: a cross-arch install runs apk --no-scripts, so the build writes those lines itself, and the names, ids and order are measured against the two images' own /etc/passwd//etc/group (cargo test -p mpos-xtask pins the shape, seat's id included - the configured account joins that group, so an image that never made it gets a second one at a regular id). Partition / fs-type / image-size / hostname / DNS → rootfs.toml. Anything about the machine (memory, cpus, vsock, audio, window backend, run mode, extra QEMU args) → machine.toml, never rootfs.toml — rootfs.toml's shape keys (mirror, branch, repos, filesystem, disk geometry) decide whether the Alpine tree is laid fresh; its package lists alone install and remove only the difference. A machine key there would still charge the image for a memory size either way, which is why the split stands (xtask/src/config.rs's the_machine_and_the_image_keep_their_own_keys fails if one drifts back). Boot wiring (console='s list) is read via src/boot/console_list.rs; the kernel is told which consoles it has and nothing about how it was launched. It used to read a second word, mpos.selftest, to decide whether to run its own checks — that is a build now, so no boot word decides it (§15.19).

The second machine's userland is its own half (rootfs.toml's [aarch64] section + the assets/rootfs/aarch64/ overlay; docs/notes/ §13.12): a package goes in the section, a file in the overlay, and cargo xtask rootfs --arch aarch64 (or all --arch aarch64, or a run --arch aarch64 that had to rebuild) installs it — the first machine's own command, the same block-layer install, with the machine's --arch for apk. What is not shared is the half of an install that runs the image's userland: on aarch64 Arch::host_runs_guest_userland is false, so apk runs --no-scripts, the chroot steps are skipped, and busybox's applet farm is laid by the build instead (rootfs::lay_applet_farm) — the measurement and why both machines then boot the same standard Alpine chain: docs/notes/ §15.34.

Touch the boot handoff. The Handoff record is one definition now — crates/bootinfo — read by both the loader (mpos-boot depends on it) and the kernel (src/boot/handoff.rs re-exports it). Changing a field changes the ABI an older mpos.elf on a partition is read with, so bump HANDOFF_MAGIC unless the change is append-only. Keep BOOT_STACK_CANARY in crates/bootinfo — the one definition the loader and both kernels read now (§13.23) — and the loader's "allocate everything before exit_boot_services" ordering intact.

5. Known traps

6. Git conventions

Subjects follow the log: type(scope): what changed — types feat/fix/docs/refactor; scopes are subsystems (vfs, sched, net, drm, ext4, syscall, xtask, console, input); multi-subsystem commits list them. The body carries the why: what was observed, measured, rejected — this history is the design record, so a commit that only restates the diff is out of place. git log the file before you change it. The review question every change gets: is that Linux's answer, or a shape that looks like it? Something that cannot be Linux's today says so in its errno and takes a named docs/ROADMAP.md gap (its measurement in docs/notes/) in the same commit (§3). Never commit build/, target/, build-test/ or anything under .workbuddy/, .qoder/, .codely-cli/ (all gitignored). Never push to a remote unless explicitly asked.

7. Where the plans live

• docs/ROADMAP.md — the plan: the phase-by-phase roadmap, the status board at the top, "Suggested next moves", what is open and in which order. What to do next lives here.
• docs/notes/ — the evidence: the ledger of each gate run, performance change and lesson with its measurement, and the reasoning behind every divergence the roadmap names.
• docs/uapi/ — the userspace surface as an inventory (syscalls, ioctl families, layouts, flag vocabularies), each row carrying Linux's answer, this kernel's, the owning module and the pin — the working list of served / honestly refused / wrong shape (only the third is work).
• docs/ARCHITECTURE.md §9 — the debt audit, mirrored in docs/notes/ Phase 11 with an ordered remediation plan.
• The same-commit rule for the board, the uapi row and the notes is §4's syscall recipe step (6) and §6; it binds every change, not only syscalls. The board is only useful if it is true.