Astra OS

Minimal, modern, Rust-based OS kernel. Not a Linux clone.

Status

Phase	Name	Status
0	Bootstrap	✅ Complete
1	Memory	✅ Complete
2	Interrupts	✅ Complete
3	VFS Core	✅ Complete
4	DevFS + Devices	✅ Complete
5	Scheduler	✅ Complete
6	ELF Loader + User Mode	✅ Complete
7	Syscall ABI	✅ Complete
8	Storage (FAT32)	✅ Complete
9	KernelFS	✅ Complete
10	MicroPython Port	🔲 Pending
11	POSIX Compatibility	🔲 Pending

What Astra Can Do Right Now

• Boots on x86_64 via the bootloader crate and prints to serial console (COM1)
• Manages physical memory with a bitmap frame allocator (up to 1 GiB)
• Maps virtual pages via 4-level x86_64 page tables with direct physical offset
• Allocates kernel heap memory through an 8-class slab allocator with bump fallback
• Handles all 20 CPU exceptions with full register dumps and fault diagnostics
• Remaps the 8259 PIC and handles timer, keyboard, and mouse IRQs
• Maintains a global tick counter from the PIT timer (configured for 1000 Hz)
• Provides an interactive kernel shell with command dispatch and history
• Provides a VFS with mount table, path resolution, and trait-based filesystem nodes
• Mounts RamFS at / with the full Astra directory hierarchy
• Mounts DevFS at /dev with dynamic device registration
• Scans the PCI bus and decodes all BARs (32/64-bit memory, I/O)
• Registers and probes virtio-blk, virtio-gpu, and virtio-net drivers
• Handles PS/2 keyboard input with full Set-1 scancode translation (US layout)
• Handles PS/2 mouse input with 3-byte packet decoding
• Runs a round-robin scheduler with context switching between kernel tasks
• Loads ELF64 binaries with PT_LOAD segment mapping and relocation processing
• Spawns user-mode processes with System V AMD64 ABI stack layout (argc/argv/envp/auxv)
• Implements 40+ syscalls matching the Linux x86_64 ABI numbers
• Supports read/write/open/close/stat/mmap/brk/fork/execve/exit/kill/uname/ioctl
• Configures SYSCALL/SYSRET via MSR registers (STAR/LSTAR/SFMASK)
• Mounts FAT32 filesystems from block devices with cluster chain traversal
• Provides an LRU block cache (256 blocks) with dirty tracking and writeback
• Manages per-process file descriptor tables (1024 fds, dup/dup2/cloexec)
• Exposes live kernel state through KernelFS at /kernel
• Reports per-process status, memory maps, and command lines via /kernel/proc/<pid>/
• Reports memory statistics, uptime, and tick count via /kernel/runtime/
• Reports PCI devices and CPU identification (CPUID) via /kernel/hw/
• [NEW] Provides a hardware-backed random number generator (rand command)
• [NEW] Modern HD Audio (Intel HDA) driver infrastructure for 32-bit PCM playback

Building

cargo build --target x86_64-unknown-none

Running

qemu-system-x86_64 \
  -drive format=raw,file="target/x86_64-unknown-none/debug/bootimage-astra-kernel.bin" \
  -serial mon:stdio \
  -no-reboot -no-shutdown \
  -m 256M

With a FAT32 disk image:

qemu-system-x86_64 \
  -drive format=raw,file="target/x86_64-unknown-none/debug/bootimage-astra-kernel.bin" \
  -drive file=disk.img,format=raw,if=virtio \
  -device virtio-gpu-pci \
  -device virtio-net-pci \
  -serial mon:stdio \
  -no-reboot -no-shutdown \
  -m 256M

Architecture

Bootstrap: The bootloader crate (v0.9.27) handles BIOS boot, real→protected→long mode transitions, and identity-maps physical memory at a configurable offset. The kernel entry point initializes all subsystems in sequence.

Memory: A bitmap frame allocator tracks 262,144 physical frames (1 GiB). Virtual memory uses the x86_64 crate's OffsetPageTable with the bootloader's physical memory offset. The kernel heap is a slab allocator with 8 size classes (16–2048 bytes) and a bump-allocator fallback, occupying 2 MiB at a high-half address.

Interrupts: All 20 CPU exceptions have dedicated handlers that dump register state. The 8259 PIC is remapped to vectors 0x20–0x2F. Timer IRQ0 drives the tick counter and scheduler. Keyboard IRQ1 and mouse IRQ12 feed their respective ring buffers.

VFS: A trait-based virtual filesystem with VfsNode as the core abstraction. The mount table resolves paths by longest-prefix matching. RamFS provides the writable root filesystem, DevFS exposes device nodes, KernelFS exposes live kernel state.

Devices: PCI config space scanner discovers devices via I/O ports 0xCF8/0xCFC. A driver registry matches devices to drivers by VID/PID. PS/2 keyboard and mouse use the 8042 controller. VirtIO drivers handle block, GPU, and network devices.

Scheduler: Round-robin scheduler with per-task kernel stacks (8 KiB). Context switching saves/restores callee-saved registers via inline assembly. Tasks have states: Running, Ready, Blocked, Dead.

Userland: ELF64 loader validates headers, maps PT_LOAD segments, and applies relocations. Process spawning builds a System V AMD64 ABI-compliant stack with argc/argv/envp/auxv. User-mode entry uses iretq with ring-3 selectors.

