Valecium OS Documentation

Welcome to the Valecium OS project! This documentation provides everything you need to understand, build, develop, and use Valecium OS.

Valecium OS is a Unix-like, multi-architecture operating system kernel designed with clean architecture, modularity, and educational value in mind. Whether you’re a curious learner, a systems developer, or someone interested in OS internals, this documentation will guide you through the project.

Quick Start

Want to build the project? → See Building the Project
Want to contribute code? → See Developer Guide
Want to try running it? → See Usage Guides
Curious about the architecture? → See Kernel Documentation
Know about the boot process? → See Bootloader Documentation

Project Overview

Valecium OS is built with the following principles:

Multi-architecture support — Designed from the ground up to support multiple CPU architectures (i686, x86_64, ARM64, etc.). Currently i686 is fully implemented; other architectures are in planning.
Clean separation of concerns — Hardware abstraction layer (HAL) isolates platform-specific code behind function-pointer operation tables
Modular design — Each subsystem (memory, filesystem, drivers) is self-contained
Well-documented — Code and systems are documented for learning purposes
Custom bootloader — A two-stage BIOS real-mode → protected mode bootloader is under development alongside GRUB support

Current State (v0.28)

The i686 BIOS path is the most mature. The kernel boots, initializes memory management (PMM, VMM, heap), sets up interrupt handling (GDT, IDT, ISR, IRQ), mounts a FAT12/16/32 root filesystem, and launches userspace processes (selftest, shell). The syscall layer supports file I/O, process creation (fork/execve), memory management (brk/sbrk), and process signaling (partial). The custom bootloader’s stage1 (MBR) and stage2 (protected mode entry) exist but do not yet load the kernel.

Documentation Files

For Developers and Contributors

These documents cover everything needed to participate in Valecium OS development:

devel.ad — Coding standards, naming conventions, assembly strategy, and git workflow
kernel/index.ad — Deep dives into kernel subsystems, memory management, scheduling, and device drivers
bootloader/index.ad — Understand how does the legacy BIOS and new UEFI boot works
roadmap.ad — Planned features, known limitations, and architectural goals

New contributors should start with devel.ad to understand the project’s coding standards and build system.

For Users and Testers

Want to try Valecium OS or understand how to use it?

building.ad — Step-by-step instructions for compiling the kernel and userland
usage/index.ad — How to boot, interact with, and test Valecium OS

For Userspace Developers

Building applications or utilities for Valecium OS?

usr/index.ad — System calls, libc functions, and standard library APIs

Quick Reference

Topic	Document
Code style & conventions	devel.ad
Memory management	kernel/mem.ad
Building from source	building.ad
Running on QEMU	usage/index.ad
Contributing patches	devel.ad
Supported architectures	kernel/arch.ad
BIOS and EFI boot	bootloader/index.ad
Syscall reference	kernel/syscall.ad
Filesystem stack	kernel/fs.ad
Crypto subsystem	kernel/index.ad

Topic

Document

Code style & conventions

Memory management

Building from source

Running on QEMU

Contributing patches

Supported architectures

BIOS and EFI boot

Syscall reference

Filesystem stack

Crypto subsystem

Getting Help

Found a bug? → Open an issue on GitHub
Have a question? → Check devel.ad or search existing documentation
Documentation out of sync with code? → Please submit a pull request with fixes
Want to contribute? → See the Contributing section in devel.ad