nos

A hobby operating system kernel for x86-64 and arm64 (aarch64), written in C++20, Rust, and assembly. Code is partially written by AI models (Claude, GPT) with human control over architecture decisions, testing, and code review. Tested primarily in QEMU/KVM environments, including Google Cloud and Yandex Cloud VMs (MBR-based disk image, virtio devices), and on QEMU virt with HVF acceleration on Apple Silicon for the arm64 build. On x86-64 it boots under both legacy BIOS and UEFI. It also runs on real hardware — a laptop and two dedicated servers, one Intel and one AMD, see Real hardware — though only those three machines have been tried, so anything beyond them is untested.

Highlights

• Two architectures — x86-64 (Multiboot2/GRUB, BIOS and UEFI) and arm64 (QEMU virt, Linux Image protocol) behind a HAL layer; both stay green in CI
• SMP — up to 64 CPUs, preemptive multitasking with per-CPU queues and load balancing, per-CPU tick, TLB shootdown via IPI
• Memory — 4-level paging, all of the machine's RAM up to 512 GiB, page and pool allocators, W^X kernel image
• Interrupts — IDT/IOAPIC/LAPIC and MSI-X on x86-64, GICv3 with ITS-delivered LPIs on arm64, IRQ balancing across CPUs
• Drivers — virtio blk/net/scsi/rng (virtio-pci and virtio-mmio), NVMe in Rust, Realtek RTL8168/RTL8125 and Intel I210 NICs in Rust, xHCI USB keyboard, 8042, serial, VGA text and pixel framebuffer consoles
• Networking — ARP, IPv4, ICMP, DHCP, DNS, UDP, TCP, an HTTP client, a UDP remote shell and a netconsole that ships the kernel log over UDP
• Storage — async interrupt-driven block layer, MBR partitions, VFS with ramfs and the on-disk nanofs
• Observability — dmesg ring buffer, symbolized stack traces, a sampling profiler on the PMU, top, stack high-water marks, a lock watchdog

The complete list is in docs/features.md.

Quick start

./scripts/build-iso-docker.sh   # nos.iso + bin/kernel64.elf (or `make` with a native toolchain)
./scripts/qemu.sh               # boot the ISO in QEMU; serial console goes to nos.log

arm64:

make nocheck ARCH=aarch64       # kernel-arm64.elf + nos-arm64.img (in Docker on macOS)
./scripts/qemu-arm64.sh         # QEMU virt, HVF on Apple Silicon; serial goes to nos-arm64.log

The toolchain, the disk image for KVM clouds, and the BIOS/UEFI hybrid ISO are described in Build; QEMU with KVM/TCG/OVMF and Google Cloud deployment in Run.

Documentation

• Features — everything the kernel does today, by subsystem
• Build — native and Docker builds, arm64, the disk image, BIOS vs. UEFI
• Run — QEMU on x86-64 and arm64, Google Cloud
• Real hardware — Dell Latitude 5480 (UEFI, no serial, USB keyboard), Hetzner EX44 (20 CPUs, RTL8125 on the real internet) and Hetzner AX41 (AMD Ryzen, Intel I210, profiler on the PMU)
• Debug — GDB, getting a log off a box with no serial port
• Tests and gates — boot self-tests, smoke boots, and a gate per subsystem for what a smoke boot cannot notice
• Kernel parameters — boot-time options via GRUB or QEMU -append

How it works, by subsystem:

• Boot — GRUB/Multiboot2 and the Linux Image protocol to boot: complete, on both architectures, and how the APs come up
• Paging and memory — the bootstrap linear map, the real page table, the free list, the allocators, MMIO and W^X, TLB shootdown
• Scheduler — per-CPU run queues, the context switch, preemption, blocking and load balancing
• Interrupts — the IDT and IOAPIC, MSI-X, GICv3 and the ITS, IPIs, NMI, IRQ balancing, deferred work
• Profiler — sampling on a performance counter or the tick, and how to read a profile report
• Rust in the kernel — the crates and how they are layered, the types that stand in for unsafe, a map of kcore, writing a driver

Tools:

• UDP remote shell — udpshell=PORT + scripts/udpsh.py
• Netconsole — netconsole=ip:port + scripts/netconsole.py
• Shell commands — the full command reference
• Project layout — where things live in src/

The roadmap — a bare-metal cloud node running Linux guests under a Rust hypervisor, stages 0–5 — is in plans/README.md. Coding conventions and the boot flow are in CLAUDE.md.