BoubisOS

A hybrid kernel / microkernel-inspired hobby operating system for x86-64, written in C17 and NASM assembly. Named after my dog Boubis.

BoubisOS includes its own bootloader, kernel, IPC-based userspace servers, filesystems, display server, networking (E1000), USB stack, web browser, and Doom.

Architecture

┌─────────────────────────────────────────────┐
│              Applications                   │
│  shell, browser, editor, doom, tcc, ...    │
├─────────────────────────────────────────────┤
│            libc / libwindow                 │
├─────────────────────────────────────────────┤
│          Userspace Servers                  │
│  VFS │ Display │ Shell │ Filesystems        │
├─────────────────────────────────────────────┤
│                    IPC                      │
├─────────────────────────────────────────────┤
│               Kernel                        │
│  Scheduler │ Memory │ Syscalls │ IPC │ ...  │
├─────────────────────────────────────────────┤
│              Hardware                       │
└─────────────────────────────────────────────┘

See docs/ARCHITECTURE.md for details.

Building

Prerequisites

• x86_64-linux-gnu-gcc — cross-compiler
• nasm — assembler
• python3 — image generation tools
• make or mingw32-make — build system
• qemu-system-x86_64 — emulator (for testing)

Build

Run once (before first build):

./userspace/tcc-boubis/patch.sh

Build everything:

make all

Outputs:

• build/bios.img — bootable disk image
• build/bfs.img — BoubisOS filesystem image

Run

Graphical QEMU:

make run

Headless QEMU (serial output only):

make run-nographic

QEMU Configuration

• Memory: 512 MB
• NIC: e1000 (user-mode networking)
• USB: UHCI controller + keyboard + mouse
• Serial: stdio
• Storage: IDE + AHCI with 3 BFS images

Directory Structure

bootloader/          # Stage1 (MBR) + Stage2 (long mode setup)
kernel/              # Kernel source
  arch/amd64/        # Architecture-specific code
    gdt/             # Global Descriptor Table
    interrupts/      # IDT, PIC, ISR stubs
    sched/           # Context switch assembly
    syscall/         # Syscall entry assembly
  core/              # Scheduler, IPC, serial
  memory/            # PMM, VMM, heap
include/             # Public kernel headers
includesrc/          # Minimal stdint/stddef
libc/                # Userspace C library
libwindow/           # Windowing library
servers/             # Userspace servers
  display/           # Display server
  vfs/               # VFS + filesystems (BFS, RAMFS)
userspace/           # Userspace programs and drivers
  programs/          # shell, browser, editor, doom, tcc, ...
  drivers/           # e1000, pci, timer, storage
  usb/               # USB stack (EHCI, UHCI, HID, MSC)
  doom-boubis/       # Doom port
  tcc-boubis/        # Tiny C Compiler integration
tools/               # Python build tools
tests/               # Host-side unit tests
docs/                # Documentation

Syscalls

See docs/SYSCALLS.md.

Quick Reference

#	Name	Description
0	SYS_PUTC	Write character
1	SYS_IPC	IPC service
4	SYS_WRITE	Write buffer
5	SYS_YIELD	Yield CPU
6	SYS_EXIT	Exit task
7	SYS_TASK_LAUNCH	Launch from ramdisk
8	SYS_TASK_RUN	Run binary
11	SYS_TASK_WAIT	Wait for task
12	SYS_GET_TICKS	Get tick count

IPC

All userspace services communicate via IPC. See docs/ARCHITECTURE.md.

Special Ports

Port	Purpose
6	VFS server
7	Serial output
8	PCI driver
9	Timer
11	RAM filesystem
13	VFS-to-filesystem routing

Filesystem

See docs/VFS.md.

Mounted Filesystems

• RAM:\ — RAM filesystem (default)
• BFS: — BoubisOS filesystem (image-based)

Documentation

• docs/ARCHITECTURE.md — System architecture
• docs/MEMORY_LAYOUT.md — Memory map
• docs/SYSCALLS.md — Syscall reference
• docs/VFS.md — VFS protocol
• docs/ENGINEERING_BASELINE.md — Baseline report
• docs/SECURITY.md — Security audit

Testing

Host-side unit tests:

cd tests
make test

Tests cover:

• Path normalization and traversal safety
• Browser URL parsing and entity decoding
• Safe string helpers
• VFS mount port encoding

License

MIT — see LICENSE.