Sword Operating System (SOS)

A sovereign x86-64 operating system, written 100% from scratch in Rust (nightly, edition 2024) and NASM assembly. Custom bootloader (no GRUB, no bootloader crate, no cargo bootimage), zero external crates: every byte that executes in real mode, protected mode, and long mode was hand-written for this project.

Sword Operating System v1.2.0
Default account: root / root (change the password after logging in).

login: _

Table of contents

• Philosophy
• Architecture
• Repository layout
• Requirements
• Building
• Running
• Shell command reference
• Installing on real hardware
• Further documentation
• License

Philosophy

• Total sovereignty over the boot process. A hand-written 16-bit stage1 (MBR, 512 bytes), a stage2 in assembly that performs the 16→32→64-bit transition and builds the kernel's page tables, and a from-scratch ISO builder (ISO 9660 + El Torito no-emulation — no mkisofs, no xorriso).
• Zero external dependencies. Not even spin, x86_64, or uart_16550: the mutex, I/O port access, IDT/GDT, VGA framebuffer, and the entire cryptography stack (SHA-256, HMAC, PBKDF2) are all hand-implemented in this repository.
• no_std, no heap. Every kernel structure (the file table, the user table, the task table) is a fixed-size static array — the same discipline a microcontroller firmware would use.

Architecture

Boot paths

The same kernel binary is reachable through three different boot images, because three different classes of hardware (plus one emulator) each expect something different from a bootable disk:

Image	Boot mode	Partition scheme	Produced by
build/sos.img	BIOS / Legacy	raw, no partition table	boot/stage1/stage1.asm (512-byte MBR) + boot/stage2/stage2_boot.asm
build/sos.iso	BIOS / Legacy, via El Torito	ISO 9660 + hybrid MBR	boot/iso_builder (from-scratch ISO 9660 writer)
build/sos_uefi.img	UEFI only	GPT + FAT32 ESP	boot/uefi (a separate x86_64-unknown-uefi binary) + boot/uefi_img_builder

stage1.asm loads stage2_boot.asm, which walks the CPU through 16-bit real mode → 32-bit protected mode → 64-bit long mode, builds its own identity-mapped page tables, and jumps into the Rust kernel at 0x10000. The UEFI path is an entirely separate binary that speaks just enough of the UEFI Boot Services protocol (hand-written, no uefi crate) to load KERNEL.BIN from a GPT+FAT32 disk it also builds itself, then hands off control to the kernel at 0x100000.

Two video backends

The kernel draws the same 80×25 console through two different code paths, selected at boot:

• BIOS/Legacy: classic VGA text mode. Character codes are written directly to 0xB8000; the hardware converts them to glyphs.
• UEFI: the bootloader hands the kernel the firmware's graphics framebuffer (GOP), and the kernel rasterizes every glyph itself, pixel by pixel, with its own bitmap font (kernel/src/drivers/fb.rs).

The second path is not optional polish: on real UEFI hardware, classic VGA text mode does not exist at all — the 0xA0000–0xBFFFF window is unmapped and nothing listens on the legacy VGA ports, since modern integrated graphics are programmed entirely through MMIO. QEMU's emulated hardware papers over this (it exposes a genuine Bochs-VBE-capable VGA chip regardless of boot mode), which is exactly why this kernel once booted flawlessly on a real UEFI notebook — keyboard, disk, shell, all of it — while showing nothing whatsoever on screen.

Two disk backends

kernel/src/drivers/block.rs is the single entry point the filesystem and the installer use to read or write a sector. Underneath, it selects between two independent drivers:

• IDE PIO (drivers/ide.rs): I/O ports starting at 0x1F0, data moved through the CPU. What a machine from the IDE era has.
• AHCI/SATA (drivers/ahci.rs): located by walking the PCI bus (drivers/pci.rs), driven through memory-mapped registers, DMA transfers. What virtually any machine built in the last fifteen years has.

lspci lists what the PCI bus reports; diskinfo reports which of the two drivers is actually in use.

Filesystem: SFS

SFS (Sword FileSystem) is a from-scratch persistent filesystem with a real directory hierarchy and a FAT-like block table that doubles as both the free-space allocator and each file's own chain of blocks — no built-in ceiling on file count or size beyond the disk itself.

At boot, SFS only ever does one of three things: mount its own superblock if one is present, format a disk that is provably blank, or — on encountering an MBR, a GPT table, or filesystem debris belonging to something else — stop and report it, untouched. SOS will never format a disk that isn't its own.

Kernel core

_start (kernel/src/lib.rs) rebuilds everything the boot trampoline only improvised: its own GDT, its own 256-entry IDT, and its own remapping of the two chained 8259 PICs (hardware IRQs are moved off vectors 0–15, where they would otherwise collide with CPU exceptions, onto vectors 32–47). The Programmable Interval Timer is reprogrammed to fire at 100 Hz and is the sole source of elapsed time in the system (sleep, disk-command timeouts, scheduler bookkeeping). Multitasking is a deliberately simple cooperative, round-robin scheduler: each task owns a small dedicated stack and voluntarily yields control with yield_now() — there is no preemption.

