genrt is an experimental hard real-time operating system written primarily in
Rust. The active platform is single-core AArch64 QEMU virt; the project uses
that controlled environment to make boot, scheduling, userspace, testing, and
release invariants explicit before expanding hardware scope.
genrt is aimed at operating-system and embedded developers who want a compact, inspectable codebase for studying deterministic kernel mechanisms. Its focus is explicit ownership, bounded runtime structures, machine-checked QEMU contracts, and reproducible release artifacts. It is a research and learning project, not a production-ready or latency-certified operating system.
- High-half EL1 kernel with low-linked pre-MMU bootstrap and post-link autonomy verification.
- DTB-driven RAM/platform discovery, physical frame allocation, runtime TTBR1 mappings, and a fixed bootstrap heap.
- Preemptive IRQ-return scheduler with one-shot deadlines, bounded kernel threads, sleep, and mailbox IPC.
- Process-owned TTBR0 address spaces, static AArch64 ELF loading, lower-EL fault
isolation, and eager-copy
fork/execve/waitpid. - Readonly CPIO initramfs, bounded per-process FD tables, cwd/path traversal, directory iteration, and UART-backed stdin.
- Freestanding C shell and product programs declared by
user/c/programs.toml. - Declarative QEMU contracts using a test-only machine protocol rather than human log matching.
- Deterministic, structurally verified tagged release bundles built by
xtask.
See the current-state snapshot for implemented details and cross-cutting invariants for constraints.
On Arch Linux x86_64 or Ubuntu 24.04/26.04, clone the repository and run:
git clone https://github.com/redeemed-sis/genrt.git
cd genrt
./scripts/setup/install-deps.sh
cargo xtask run-aarch64The default image boots the production kernel and initramfs shell. QEMU uses
the terminal as PL011 UART input; enter ls, pwd, cat /etc/banner,
echo hello, or exit. Use Ctrl-c to stop QEMU.
The image shows the current production shell after boot; the preceding kernel diagnostic log is cropped. Commands and output are derived from the production userspace and initramfs shipped by this repository.
For the full local verification gate, run separately:
cargo xtask ciSee host dependency setup for supported platforms, manual installation, non-interactive use, and Rust migration guidance.
Useful debugging commands:
just debug-aarch64
just gdb-aarch64See AArch64 debugging for the two-terminal GDB workflow and artifact locations.
cargo xtask check
cargo xtask test-aarch64 --list
cargo xtask test-aarch64
cargo xtask cicheck runs host formatting/tests/clippy, production builds, initramfs policy,
and the .boot.text post-link check. test-aarch64 runs QEMU contracts.
ci is the canonical local and hosted merge gate. Detailed test architecture,
artifacts, and case authoring live in docs/testing.md.
cargo xtask dist --tag v0.0.0-local.1 --output-dir /tmp/genrt-distThe release gate tests exact production executables in controlled contract images, verifies production composition and hashes, and emits a deterministic bundle. See the published releases and docs/releases.md.
| Path | Responsibility |
|---|---|
arch/aarch64/ |
AArch64 boot, MMU, exceptions, IRQ, timer, GIC, and UART |
kernel/ |
Architecture-neutral kernel policy and mechanisms |
crates/bootinfo/ |
Early boot handoff types |
user/ |
Freestanding userspace and initramfs product data |
tools/xtask/ |
Canonical build, QEMU, test, and release workflows |
tests/qemu/ |
QEMU system contracts and test-only fixtures |
memory/ |
Current state, durable invariants, and ADRs |
docs/ |
Development, testing, release, and roadmap guides |
.codex/ |
Project custom-agent configuration |
.agents/ |
Repository skills and engineering standards |
- Documentation map
- AArch64 architecture
- Kernel architecture
- Memory subsystem
- Scheduler and time
- Filesystem and FD model
- xtask workflows
- QEMU contract tests
- Userspace
- Project decisions
- Agent-oriented workflow
- Single-core only; no SMP locks, TLB shootdown, or latency certification.
- No FP/SIMD context ownership; kernel Rust uses the soft-float target.
- No ASIDs, copy-on-write, demand paging, signals, or recoverable usercopy faults.
- One main user thread per process and a deliberately small process-control ABI.
- Readonly ramfs rather than a writable VFS or storage stack.
- Raw UART stdin rather than a terminal/TTY subsystem.
- Fixed bootstrap heap and limited kernel VM mapping granularity.
- x86_64 and RISC-V ports are structural placeholders, not active targets.
Active hardening topics are tracked in docs/roadmap/hardening.md, without assigning them calendar-based milestones.
genrt is distributed under the MIT License.
Start with CONTRIBUTING.md. Repository engineering rules live in AGENTS.md and the nearest nested instructions. Commits follow Conventional Commits; new or changed public and crate-visible Rust APIs follow the rustdoc standard.
Looking for a first task? The repository has several scoped issues suitable for new contributors:
- Validate the Quick Start on your Linux distribution
- Add the
wcuserspace utility - Add the
unamesyscall and userspace utility
Questions and draft pull requests are welcome.