TRADEWIND

A from-scratch operating system in RISC-V 64-bit assembly.
Every instruction from silicon to cursor is ours.

~172 KB kernel / ~40,000 lines of assembly / 0 lines of C
Explore the Vessel

Built plank by plank from the keel up

TradewindOS is a GUI-first operating system written entirely in RISC-V assembly language using the fasmg assembler. No code is borrowed, generated, or ported. When the system needs a font rasterizer, a filesystem, a cryptographic primitive, or a GPU driver, it is written from the published specification in assembly.

Everything is nautically named. The OS is a vessel, the user is the captain, programs are crew, files are cargo, workspaces are decks.

Five Layers

TradewindOS is structured in concentric layers. The innermost layer is the kernel, which handles only hardware interaction, scheduling, and system call dispatch. Everything else runs as crew members in user space.

0 The Sea Hardware: CPU, RAM, devices
1 The Slip Bootloader: stack, BSS clear, jump to kernel
2 The Hull Kernel: scheduler, syscalls, interrupts, memory pools
3 The Rigging Gangway modules: GPU, input, storage drivers
4 The Crew User programs: all tools and applications

Memory Model: Tonnage

All memory is pre-allocated at boot into nine tiered pools. No runtime allocation exists. Programs claim and release pre-allocated blocks. No heap. No fragmentation. No use-after-free.

4 KB Process stacks, small buffers
64 KB Font caches, VirtIO queues
1 MB Large data buffers
4 MB Framebuffer regions
16 MB GPU backing memory
64 MB Chart filesystem
256 MB Large allocations (16+ GB systems)
1 GB Reserved for 16+ GB systems
4 GB Reserved for 64+ GB systems

Every System From Scratch

Everything below was written from scratch in RISC-V assembly. No libraries, no reference implementations adapted. Every line understood, every instruction justified.

Keel — Font Rasterizer
Complete TrueType outline rasterizer. Build-time TTF parsing, boot-time Bezier flattening, 8x vertical antialiasing, alpha-blended rendering.
1,560 lines
Quarterdeck — GPU Driver
VirtIO GPU driver: resource creation, backing attachment, scanout, 2D transfer, hardware cursor, dirty-rectangle tracking.
1,840 lines
Porthole — Window Manager
WinMap per-pixel ownership, z-order, click dispatch, drag-to-move, drag-to-resize, minimize/maximize/shade, window tabs, Braun-style chrome.
4,627 lines
Chart — Filesystem
Flat item table in RAM. Decks for workspace isolation. Sealing, veiling (ChaCha20 encryption), auto-grow, atomic persistence.
1,679 lines
Cipher — Cryptography
ChaCha20 stream cipher and SHA-256 hash, both implemented from FIPS/RFC specs in assembly. Veiled items, Strongroom full-disk encryption.
822 lines
Tonnage — Allocator
Nine-tier block allocator. Pool sizes from detected RAM. Every claim returns a pre-carved block. O(1) claim and release. No fragmentation.
562 lines
Anchor — Persistence
Crash-safe filesystem persistence. Versioned on-disk format (v1-v4). Superblock-last write ordering. Strongroom encrypts every sector.
838 lines
Quill — Text Editor
Full-screen editor with text selection, mouse click-to-cursor, Shift+Arrow selection, CUA keys, multi-buffer tabs, Chart I/O.
1,767 lines
Gangway — Module System
12 ports x 8 slots jump table. Kernel and user programs call through the Gangway. Swap hardware drivers without touching callers.
442 lines
Gunwale — Navigation Bar
Top bar with zone-based hover hit testing. Brand, navigation items, minimized window titles, light/dark mode toggle.
577 lines
Fitting — Widgets
Pool-based UI widgets: Cleat (button), Pennant (label), Latch (checkbox), Taffrail (scrollbar). 128 widget slots.
1,151 lines
Manifest — Menus
Menu bar (File, Edit, View) with dropdown panels. Per-porthole registration. Click-to-open, click-to-select, click-outside-to-dismiss.
1,196 lines
Lantern — Theme System
Light/dark mode with runtime palette swap. 27-color theme tables. Toggle recolors all active portholes and redraws desktop.
201 lines
Tiller — Input Driver
VirtIO tablet device driver. Absolute-to-cursor coordinate translation. Hardware cursor via GPU resource. PLIC interrupt-driven.
791 lines
Hold — Block Storage
VirtIO MMIO legacy block driver with command queuing (5 in-flight), batched multi-sector I/O, interrupt-driven completion.
590 lines
Survey — Static Analyzer
Binary verification at boot. Checks: bounded loops, no recursion, function length, assertion density, memory bounds.
Kernel-integrated
Helm — Recovery Shell
UART console with 20+ commands. Line editing, command history, pipelines, I/O redirection. NATO phonetic flag system.
6,651 lines (with bootloader)
.draft — Image Format
Custom graphics format: 12-byte header, raw BGRX, RLE compressed, or palette+bit-packed. Transparency via color key. ~50 instruction decoder.
Native format

The Voyages

Development milestones, each building on the last. Every voyage a complete, functional checkpoint.

01 First Light Boot, UART, "hello world" Complete
02 The Hull Traps, Tonnage allocator, scheduler Complete
03 Rigging the Sails Syscalls, PMP isolation, Chart filesystem, Decks Complete
04 Taking the Helm Keyboard input, Helm shell, built-in commands Complete
05 Outfitting the Crew Process launch, pipes, text tools, I/O redirection Complete
06 Dropping Anchor VirtIO block driver, disk persistence, crash-safe writes Complete
07 Battening the Hatches ChaCha20/SHA-256 encryption, Bulkhead isolation, CUA keys Complete
08 Provisioning Quill text editor, Peer pager, I/O redirection Complete
09 Desktop Foundation VirtIO GPU framebuffer, cursor, .draft image format Complete
10 Portholes + Gunwale Window management, menus, widgets, vector font rasterizer In Progress

Nautical Dictionary

Every component, subsystem, and tool is named after nautical hardware, instruments, or maritime concepts. The metaphor is consistent throughout.

Operating System Vessel
Desktop The Deck
Window Porthole
Top Bar Gunwale
Shell Helm
File Cargo
Directory Deck
Process Crew
Process Table Roster
Pipe Line / Rig
CPU Core Strand
Driver Gangway Module
Memory Pool Tonnage
Filesystem Chart
Disk Persistence Anchor
Block Device Hold
Encryption Cipher / Strongroom
Static Analysis Survey
Text Editor Quill
File Viewer Peer
Theme Toggle Lantern
Menu Bar Manifest
Widget Fitting
Button Cleat
Font Rasterizer Keel
Scrollbar Taffrail
grep Sonar
sort Muster
wc Tally
grep -v Sieve
Settings The Binnacle
Start Menu The Compass

The Manifest

~172
KB kernel binary
~40K
lines of assembly
59
system calls
21
kernel source files
9
memory pool tiers
6
userspace tools
1
vector font rasterized at boot
0
lines of C, Rust, or Python

Follow the Build

Dispatches from the shipyard. Technical notes, design decisions, and progress updates as TradewindOS is built plank by plank.

Read the Devlog