Cryptography

Accounts authenticate against PBKDF2-HMAC-SHA256, with SHA-256, HMAC, and PBKDF2 all implemented from scratch (kernel/src/crypto/), no hardware acceleration, no crate. Each account carries its own 16-byte salt; verification runs in constant time.

Repository layout

boot/
├── stage1/           16-bit ASM, 512-byte MBR
├── stage2/            ASM, 16→32→64-bit trampoline
├── iso_builder/        host tool (Rust std) that writes sos.iso
├── uefi/               UEFI bootloader (x86_64-unknown-uefi, no build-std)
└── uefi_img_builder/   host tool (Rust std) that writes sos_uefi.img
common/
└── diskfmt/            shared GPT/FAT32 writer used by the installer and uefi_img_builder
kernel/
└── src/
    ├── lib.rs           _start, subsystem bring-up
    ├── install.rs       writes SOS onto a real disk
    ├── arch/x86_64/     gdt, idt, pic, pit, port, context (task switch), power, acpi
    ├── drivers/         vga, fb, keyboard, ide, ahci, pci, block, mutex
    ├── fs/               vfs (public API) + sfs (the persistent filesystem)
    ├── shell/            parser, commands, history, the SuSH interpreter, the Papyrus editor
    ├── users/            auth (persistent accounts), session (login/permissions)
    ├── task/             the cooperative scheduler
    └── crypto/           sha256, hmac_sha256, pbkdf2
site/
└── index.html            the project's public web page (self-contained, no build step)

Requirements

• Rust nightly, with the x86_64-unknown-none target and the rust-src / llvm-tools-preview components (required for -Z build-std, rust-lld, and rust-objcopy).
• NASM on PATH.
• QEMU (qemu-system-x86_64) on PATH.
• Windows + PowerShell 5.1 (the build script targets that shell specifically).

Building

.\build.ps1

This runs the full pipeline in one step: assembles stage1 (both the 512-byte IMG variant and the 2048-byte ISO variant) and stage2, builds the kernel with -Z build-std, links it with rust-lld, converts it to a flat binary with rust-objcopy, assembles sos.img and the hybrid sos.iso, builds sos_uefi.img, creates hdd.img (an 8 MB scratch disk) and target.img (a blank disk for exercising the installer) only if they don't already exist — both persist across builds so disk persistence can actually be tested — and finally launches QEMU.

Pass -NoRun to build every image without launching QEMU (useful when the target is real hardware — see Installing on real hardware):

.\build.ps1 -NoRun

Running

Default account on first boot: root / root. Change it immediately after logging in:

passwd root <new-password>

Accounts, passwords, and keyboard layout are persisted to disk (SFS) and survive a reboot.

Line editor and shortcuts

A real cursor (Left/Right, Home/End, Delete, insertion at any position — not only at the end), command history (Up/Down), and a scrollback buffer reachable with Shift+Up/Down (typing anything jumps back to the live view). Shortcuts: Ctrl+C (cancel the current line), Ctrl+L (clear the screen without losing scrollback), Ctrl+U (kill the line).

Shell command reference

Files & scripting

Command	Description
ls [path]	List a directory
cat <file>	Print a file's contents
write <file> <text...>	Create or overwrite a file
copy <src> <dst>	Copy a file (max 32 KB)
rm <file>	Delete a file
mkdir <path>	Create a directory
cd [path]	Change the current directory
pwd	Print the current directory
sush <file>	Run a .sush script — see README_SUSH.md
papyrus <file>	Full-screen text editor (max 256 KB)
mkfs	Reformat the disk (admin, destructive)

Users & sessions

Command	Description
useradd <name> <password> [admin]	Create an account
userdel <name>	Delete an account (admin)
users	List accounts
passwd <name> <new>	Change a password
login <name> <password>	Log in as another user
logout	End the current session
whoami	Print the current user

System

Command	Description
help [command]	List commands, or show detailed help for one
echo [text...]	Print arguments
clear	Clear the screen
about	System information
version	Kernel version and toolchain
uptime	Time since boot
sleep <ms>	Block for a duration
tasks	List scheduler tasks
history	Show command history
keyboard [us|latam]	Show or set the keyboard layout (persistent)
reboot / shutdown	Restart or power off (admin)

Disk & hardware

Command	Description
lspci	List PCI devices
diskinfo [master|slave]	Disk model, capacity, active driver
diskread / diskwrite	Raw sector access (admin)
install <master|slave> [bios|uefi] confirm	Install SOS onto a real disk (admin, destructive)

Installing on real hardware

install <master|slave> [bios|uefi] confirm writes a bootable SOS installation directly onto a physical disk, from a running SOS session — typically one booted live from a USB drive. This is how SOS gets from "an image in build/" to "the operating system a laptop actually boots into."

The full walkthrough (flashing a USB drive with Rufus, BIOS/UEFI boot menu quirks, Secure Boot, disk identification, and what to do if power is lost mid-install) lives in INSTALL.md — read that before running install against anything with data on it.

License

• Bootloader (boot/) and kernel (kernel/): MPL 2.0 (see LICENSE).
• Userland (if any is ever added): MIT.