Technical note · the July 2026 audit

A full technical audit of this codebase wrapped up in July 2026: 30-plus real defects found and fixed, ranging from a filesystem block allocator that could silently corrupt a different file than the one being written, to a guaranteed stack overflow on real UEFI hardware, to a handful of authentication weaknesses around the user table. None of that is presented here as “now it's bug-free.” A project that hand-writes its own mutex, IDT, and cryptography stack accumulates real defects as a simple consequence of its own ambition — finding and fixing them honestly is the actual engineering work. Every fix from this pass landed with a comment in the source explaining the bug it was written against, so it doesn't quietly come back.

One gap the audit could not close: hardware coverage. Every fix has been re-verified end-to-end on the BIOS boot path on real hardware. The UEFI path builds cleanly and every change to it has been reasoned through by hand, but it has not yet been re-run start-to-finish on a physical UEFI machine since these fixes landed.

Technical note · the video problem

The kernel draws the same 80×25 console through two entirely different code paths, and which one runs is decided at boot. Under BIOS, it writes character codes directly into 0xB8000 — classic VGA text mode, and the hardware turns those bytes into glyphs on its own. Under UEFI, that memory window simply does not exist on real firmware, so the bootloader instead hands the kernel the firmware's graphics framebuffer (the Graphics Output Protocol), and the kernel draws every glyph itself, pixel by pixel, with its own bitmap font.

QEMU's emulated hardware happens to support classic VGA text mode even when booted via UEFI, because the emulated card is a genuine Bochs-VBE-capable VGA chip underneath. Real UEFI laptops are not that generous. The first time this kernel booted on an actual UEFI notebook, it came up perfectly — keyboard, disk, shell, all of it — and showed nothing whatsoever on the screen, because it was faithfully writing to a memory address that nobody on that machine was reading.

That per-pixel drawing also used to make scrolling visibly slow on real UEFI hardware: advancing one line meant re-rasterizing all 1,920 glyphs on screen from the bitmap font, roughly a million individual pixel writes per line feed at 1080p. The console now moves whole scanlines instead of redrawing every glyph — the difference between a laggy terminal and a normal one, on the same firmware.

Technical note · the storage problem

Until this audit, AHCI/SATA disks only worked when SOS booted via UEFI. The reason lived one layer below the driver itself: stage2, the 16→32→64-bit trampoline, only ever identity-mapped the first 4 MB of physical memory, and an AHCI controller's memory-mapped registers sit well above that on real hardware. Touching them from the BIOS path was an instant page fault, so the driver was gated to UEFI only — which meant any modern PC booted in Legacy mode, still the far more common case in the wild, saw no usable disk at all: nothing persisted, and the installer had nowhere to install to. It was the single largest functional gap in the project.

stage2 now builds three additional page directories and identity-maps a full 4 GB, so AHCI/SATA registers are reachable from either boot path, and both now have the same disk support.

Technical note · why the UEFI image shrank

sos_uefi.img dropped from 315 MB to 72 MB, and the smallest disk it can install onto from roughly 300 MB down to about 70 MB. FAT32, the format required for the EFI System Partition, refuses to format a volume with fewer than 65,525 clusters; at the previous 4 KB cluster size, that floor forced a 268 MB partition no matter how little the ESP actually held. Shrinking the cluster size to 1 KB moves the same floor down to 64 MB.

Technical note · memory management, in three layers

The audit added the three pieces a kernel needs before it can host userland at all, in the strict order they have to come up: a physical memory manager (mm::pmm) that harvests UEFI's free-RAM map into a bump allocator; a kernel-owned virtual memory manager (mm::paging) that replaces the firmware's inherited page tables with ones the kernel built itself and so can safely hand out high userland addresses without clobbering its own identity map; and a heap (mm::heap) on top of the PMM, used narrowly — most kernel state still lives in fixed-size statics. pmm → paging → heap is the order mm::init() runs them in, and the order that matters: the heap is page-mapped, and paging needs the PMM to give it pages.

Technical note · zero_bss

