BoredOS Documentation

Internal guides, architecture, and application development.

Welcome to the documentation for BoredOS! This directory contains detailed guides on how the OS functions, how to build it, and how to develop applications for it.

The documentation is organized into three main categories:

1. Architecture

Explains the logical layout of the kernel and internal components.

System

Core: Kernel source layout and the boot process (Limine, Multiboot2).
Processes & Scheduling: Multitasking, context switching, and ELF loading.
TTY & Virtual Terminals: 10 virtual consoles, virtual framebuffers, active blitting, and keyboard/mouse multiplexing.
Interrupts & Exceptions: IDT, GDT, and exception handling.

Memory

Memory Architecture: PMM frame allocator, MMU paging, VMA tracking, and demand paging in the VMM.
Slab Allocator: Object caches and general heap allocation (kmalloc/kfree).
Page Cache: Page cache, radix tree indexing, and dirty page writeback.

Storage & Filesystems

Filesystem & VFS: VFS layer, tmpfs, FAT32, ext4, and background sync.
AHCI Drivers: Hardware communication for block storage devices.

Network

Network Stack: TCP/IP implementation and socket APIs.
Network Drivers: Hardware interaction for network cards (e.g. e1000).

Graphics

Framebuffer Device: Direct physical screen memory access, Linux-compatible /dev/fb0 ioctls, seeking, and memory mapping (mmap).

Hardware

PCI: PCI bus enumeration and device binding.
Input: PS/2 Keyboard and Mouse input handling.

Misc

Versioning: The OS date-based version scheme (YY.M[.x]) and kernel semantic versioning (MAJOR.MINOR.PATCH).

2. Building and Deployment

Instructions for compiling the OS from source.

Toolchain: Prerequisites and cross-compiler setup (x86_64-elf-gcc, nasm, xorriso).
Usage: Understanding the Makefile targets, QEMU emulation, and flashing to bare metal hardware.

3. Application Development

The SDK and toolchain guides for creating your own .elf userland binaries.

SDK Reference: Overview hub for SDK layout, includes, and links to detailed libc/syscall docs.
Syscalls: Current syscall numbers, FS/SYSTEM command IDs, and wrapper guidance.
libc Reference: Current libc headers, implemented APIs, and behavior notes.
Raw Graphics Guide: Developer guide to raw /dev/fb0 drawing, screen layout queries, ioctls, memory mapping (mmap), and safe TTY mode restoration.
Custom Apps: A step-by-step tutorial on writing a new C application, editing the Makefile, and compiling/bundling it into the ISO.
Example Apps: A collection of sample C applications ranging from basic terminal output to advanced direct framebuffer access and TCP networking.
Native TCC: How to use the Tiny C Compiler (TCC) to build and run C applications directly on BoredOS.
Nova Protocol: Detailed wire protocol formats and event layouts for the desktop compositor.
Developing Nova Clients: Guide for building applications using the low-level Nova compositor socket interface.
Nova ToolKit (NTK): Official widget toolkit for developing graphical applications with decorations and layouts.

4. Usage

General guides on how to interact with the OS.

Booting: How to use the Limine bootloader and toggle kernel boot flags like -v.
Terminal: Command line interface, redirection, and common commands.