Architecture

Layer Stack#

Helix follows a strict layered architecture — every layer only depends on layers below it, never above. This is enforced at compile time through Cargo dependency declarations: if crate A depends on crate B, crate B cannot depend on crate A.

Layer Rules#

1. No upward dependencies — helix-hal never imports helix-core. Subsystems access hardware only through HAL traits.
2. No circular dependencies — Cargo enforces this at workspace resolution time.
3. Trait-based abstraction — Each layer boundary is defined by traits: HalImpl, Subsystem, Module, SyscallHandler.
4. Compile-time target selection — Architecture-specific code is selected via #[cfg(target_arch)], not runtime dispatch.

---

Workspace Structure#

The Cargo workspace at the root defines 16 member crates plus the Lumina graphics sub-workspace and the Magma GPU driver sub-workspace:

Sub-workspaces#

Workspace Metadata#

[workspace.package]
version = "0.4.0"        # codename "Aurora"
edition = "2021"
rust-version = "1.75.0"
license = "MIT"

[workspace]
members = [
    "core", "hal", "boot/limine", "boot/multiboot2", "boot/uefi",
    "subsystems/memory", "subsystems/execution", "subsystems/dis",
    "subsystems/userspace", "subsystems/relocation", "subsystems/nexus",
    "subsystems/init", "modules", "modules_impl/schedulers/round_robin",
    "fs", "benchmarks", "profiles/minimal",
]

---

Crate Dependency Graph#

Below is the full dependency graph showing how every crate connects. Arrows point from dependent to dependency:

Dependency Rules#

External Dependencies (workspace-wide)#

The entire kernel uses only 4 external crates. Everything else is written from scratch.

---

Project Metrics#

---

Design Principles#

Helix is designed around five core principles that guide every architectural decision:

1. Compile-Time Safety#

Rust's type system and ownership model are used extensively to prevent entire classes of kernel bugs at compile time:

• No null pointers — Option<T> everywhere
• No data races — Send/Sync bounds enforced on all shared state
• No buffer overflows — bounds-checked arrays, no raw indexing in safe code
• No use-after-free — ownership model prevents dangling references
• panic = "abort" — no unwinding in kernel space, predictable failure mode

2. Trait-Driven Abstraction#

Every major subsystem boundary is defined by a trait, enabling pluggable implementations:

3. Zero External Dependencies (almost)#

The kernel uses only 4 external crates (spin, bitflags, libm, heapless). Everything else — schedulers, allocators, filesystems, graphics, AI — is written from scratch.

4. Hot-Reloadable Modules#

The module system supports runtime replacement without downtime:

1. Save module state via get_state() → ModuleState
2. Unload old module binary
3. Load new module binary, verify ABI compatibility
4. Restore state via restore_state(ModuleState)
5. Resume execution

5. Layered Initialization#

The kernel boots through 5 strictly-ordered phases, each unlocking new capabilities:

---

Build Profiles#

Helix defines six Cargo build profiles tailored for different use cases:

[profile.dev]
opt-level = 0          # No optimization — fastest builds
lto = false
debug = true           # Full debug info
panic = "abort"        # No unwinding in kernel
codegen-units = 256    # Maximum parallelism

[profile.release]
opt-level = 3          # Maximum optimization
lto = "fat"            # Full link-time optimization
debug = false          # No debug info
panic = "abort"
codegen-units = 1      # Best optimization (single CGU)

[profile.release-debug]
inherits = "release"
debug = true           # Release speed + debug symbols

[profile.production]
inherits = "release"   # Alias for CI/CD pipelines

[profile.bench]
opt-level = 3
lto = "thin"           # Faster than fat LTO, still good
panic = "abort"

[profile.test]
opt-level = 1          # Some optimization for realistic tests
debug = true
panic = "abort"

Profile Selection Guide#

All profiles use panic = "abort" — stack unwinding is not supported in kernel space.

---

Toolchain#

The project pins a specific nightly via rust-toolchain.toml:

