Skip to content

rou2exOS Documentation

A second iteration of a DOS-inspired hobby OS. Written in Rust and x86 assembly. It boots, runs, executes, schedules, renders and does networking.

Check it out on GitHub!

Where to Start

If you want to… Read
Build or boot the system Build and Run
Use the text-mode rescue shell Kernel Shell
Use the desktop or install updates Memento, Jug
Write a program SDK Overview, C, C++, Go, TCC on r2
Publish programs to Jug Publishing Jug Programs
Call the kernel directly ABI Specification, Type Definitions
Understand or debug the kernel Kernel Internals

System at a Glance

memento-welcome

Fig. 1: The initial screen of the MEMENTO GUI experiment. The screen is shown right after the boot (if configured in the init script so). That "thing" on the right is the mouse cursor ready to be moved by a PS/2 mouse.

memento-desktop

Fig 2: The Desktop window showing a variety of some "programs" available to run in MEMENTO.

memento-login

Fig. 3: External userspace program demo called MEMENTO.ELF. Login window in the foreground, a wallpaper in the background.

memento-clock

Fig. 4: The Clock window in the MEMENTO GUI experiment.

Userland programs are static ELF64 binaries. Each one runs in ring 3 in its own private 2 MiB frame mapped at 0x600_000 and calls into the kernel via interrupt 0x7F. Programs can be written in C, C++ or Go (TinyGo) using the libraries of the SDK.

kernel-shell-init

Fig. 5: Kernel shell init. The verbose output is generated by just-started external applications. The INIT.RC script file is parsed and executed by the shell command interpreter.

It boots via GRUB/Multiboot2, runs in 64-bit long mode with a custom identity-mapped page table, and exposes a kernel shell backed by a preemptive round-robin scheduler running at 1000 Hz.

The kernel speaks directly to the hardware:

  • ISA DMA for floppy I/O (FAT12, read/write, with a track cache),
  • ATAPI PIO for CD-ROM (ISO9660, read-only; carries the shipped programs in /bin),
  • an RTL8139 or supported Intel NIC for Ethernet, with TCP/IP stacks in userland,
  • a VESA framebuffer or VGA text mode for output, plus VGA mode 13h for userland,
  • a PS/2 keyboard and mouse,
  • the PC speaker (tones and Standard MIDI Files), and HD Audio for stereo PCM.

The current tree supports 32 scheduler slots, a shared user heap that grows past its initial 4 MiB, and a writable RAM disk. GRUB also loads a boot archive so programs remain available when booted from USB. The graphics kernel starts Memento as its supervised desktop; Jug can update and relaunch it without rebooting. WireGuard supplies an optional userland IPv4 tunnel, and network monitoring reports NIC totals and TCP port owners.

Releases

Download r2.iso and, when supplied, the optional fat.img from a release. The ISO carries the kernel, programs and boot archive; the floppy supplies writable configuration and data. Release images can lag behind the behavior documented for the current source tree.

Please consult the Build & Run page to see options on how to run the system in QEMU locally.

qemu-system-x86_64 -boot d -cdrom r2.iso -fda fat.img

Repositories

Blog posts

Note: Some portions of this documentation have been generated from the original source code by AI.