The file the bootloader actually reads off disk, kernel.bin, does not contain the kernel's .bss section at all. Any static without an explicit non-zero initializer — the IDT table, the scheduler's task list, every fixed-size buffer in the shell — occupies memory once the kernel is running, but zero bytes in the file on disk. The very first line of _start, before anything else runs, is a hand-written zero_bss() that walks from the linker-provided _bss_start to _bss_end and blanks it by hand. Skip that step, and every one of those structures boots with whatever happened to already be sitting in RAM.

For most of this project's life, that also meant .bss had almost nowhere to grow on the BIOS boot path: it started right after the kernel's own loaded code and ran up against the VGA memory window at 0xA0000, leaving only about 20 KB of headroom. A completely unrelated one-line change — doubling Papyrus's text buffer from 256 KB to 512 KB — would have grown .bss straight through that ceiling and started corrupting VGA memory, breaking the BIOS boot silently while the UEFI build, which has no such low-memory ceiling, kept working and testing green. The fix relocates the kernel's .bss above the 1 MiB mark, growing the BIOS path's headroom from about 20 KB to 640 KB, and build.ps1 now checks both boot paths so a regression like that fails loudly instead of only on somebody's BIOS machine.

Technical note · dropping privilege, the long way round

enter_ring3 is hand-written assembly for the same reason context_switch is: the moment of actually dropping CPL requires a frame on the stack laid out exactly the way iretq expects (SS, RSP, RFLAGS, CS, RIP, in that order), with the ring-3 selectors gdt::load() installed at boot baked into CS and SS — there is no compiler intrinsic for that, and Rust's x86-interrupt ABI gives no way to redirect the eventual return. So the kernel saves the six callee-saved registers and its own RSP, builds that frame, sets IF=1 in the flags it pushes (ring-3 code starts with interrupts enabled), and iretqs. The return is just as deliberate: vector 0x80 is an interrupt-gate-at-DPL-3, so ring-3 code reaches it with a plain int 0x80; a cmp rax, 0 in the handler decides whether that trap is SYS_EXIT (abandon ring 3 entirely, restore the saved RSP and registers, ret) or any other syscall (dispatch in ring 0, then iretq right back where the int 0x80 came from).

Technical note · every program at its own address

The three programs used to share a single fixed virtual address (0x4000000000) on the assumption that "only one ring-3 program runs at a time." SYS_RUN_LINE breaks that assumption on purpose: a running SuSH script can dispatch a line like papyrus file.txt as one of its OWN lines, which loads a SECOND program into ring 3 while the first (SuSH) is merely paused, not finished. These are ET_EXEC binaries with no relocations, so their machine code contains absolute addresses baked in at link time — reusing the same address would have the inner program overwrite the outer program's still-needed code/data/stack. Each program now has its own disjoint range:

Technical note · two bugs the ring-3 audit itself uncovered

Closing a Papyrus session with Ctrl+Q used to lock up the whole machine. The cause is a one-instruction detail of how x86_64 privilege gates work: vector 0x80 is an interrupt gate (Type 0xE), and the CPU hardware-clears IF on entry to one, exactly as for a hardware IRQ. The normal syscall path restores IF via its own iretq, which pops ring 3's saved RFLAGS (IF=1, forced by enter_ring3). The SYS_EXIT path never executes an iretq at all — it discards that frame and does a plain ret — so IF stayed cleared for the rest of the kernel's life the instant any ring-3 code exited. No keyboard IRQ, no timer tick, nothing, ever again. The diagnostic commands never surfaced it because nobody typed right after them; closing Papyrus is exactly when a user reaches for the keyboard. A single sti before that ret closed it.

The second is one an earlier audit cleanly missed. Saving the outer excursion's RSP was necessary but not sufficient, because the CPU also reloads RSP from TSS.rsp0 on every ring 3→ring 0 transition — with no notion of nesting. With rsp0 a boot-time constant, a nested program's first int 0x80 pushed its interrupt frame at exactly the address the outer excursion's own frame, and the entire live call chain below it, already occupied — SYS_EXIT then faithfully popped garbage into the callee-saved registers and reted to a garbage address. enter_ring3 now repoints TSS.rsp0 at its own current RSP per nesting level and the SYS_EXIT path puts the previous value back — the ordinary "one kernel stack per thread of control" arrangement, achieved in hand-written assembly.