Syscalls: SYSCALL/SYSRET configured via MSR registers. 40+ syscalls implemented with Linux-compatible numbers. File I/O, process management, memory mapping, signals, and POSIX stubs for musl compatibility.

Storage: FAT32 driver reads BPB, walks cluster chains, parses 8.3 directory entries. LRU block cache provides transparent caching with dirty writeback. Per-process fd tables support 1024 descriptors.

KernelFS: Virtual filesystem generating content live from kernel state. Process info, memory stats, uptime, PCI devices, and CPU identification all available as readable files.

Repository Layout

.
├── boot_sound_gen.py
├── build.rs
├── Cargo.toml
├── docs
│   └── shell_commands.md
├── linker.ld
├── phases
│   ├── phase0-bootstrap.md
│   ├── phase1-memory.md
│   ├── phase2-interrupts.md
│   ├── phase3-vfs.md
│   ├── phase4-devfs.md
│   ├── phase5-scheduler.md
│   ├── phase6-elf-usermode.md
│   ├── phase7-syscall.md
│   ├── phase8-storage.md
│   └── phase9-kernelfs.md
├── README.md
├── run-qemu.bat
├── rust-toolchain.toml
└── src
    ├── assets
    │   └── boot_sound.mid
    ├── crypto
    │   ├── mod.rs
    │   └── rng.rs
    ├── device
    │   ├── block.rs
    │   ├── drivers
    │   │   ├── class
    │   │   │   ├── input.rs
    │   │   │   ├── input_mouse.rs
    │   │   │   └── mod.rs
    │   │   ├── intel_hda.rs
    │   │   ├── midi.rs
    │   │   ├── mod.rs
    │   │   ├── ps2_controller.rs
    │   │   ├── speaker.rs
    │   │   └── virtio
    │   │       ├── blk.rs
    │   │       ├── gpu.rs
    │   │       ├── mod.rs
    │   │       ├── net.rs
    │   │       └── virtqueue.rs
    │   ├── mod.rs
    │   ├── pci
    │   │   └── mod.rs
    │   └── registry.rs
    ├── fs
    │   ├── devfs.rs
    │   ├── fat32.rs
    │   ├── kernelfs.rs
    │   ├── mod.rs
    │   ├── ramfs.rs
    │   └── vfs.rs
    ├── gdt.rs
    ├── interrupt
    │   ├── handlers.rs
    │   ├── idt.rs
    │   └── mod.rs
    ├── main.rs
    ├── memory
    │   ├── frame_allocator.rs
    │   ├── heap.rs
    │   ├── mod.rs
    │   └── paging.rs
    ├── net
    │   └── mod.rs
    ├── panic.rs
    ├── scheduler
    │   ├── context_switch.rs
    │   ├── mod.rs
    │   └── task.rs
    ├── serial.rs
    ├── shell
    │   ├── commands
    │   │   ├── debug.rs
    │   │   ├── device.rs
    │   │   ├── edit.rs
    │   │   ├── fs.rs
    │   │   ├── memory.rs
    │   │   ├── mod.rs
    │   │   ├── net.rs
    │   │   ├── process.rs
    │   │   ├── system.rs
    │   │   └── time.rs
    │   └── mod.rs
    ├── syscall
    │   ├── mod.rs
    │   └── table.rs
    ├── userland
    │   ├── elf_loader.rs
    │   ├── fd_table.rs
    │   ├── mod.rs
    │   └── process.rs
    └── vga_buffer.rs

Documentation

Phase	Document	Summary
0	phase0-bootstrap.md	Serial console, panic handler, QEMU boot
1	phase1-memory.md	Frame allocator, page tables, slab heap
2	phase2-interrupts.md	IDT, exception handlers, PIC, timer
3	phase3-vfs.md	VfsNode trait, mount table, path resolution
4	phase4-devfs.md	PCI scan, drivers, PS/2, VirtIO, DevFS
5	phase5-scheduler.md	Task struct, round-robin, context switch
6	phase6-elf-usermode.md	ELF64 loader, process spawn, ring-3 entry
7	phase7-syscall.md	SYSCALL/SYSRET, 40+ syscall implementations
8	phase8-storage.md	FAT32 driver, block cache, fd table
9	phase9-kernelfs.md	Live kernel state via /kernel VFS
REF	shell_commands.md	Comprehensive command reference and usage

Design Philosophy

1. Kernel = platform. Userland = ecosystem. Never put tool logic in kernel space.
2. Everything is a VFS mount. No hardcoded paths in kernel logic.
3. Drivers are stateless traits. PnP manager owns lifecycle.
4. POSIX ABI contract = Linux compatibility. Implement the interface, not the internals.
5. musl before CPython. Never skip the libc layer.
6. MicroPython before CPython. Validate scripting layer cheap before paying the POSIX tax.

Filesystem Layout

/
├── sys/bin/       → user commands
├── sys/sbin/      → admin tools
├── sys/lib/       → shared libraries
├── sys/pkg/       → installed packages
├── kernel/proc/   → process table (kernelfs)
├── kernel/hw/     → hardware/driver view (kernelfs)
├── kernel/runtime/→ live system state (kernelfs)
├── dev/           → device nodes (devfs)
│   ├── kbd        → PS/2 keyboard
│   ├── mouse      → PS/2 mouse
│   ├── disk0      → VirtIO block device
│   ├── gpu0       → VirtIO GPU
│   ├── net0       → VirtIO network
│   └── null       → /dev/null
├── users/root/    → root home directory
├── data/config/   → system configuration
├── data/tmp/      → temporary files
└── boot/          → boot files