boredos_mirror/docs

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.

Table of Contents

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.
• Interrupts & Exceptions: IDT, GDT, and exception handling.

Memory

• Memory (PMM/VMM): Physical Memory Management and Virtual Memory Management.
• Memory Manager: Slab allocator and block allocator for kernel heap.

Storage & Filesystems

• Filesystem: Virtual File System (VFS) and the RAM-based FAT32 simulation.
• 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

• Window Manager: Compositor, events, and overlapping windows.
• Rendering: Framebuffer, font rendering, and image loading.

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.
• UI API: Drawing on the screen, creating windows, and polling the event loop using libui.h.
• Widget API: High-level UI components like buttons, textboxes, and scrollbars using libwidget.h.
• Custom Apps: A step-by-step tutorial on writing a new graphical C application, editing the Makefile, and bundling it into the ISO.
• ELF App Metadata: How to declare app icons and descriptions using source annotations, how the build system embeds them into .note.boredos.app ELF sections, and how the kernel reads them at runtime.
• Example Apps: A collection of sample C applications ranging from basic terminal output to advanced TCP networking.
• Grapher: Full reference for the built-in mathematical graphing application — equation syntax, keyboard controls, architecture, and configuration.
• Native TCC: How to use the Tiny C Compiler (TCC) to build and run C applications directly on BoredOS.

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.
• Desktop: Window management, shortcuts, and desktop interaction.
• Lumos: Using the system-wide search (Shift + Ctrl + Space).
• Terminal: Command line interface, redirection, and common commands.
• Launching Apps: Ways to launch files and applications, plus a software overview.

---