XerisOS
Documentation

Architecture reference

How the system is laid out, what each layer owns, and the constraints that shaped it.

Overview

XerisOS is a 64-bit operating system for x86-64 machines. It is not a Linux distribution and does not embed a Linux kernel. The bootloader, kernel, drivers, filesystem, window system and applications are written for this system, and the compatibility it offers to Linux software is provided at the syscall boundary rather than by reusing any Linux code.

The design goal is narrow and testable: run software people actually use, on hardware people actually own, without a layer in between that can observe them.

Boot and recovery

Firmware loads BOOTX64.EFI from the EFI system partition. The loader collects the UEFI memory map and graphics mode, reads the kernel image, and exits boot services before handing over.

A/B slots

A BOOTSLOT record on the volume names the active slot and carries a trial counter. A slot installed as a trial must confirm a successful boot; if it does not, the counter runs out and the loader falls back to the previous slot. An update that fails to boot costs a reboot rather than a recovery USB.

Memory model

The kernel is identity-mapped. User address space is split into fixed windows — program image, interpreter, break, and a large demand-paged region for anonymous mappings.

  • Demand paging. Anonymous mappings return address space immediately and are backed by physical frames only when touched, which is what allows the multi-terabyte sparse reservations modern allocators make.
  • Alignment matters. Allocators such as PartitionAlloc map a pointer back to its pool by masking, so a pool has to be aligned to its own size. Reservations are aligned to their natural size for this reason.
  • Protection shadowing. PROT_NONE guard regions are tracked so that pointer validation and guard-page probes behave as software expects.

Syscall layer

Linux binaries enter through syscall and are dispatched by number. The implemented surface covers process and thread lifecycle, memory, files, sockets, polling, signals, time, and the shared-memory and descriptor-passing primitives a modern browser depends on.

clone / futex          threads, and blocking between them
mmap / mremap          demand-paged anonymous and file mappings
memfd_create           anonymous shared memory by descriptor
sendmsg  SCM_RIGHTS    passing descriptors across a socket
epoll_*                readiness for pipes, sockets, eventfd
openat / statx         the FAT volume, presented as a POSIX tree

Where a call cannot be implemented honestly, it fails honestly. Silently returning success for something that did not happen is treated as a defect, because it converts a clear error into a corruption several layers away.

Compositor

The Wayland compositor runs inside the kernel. Clients bind wl_compositor, wl_shm and xdg_shell, attach a shared-memory buffer, and commit. The compositor reads that buffer directly — there is no copy through a socket and no display-server process.

Input flows the other way: pointer motion, buttons, axis (scroll) events with source and discrete steps, and keyboard events carrying an xkb keymap. Damage is tracked per commit so only changed rows reach the framebuffer.

Storage and filesystem

FAT32 and FAT16 are supported. The mount order is USB, then NVMe, then IDE, so one image boots from a stick or an internal disk without reconfiguration.

  • Contiguous-run reads. The chain walker coalesces sequential clusters into a single command and reads straight into the caller's buffer, rather than one command per cluster through a bounce.
  • Write ordering. A new chain is allocated and the directory entry repointed before the old chain is freed, so a failure mid-write cannot leave an entry aliasing free clusters.
  • Bounded walks. Every chain traversal is bounded by the cluster count and rejects out-of-range clusters, so a malformed volume cannot spin the kernel.

Multiprocessing

Secondary cores are started through the APIC. The desktop is reserved to the boot processor while application threads run on the others, so the UI keeps repainting while a heavy page loads. A leaf spinlock protects the page tables, and a TLB generation counter keeps mappings coherent across cores without cross-processor interrupts.

Building

The tree builds with an x86_64-elf cross toolchain and NASM. Output is a kernel binary plus the UEFI loader; a run target stages both onto a FAT directory for testing, and a USB target stages the same files onto a stick.

make            build the kernel and loader
make run        boot it under emulation
make run-usb    stage a bootable USB layout

Known limits

Stated plainly, because a launch page that only lists strengths is not much use to an engineer:

  • Graphics are software-composited. There is no GPU acceleration path yet, so the browser rasterises on the CPU.
  • Hardware support is broad but specific — the drivers listed are the drivers that exist.
  • The filesystem is FAT. It is universally readable and simple to recover, but it is not journaled.
  • The syscall surface targets the software we test against. Anything outside it fails cleanly rather than pretending.