[toolchain]
channel = "nightly"
components = ["rust-src", "rustfmt", "clippy", "llvm-tools-preview"]
targets = ["x86_64-unknown-none"]

Required Components#

Compile Targets#

Nightly Features Used#

---

Linker Scripts#

Helix ships five linker scripts for different boot protocols. All higher-half scripts map the kernel to the top 2 GB of virtual address space.

Memory Layout#

All higher-half linker scripts produce the following virtual memory layout:

Exported Symbols#

Every linker script exports these symbols for use in Rust code:

__kernel_start, __kernel_end          # Kernel image boundaries
__text_start, __text_end              # Code section
__rodata_start, __rodata_end          # Read-only data
__data_start, __data_end              # Mutable data
__bss_start, __bss_end                # Zero-init section
__got_start, __got_end                # GOT (for KASLR relocation)
__rela_start, __rela_end              # Relocation entries
KERNEL_PHYS_BASE, KERNEL_VIRT_BASE    # Physical/virtual base addresses

These are accessed in Rust via extern "C" blocks and used during early boot to set up paging and perform KASLR relocation.

---

Boot Sequence#

The boot flow from power-on to kernel_main passes through 5 initialization phases managed by helix-init:

Init Subsystems#

The init framework registers 13 subsystems with dependency ordering:

KernelState Machine#

The kernel transitions through a state machine managed by KernelOrchestrator:

Each state transition triggers registered LifecycleCallback handlers.

---

Build Commands#

Make Targets#

make build           # Release build (opt-level 3, fat LTO)
make build-debug     # Debug build (opt-level 0, full debug info)
make qemu            # Build + launch in QEMU
make qemu-debug      # Build debug + QEMU with GDB server on :1234
make test            # Full test suite (integration + unit)
make test-unit       # Unit tests only (host target)
make clippy          # Lint check (-D warnings)
make fmt             # Format all code (rustfmt)
make fmt-check       # Verify formatting without changes
make docs            # Generate rustdoc (private items)
make iso             # Create bootable ISO image
make clean           # Remove build/ and target/
make pre-commit      # fmt-check + clippy + test (CI gate)
make size            # Show kernel binary size breakdown

Just Recipes#

just build           # Release build
just watch           # Rebuild on file changes (cargo-watch)
just doc-serve       # Serve docs on localhost:8000
just audit           # cargo audit + cargo deny check

Docker#

docker compose run dev       # Interactive dev shell with all tools
docker compose run build     # One-shot release build
docker compose run test      # Full test suite in container
docker compose run qemu      # QEMU with port forwarding (1234, 5900)

Nix#

nix develop          # Enter development shell with all deps
nix build            # Reproducible release build

---

Data Flow#

Understanding how data flows through the kernel helps grasp the architecture:

Syscall Path#

IPC Path#

Module Hot-Reload Path#

---

Security Architecture#

Security is embedded at every layer of the kernel:

Capability-Based Access Control#

The CapabilityBroker in helix-core manages fine-grained permissions:

Isolation Levels (DIS)#

The Dynamic Intent Scheduling system defines 5 isolation levels:

Protection Keys (Memory)#

The memory subsystem supports Intel PKU for per-page protection domains:

• ProtectionFlags: NONE, READ, WRITE, EXECUTE, RW, RX, RWX
• ProtectionDomain: Groups pages under a single protection key
• GuardPage: Unmapped pages surrounding stacks to catch overflows

---

Error Handling Strategy#

Helix uses a consistent error handling pattern across all crates:

1. Each crate defines its own error enum — KernelError, MemError, HalError, ModuleError, etc.
2. All errors are Send + Sync — safe to pass across thread boundaries
3. No panics in normal paths — Result<T, E> everywhere
4. Panic = kernel halt — panic = "abort" in all profiles, custom PanicHandler logs context
5. Self-healing for recoverable failures — SelfHealingManager monitors subsystem health and triggers automatic recovery (max 3 restart attempts)

Panic Handling#

The PanicContext captures: message, location (file:line:col), backtrace, CPU state, and the current thread ID.