SexOS · Developer Reference

System Developer Manual

Version: Phase 21 (Userland Handoff) · Kernel: sex-kernel v0.1.0 · Bootloader: Limine 7.13.3 · Architecture: x86_64 no_std pure Rust

Contents
  1. System Overview
  2. Repository Layout
  3. Boot Flow — Limine 7.x Protocol
  4. Kernel Init Sequence
  5. Hardware Abstraction Layer (HAL)
  6. Memory Subsystem
  7. Protection Keys (PKU / Intel MPK)
  8. Protection Domains
  9. ELF Loader
  10. Ring-3 Handoff (IRETQ)
  11. IPC System
  12. Display Server — sexdisplay
  13. Build System
  14. QEMU Testing
  15. Known Issues & Phase Status

1. System Overview

SexOS is a Single Address Space Operating System (SASOS) built entirely in Rust (no_std). All kernel and userland processes share one virtual address space. Isolation between processes is enforced by Intel Memory Protection Keys (PKU/MPK) rather than separate page tables.

Design Principles

PrincipleMechanism
Isolation without page-table switchingIntel PKU — each PD gets a unique PKEY (1–15)
Zero kernel/userland address-space boundarySingle PML4 shared by all
Lock-free IPCPer-PD atomic ring buffers (RingBuffer<MessageType, 256>)
No dynamic kernel modulesAll drivers compile into server ELFs, loaded at boot
Capability-based access controlCapabilityTable per PD, CHERI-style bounds

2. Repository Layout

microkernel/
├── kernel/          # Core microkernel (no_std, ring 0)
├── servers/         # Ring-3 server ELFs
│   ├── sexdisplay/  # Compositor & framebuffer
│   ├── sexinput/    # PS/2 + USB HID
│   ├── sexfiles/    # Virtual File System
│   └── ...
├── crates/          # Shared no_std libraries
│   ├── sex-pdx/     # PDX syscall wrappers
│   └── sex-graphics/# Drawing primitives
├── scripts/         # Build scripts
├── Makefile         # Top-level build orchestration
└── x86_64-sex.json  # Custom target specification

3. Boot Flow — Limine 7.x Protocol

  1. UEFI firmware loads Limine bootloader
  2. Limine loads the kernel ELF at the Higher-Half offset (0xFFFFFFFF80000000)
  3. Limine passes memory map, framebuffer, RSDP, and SMP info via request/response protocol
  4. Kernel entry point (_start) receives the Limine boot info struct

4. Kernel Init Sequence

  1. HHDM Setup: Map physical memory into Higher-Half Direct Mapping window
  2. GDT/IDT: Install Global Descriptor Table and Interrupt Descriptor Table
  3. APIC: Initialize Local APIC timer for preemptive scheduling
  4. PKU: Configure initial Protection Key registers (WRPKRU)
  5. Server Loading: ELF-load sexdisplay, sexinput, and other server PDs
  6. Ring-3 Transition: IRETQ to userspace with appropriate PKRU value

5. Hardware Abstraction Layer (HAL)

kernel/src/hal/
├── gdt.rs       # Global Descriptor Table
├── idt.rs       # Interrupt Descriptor Table
├── apic.rs      # Local APIC / IOAPIC
├── pci.rs       # PCI enumeration
└── pku.rs       # Protection Key manipulation

6. Memory Subsystem

7. Protection Keys (PKU / Intel MPK)

PKEY 0  — kernel + default (no restriction)
PKEY 1  — sexdisplay / framebuffer (trusted display domain)
PKEY 2+ — future userland PDs

Each page is tagged with a 4-bit PKEY in bits 62:59 of the Page Table Entry. The PKRU register controls per-key access rights for the current thread. Switching domains = a single WRPKRU instruction — zero TLB flush.

8. Protection Domains

Each PD has:

9. ELF Loader

The kernel ELF loader parses program headers, maps LOAD segments via the buddy allocator, and sets up initial capability grants for the new PD. Load phase is fully asynchronous via sys_spawn_pd.

10. Ring-3 Handoff (IRETQ)

The kernel prepares a Ring-3 stack frame with appropriate segment selectors and uses iretq to drop privilege. The PKRU register is set before the transition so the new PD wakes up with correct memory access rights.

11. IPC System

12. Display Server — sexdisplay

The sexdisplay server runs as PKEY 1 and owns the framebuffer. It implements SexCompositor, a pure PDX-native compositor that accepts window buffers via PDX calls and composites them into the scanout framebuffer.

13. Build System

CRITICAL: rust-src Requirement

SexOS requires rust-src for the nightly toolchain to rebuild core and alloc via -Z build-std.

rustup component add rust-src --toolchain nightly-x86_64-unknown-linux-gnu
# Docker build (canonical)
./scripts/clean_build.sh

# Run in QEMU
make run-sasos

# Native build (advanced)
make release

14. QEMU Testing

make run-sasos  # Requires: -cpu host,+pku for Intel PKU passthrough

Without +pku, the kernel triggers a General Protection Fault (GPF) at boot because the PDX security handshake cannot initialize.

15. Known Issues & Phase Status