GenOS Documentation

Here are our notes on building, using and hacking on GenOS. We keep the documentation with the source on GitHub. GenOS is still Experimental / ALPHA software; please read the limitations before trying it. These documents cover what is there now and what is still missing. For our plans, see the roadmap.

Inside the machine

The loader starts the kernel. The kernel manages the hardware and gives programs controlled access to memory, files and the network. The shell is one of those programs.

An illustrated map of GenOS. Storage and networking are kernel services; Ring 3 programs reach them through system calls. This is a guide to the design, not a claim that every part is finished.

New to GenOS? Start here

Project README — what GenOS is and where development stands.
Roadmap and acceptance gates — our R1/R2/R3 plans and the checks needed for each.
Known limitations — known problems and missing compatibility, security and release work.
Reference VM — the exact tools, firmware and devices we test with, and the limits of those tests.
Engineering quality plan — release levels, tests and what we need before shipping.

Building, running and testing

Build and run — the commands you need to try a build.
Normal and validation boot — the two image types, test commands and results.
Terminal — shell commands, controls and current console limits.
Standalone SDK — building and testing a native application outside the workspace.
Compatibility — the native ABI, image format and limits on feature negotiation.
Verification record — test results with the source revision and setup used.
CI policy — required checks and how we record test runs.

Notes on the kernel and userspace

Userspace and ABI — Ring 3 boundaries, syscalls and typed capabilities.
Runtime — ownership, scheduling and deferred completion.
Memory — frame ownership, mapping constraints and diagnostics.
CPU state — which process register state is handled, and its limits.
Fault containment — exception nesting and return handling.
Storage — bounded snapshots, commit semantics and recovery.
Networking — bounded IPv4, socket and device contracts.
IPv6 — demonstrated control-plane behavior and remaining socket/conformance work.
VirtIO profile — the supported modern PCI network device configuration.
Security model — experimental trust boundaries and security work still to do.

Hacking on GenOS

Architecture decisions — recorded design choices and how we document new ones.
Primary-source research — background reading for our development plans.
Contribution guide — how to send focused changes and show how you tested them.
Security reporting policy — the project’s private reporting and disclosure process.
Complete documentation index — more notes and links to the rest of the documentation.

A small glossary

No need to learn all of these before looking around. Here are a few words you will meet in our notes.

Kernel: The central part of an operating system. It manages memory, devices and the turns programs take on the CPU.
UEFI and loader: UEFI is the PC firmware that starts before an operating system. The loader is the small program it starts to load our kernel into memory.
QEMU and VM: QEMU is an emulator: it runs a virtual computer on your computer. We call that virtual machine a VM, and the operating system inside it the guest.
Ring 3 and userspace: Ring 3 is the x86 CPU mode used for ordinary programs. Userspace means the programs outside the kernel. They ask the kernel to do privileged work through system calls.
Capability: A handle a program holds for a particular resource, with a particular set of allowed operations. Having one does not mean the whole system has been proven secure.
Serial console: A text connection to the guest. It carries boot messages, keyboard input and shell replies, without a graphical desktop.
VirtIO: A family of virtual devices made for virtual machines. GenOS uses a limited VirtIO network device profile; this does not mean every VirtIO device works.
VFS: The virtual file system: the kernel's common way to name and access files, regardless of the storage behind them.
ABI and SDK: The application binary interface (ABI) is the low-level agreement between a compiled program and the system. A software development kit (SDK) provides tools and examples for writing programs for it.
no_std: Rust code built without the usual standard library. A kernel must provide many basic services for itself.
Qualification and gates: Qualification means checking a particular setup against stated requirements. A gate is a group of checks that must pass before a milestone can be reached.
TCG, SMP and NIC: TCG is QEMU's software CPU emulation. SMP means using multiple CPUs together; GenOS currently runs its kernel on one CPU. A NIC is a network interface card.
POSIX and TLS: POSIX describes common operating-system interfaces. TLS protects network connections with encryption. GenOS does not promise full POSIX compatibility or general TLS support.