# vanir-os

> Minimal x86-64 kernel in stable Rust, booted by Limine. A fixed set of ring-3 tasks (declared in a TOML app manifest at build time) talk by Hubris-style synchronous send/recv/reply IPC. Drivers (virtio console, vsock, block, net), a supervisor, telemetry, TPM attestation, encrypted storage and a TCP/IP stack (smoltcp) with services behind it are ordinary tasks. Full manual: index.html (one page; section anchors below).

## Rules for agents

- Every commit must pass `make test ACCEL=tcg` and `make test ACCEL=kvm` (123 cases, a build check and a host check each). Run one case with `ONLY='^name$' make test`.
- Stable Rust only, `no_std`, target `x86_64-unknown-none`. Keep the soft-backend `--cfg` flags in `.cargo/config.toml` (SIMD crypto backends crash rustc with SIGILL).
- Never commit `keys/` (image-signing key, storage master key) or `build/`.
- The kernel never blocks mid-syscall; user pointers are always range-checked and copied with fault recovery; servers identify clients with `task_name(sender)`, never from message contents.
- Test cases in `tests/run.sh` run in order and share state (disk image, TPM state, attestation references). Tests match serial-log strings, so changing a println can break a test.
- Changing the kernel, a manifest or a task image changes PCR 12; the `attest-record` / `attest-storage-record` cases re-record references.
- Don't edit sources while a test suite is running: each case builds from the working tree.
- Network cases bind host ports (8080, 8081, 18090-18093); to run them next to another suite, set NET_PORT, NET_MGMT_PORT, NET_DGRAM_PORT, NET_MGMT_DGRAM_PORT in the environment.
- Network servers never go idle: tests end with the supervisor's `halt-on-exit` feature and a task that exits (e.g. `http/exit-on-request`, then GET /exit).

## Commands

- `make run APP=tests/apps/<name>.toml USER_FEATURES="pkg/feature ..." KERNEL_FEATURES=...`
- Make variables: ACCEL=tcg|kvm, BOOT=bios|uefi-secure, TPM=1, TRANSPORT=console|vsock, DISK=1, DISK_RESET=1, DISK_CORRUPT=volume:block, SIGN_VERSION, TAMPER, UNSIGNED, SWAP_SIGS, SB_TAMPER_KERNEL, SB_EDIT_CONFIG, SB_UNSIGNED_LOADER, NET=user|dgram, NET_MGMT=user|dgram, NET_PORT, NET_MGMT_PORT; test-only PEER=<net-peer.py scenario>, INTERVAL=<ms>, SLOW=1
- Exit status (QEMU isa-debug-exit): 1 clean, 3 a task exited non-zero, 5 a task was killed, 7 kernel panic or supervisor died, 9 deadlock, 124 timeout
- Test row: `"name | app | user features | kernel features | make variables | status | text"`; text is a fixed string, `re:` (grep -Pz) or `cmd:` (shell, output on stdin)
- `make run-debug` writes interrupts and CPU resets to qemu.log

## Guide

- [Introduction](index.html#introduction): what vanir-os is
- [Quick start](index.html#quick-start)
- [The layers, from scratch](index.html#layers): privilege, virtual memory, traps, tasks, devices, trust, for newcomers

## Reference

- [Boot](index.html#boot): kmain init order
- [Memory and address spaces](index.html#memory): task address-space layout, PTE software bits
- [Tasks and scheduling](index.html#tasks): states, preemption, budgets, outcomes
- [App manifests](index.html#manifests): keys name, program, budget, supervisor, sends, devices, dma_pages, events, min_version, tpm, listen, service, routes, loads, connects; top-level runtime_log and [[slot_class]] (name, count, memory_pages, image_pages, budget, sends); task names with meaning (uplink, telemetry, blockdev, disk, keys, attest, net, nic, mgmt-net, nic-mgmt, control)
- [IPC](index.html#ipc): send/recv/reply, generations, error codes
- [Supervisor](index.html#supervisor): death records, restart(id); restarts forever with backoff (10 ms doubling to 30 s, reset after 60 s), crash events; test features give-up-after-3/3000, backoff-fast, reset-after-2s, halt-on-exit
- [Drivers](index.html#drivers): BARs, DMA regions, IRQ notifications
- [Telemetry](index.html#telemetry): event ring, JSON line format, host-agent.py
- [Boot chain and attestation](index.html#boot-chain): Secure Boot, signatures, PCR 12, quotes (PCRs 0, 4, 7, 12, 13)
- [Storage](index.html#storage): on-disk format, key hierarchy, attested key release, restarts, storage events
- [Networking](index.html#networking): virtio-net driver, the net task (smoltcp), socket ops, routing and draining, limits, counters and events, NET/NET_MGMT
- [Deployment](index.html#deployment): generic slots ([[slot_class]]), signed descriptors (tools/sign-image.py sign-slot, VNRSIG02), slot_stage/slot_load/slot_unload by the agent (loads = true), PCR 13 and the kernel's run-time log, the TPM lock; agent test scripts are features; the agent's lifecycle (EMPTY, STARTING, READY, LIVE, DRAINING, DRAINED, STOPPED, FAILED), local swap, rollback, commit; supervisor OP_STOP/OP_START, kernel stop(); net OP_STATUS, DRAIN_NOWAIT; the agent dials the control plane over mgmt-net (OP_CONNECT, connects = true) with Noise IK (user/noise; pinned keys keys/cp-noise.pub and keys/cp-sign.pub), binds its keys with attest OP_QUOTE_FOR, applies signed desired state (live/stop/commit lines, rising generation), fetches images into slots, reports, and pulls telemetry (OP_PULL); tools/control-plane.py is the mock control plane (tests: CP=<scenario>); moves and evacuation between two nodes (tests/two-nodes.sh, NODES=2, UPDATE=1), desired-state line update (refused with instances; an empty node reboots: supervisor OP_REBOOT, kernel reboot())
- [Syscalls](index.html#syscalls): numbers and ABI (int 0x80; rdi, rsi, rdx, r10, r8, r9)
- [Protections](index.html#protections): each protection and the test proving it
- [Limitations](index.html#limitations)

## Working on vanir-os

- [Agent quick reference](index.html#agents): where to change what
- [Build, run, test](index.html#build): Make variables, exit status, test format
- [Test catalogue](index.html#tests): all 123 cases by area and what they need
- [Repository map](index.html#repo-map)
- [Recipes](index.html#recipes): add a program, test, syscall, event, device, manifest key
- [Invariants](index.html#invariants)
- [Troubleshooting](index.html#troubleshooting)
- [System dependencies](index.html#dependencies)

## Optional

- [apps/README.md](../apps/README.md): manifest format
- [plans/step-7-iommu.md](../plans/step-7-iommu.md): next planned step (IOMMU)
- [plans/step-8-bench.md](../plans/step-8-bench.md): benchmark plan (step 8)
- [plans/step-9-net.md](../plans/step-9-net.md): network services plan (step 9, done except the dos-* tests)
- [rfd/0001-network-services.md](../rfd/0001-network-services.md): the design behind step 9