Technical note · rmdir and the block-table cache

The one thing every earlier version of SFS could do but never undo was making a directory: mkdir created a permanent entry, with no rmdir to remove it, so every directory's block stayed allocated forever even once it was empty. This audit adds rmdir.

Writing a file was also far more expensive than it needed to be. The block table lives in 512-byte sectors, but each write only touches the 4 bytes belonging to one file's chain entry — so saving a 256 KB file, 512 blocks of data, cost roughly 2,560 sector operations, a full sector read-or-rewrite of the block table for every single block written. A one-sector write-back cache in front of the block table brings that down to about 520.

$ cat count.sush
set i 0
while $i < 5
    echo tick $i
    set i $i + 1
endwhile

Technical note · Papyrus and the stack

Papyrus used to keep its entire editing buffer, 256 KB, on the stack. On the BIOS path the kernel's own stack is generous enough that this was invisible. On UEFI, it was a guaranteed overflow: the UEFI loader handed control to the kernel without ever setting up its own stack pointer, so the kernel simply kept running on whatever stack the firmware itself was using — and the UEFI specification only promises 128 KB of that. A 256 KB local buffer on top of it was arithmetically certain to run past the end. The fix has two halves: the loader now reserves and switches to a full 1 MB stack of its own before jumping into the kernel, and Papyrus no longer keeps its buffer on the stack at all.

Technical note · Papyrus and SuSH moved out of the kernel

Both of these tools used to live inside the kernel as ordinary ring-0 code — shell/editor.rs and shell/sush.rs, neither of which exists anymore. They are now standalone no_std ELF64 executables in userland/papyrus/ and userland/sush/, embedded into the kernel at compile time and loaded as real ring-3 processes (see the Userspace section above). The shell command papyrus file.txt no longer calls editor code directly — it maps a one-page argument buffer, hands the file path to it through enter_ring3's single u64 argument, and the editor reads the file with SYS_READFILE, draws to the screen with SYS_PUT_ROW_STR/SYS_CLEAR_ROW, and saves with SYS_WRITEFILE. SuSH is the same: every line that is not a built-in of the interpreter goes to the kernel through SYS_RUN_LINE, so the interpreter no longer reimplements any shell command itself. The cost is documented and accepted: ring-3 code cannot execute hlt, so both programs poll the keyboard queue in a tight loop instead of parking — full CPU while they wait for a key.

Technical note · the mouse, and a framebuffer to draw a cursor on

The audit added a PS/2 mouse driver (drivers/mouse.rs) alongside the keyboard, speaking the same controller's aux channel. Movement and buttons come off the IRQ as a small packet and are exposed to the kernel as a single MouseEvent. There is a cursor — but no classic-VGA cursor was possible here: the text-mode VGA window at 0xB8000 that the BIOS path uses has no concept of a mouse pointer. The cursor only exists on the UEFI path, where the framebuffer driver (drivers/fb.rs) actually owns every pixel on the screen and the cursor can be drawn as a small bitmap, moved, and restored byte-for-byte underneath. That is part of why the framebuffer primitives were extended at the same time: not just a glyph rasteriser any more, but per-row and per-pixel drawing primitives the mouse cursor — and the ring-3 drawing syscalls — can build on.

Technical note · other weaknesses this audit closed

A handful of other authentication weaknesses were found and closed in the same pass. A timing oracle in the login path let an attacker tell a valid username from an invalid one purely by how long the “Login incorrect” response took to arrive. The default root account's salt was practically the same on every fresh install, because it was derived from the boot timer's tick count at install time — a value that barely varies from one boot to the next. Passwords typed into useradd, passwd, and login were being retained in plaintext in the shell's own command history. And diskread, the raw sector-read command, didn't require administrator privileges, so any logged-in user could dump the account table off the disk sector by sector regardless of their own permissions.

Separately, the audit also flagged — without yet closing — that deleting the system's last administrator account leaves it permanently locked out, with no way to recover from inside the running system.