The purpose of this "wiki", web documentation, guide, however you call it, is to use it as a
personal memory aid
for kernel development.
It doesn't have to be an ultra-aesthetic page, but I'm trying hard so it doesn't show that I made it
with vanilla html, css and js like some amateur project
that's out there.
A minimally functional operating system kernel (all the Kernel Space plus a minimal user space)
can easily run in 15,000 lines of code, so as you'll see;
it's humanly impossible to memorize and understand the entire kernel flow by myself. Besides, there
are many complex subsystems working together at a low level to mediate between hardware and
software.
This calculation is automatic and is done through an API that counts the number of lines of code in the kernel (.c, .h, .asm, .rs, and .cpp)
This deserves a star on the repo
IR0 is a multipurpose operating system kernel developed
from scratch for the x86-64 architecture, written in C,
C++,
Rust, and ASM. The kernel core is in C, device drivers in Rust
(for memory safety), and advanced components like schedulers in C++ (for templates and RAII).
I'm creating it to learn more about operating systems and be able to use it as raw material
for another project that replicates WSL2 but with my own kernel.
I don't rule out scaling it enough to make it usable in minimal servers or even IoT,
but I understand that's in the very long term.
This
is its GitHub Repository.
Discord
community
Version: v0.0.1 pre-release candidate 1
Architecture: x86-64 (primary), x86-32 (experimental), ARM (in development)
Bootloader: GRUB
License: GNU GPL v3.0
Type: Monolithic Modular Kernel
ASM Syntax: Intel (NASM)
Unlike kernels such as Microsoft's NT kernel (Hybrid), Redox-OS
(Microkernel),
or the same MINIX kernel (microkernel), IR0 is based on a more similar
architecture
to what Linux has, which is monolithic.
However, my main argument is that of performance. I understand that someone could come and
point out that, like any monolith, if a subcomponent breaks, the entire system crashes (and
they would be right)
but what I respond to that is "What good does it do me that the kernel supports continuing
without
filesystem if I can't do anything practical without it?", that is, it doesn't make sense
that the
kernel
continues functioning without one of its key components running.
That's why I don't see a better alternative (for now) than the monolithic pattern. And it also saves me from having to
interconnect
key subsystems with each other via IPC, which impacts performance of the Operating System. It's not
perfect, but it's stable. It's not entirely traceable and requires scaling little by little, but if
it scales well it performs a lot.
However, I also have disagreements with the UNIX philosophy. They (among other things and very briefly)
consider
that if something fails, let it fail well. Which in kernel terms would be: If the
scheduler breaks, Panic() directly. If you have memory corruption (in kernel space),
Panic.
And it's not that I question it for no reason, I simply ask (although without solutions yet) "Why
not rescue the system during Panic()?, or at least try".
Beyond the philosophical point and to summarize, the kernel is monolithic because it's more
performant and
I feel that the key pieces of the kernel must work without overhead.
However, if in the future I needed to integrate some specific subsystem in a hybrid way,
I would surely be pragmatic.
I know I talk as if IR0 were used by thousands of people and all the history, but I'm going to give
myself the luxury of opining
about it.
So, the point is that kernel space has to be only habitable by subsystems
that work in that Environment,
nothing else.
I understand that there are certain manufacturers concerned about their clients'
security who,
coincidentally, have access to every interruption that the user makes (they know what keys you
press,
your session time every time you turn on the computer, etc.) And all that because they have
software running in the kernel space with all the privileges that implies.
RING 0 is only for the kernel. Everything that comes from RING 3
communicates with syscalls(), end of statement.
For IR0 to work as support for basic servers and IoT applications, I need
fundamental network support but without the massive complexity of Linux's complete
stack.
In the Linux Kernel there are more or less 1,500,000 lines of code ONLY THE COMPLETE
NETWORK STACK. Instead of trying to port all of that, I've decided to use a more
pragmatic approach:
Custom lightweight stack (planned):
How the file structure can change constantly, I prefer you consult it in the GitHub Repository.
- Main branch with stable and tested code.
- Active development branch where new features are implemented and tested.
- I add it because it's the branch where feats are created that later go to upstream merging to dev. It's the most unstable of all because it's where new code is integrated that must also be tested and reviewed before reaching merge.
- In this branch, features are integrated unstable enough to end up in mainline but that may have potential in the future.
Version: v0.0.01 pre-release candidate 1
Architecture: x86-64 (primary), x86-32 (experimental), ARM (in development)
License: GNU GPL v3.0
Type: Monolithic Modular Kernel
SYS_EXIT(0) - Process termination SYS_WRITE(1) - Write to file descriptor SYS_READ(2) - Read from file descriptor SYS_GETPID(3) - Get process ID SYS_GETPPID(4) - Get parent process ID SYS_LS(5) - List directory contents SYS_MKDIR(6) - Create directory SYS_PS(7) - Show process list SYS_WRITE_FILE(8) - Write file to filesystem SYS_CAT(9) - Display file contents SYS_TOUCH(10) - Create empty file SYS_RM(11) - Remove file SYS_FORK(12) - Create child process SYS_WAITPID(13) - Wait for child process SYS_RMDIR(40) - Remove directory SYS_MALLOC_TEST(50) - Memory allocation test SYS_BRK(51) - Change heap break SYS_SBRK(52) - Increment heap break SYS_MMAP(53) - Memory mapping SYS_MUNMAP(54) - Unmap memory SYS_MPROTECT(55) - Change memory protection SYS_EXEC(56) - Execute program
Status: There is no network connectivity yet; groundwork is in progress to code the entire stack ourselves.
Kernel Space: 0x100000 - 0x800000 (1MB-8MB) Heap Space: 0x800000 - 0x2000000 (8MB-32MB, 24MB total) User Space: 0x40000000+ (1GB+)
print(), write(), etc. because there's no operating system that
responds to those functions . You are the
operating system. that's why, in the repo I have the folder of dependencies "includes".
snake_case()UPPER_CASEstruct_name_tg_variable_nameCONSTANT_NAME#INCLUDE -ir0/Lib.h - (are being migrated to that format)We try to follow the Linux kernel coding style, but with some specific adaptations for this project. These are desirable conventions, not strict rules (except for the brace style).
/* ... */ over single-line
//.
if statements should not use braces.
goto for cleanup logic when multiple exit
points share the same cleanup code./*
* Example of a function following IR0 conventions
* Note the Allman style braces and multi-line comments
*/
int process_data(struct data_t *data)
{
if (!data)
return -1; /* Single line if without braces */
char *buffer = kmalloc(1024);
if (!buffer)
{
/*
* Braces are used here because the block
* contains multiple lines or is complex
*/
return -ENOMEM;
}
if (prepare_buffer(buffer) < 0)
goto cleanup; /* Use goto for error handling/cleanup */
/* ... processing logic ... */
kfree(buffer);
return 0;
cleanup:
kfree(buffer);
return -1;
}
Header files should contain function prototypes, struct definitions, and detailed documentation in comments.
#ifndef _IR0_EXAMPLE_H
#define _IR0_EXAMPLE_H
/*
* struct example_t - Represents an example structure
* @id: Unique identifier
* @value: Associated value
*/
typedef struct
{
int id;
int value;
} example_t;
/*
* process_example - Processes the example structure
* @ex: Pointer to the structure
* Returns: 0 on success, negative error code on failure
*/
int process_example(example_t *ex);
#endif
IMPORTANT: Before compiling, it's recommended to verify that all dependencies are correctly installed:
make deptest
This command will verify the presence of all necessary tools:
The script automatically detects your platform and provides specific installation instructions if any tool is missing.
IR0 now supports development in three languages:
# Install Rust curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh # Add required components rustup component add rust-src rustup target add x86_64-unknown-none # Verify installation rustc --version cargo --version
# Debian/Ubuntu sudo apt-get install g++ # Arch Linux sudo pacman -S gcc # Verify installation g++ --version
# Debian/Ubuntu sudo apt-get install build-essential nasm qemu-system-x86 grub-pc-bin python3 # Arch Linux sudo pacman -S base-devel nasm qemu grub python
| Command | Description |
|---|---|
make ir0 |
Complete build: kernel ISO + userspace programs |
make kernel-x64.bin |
Build only the kernel binary |
make kernel-x64.iso |
Create bootable ISO image |
make userspace-programs |
Build only userspace programs |
make clean |
Clean all build artifacts |
make userspace-clean |
Clean only userspace programs |
| Command | Description |
|---|---|
make run |
Run with GUI + virtual disk (recommended) |
make run-debug |
Run with GUI + serial debug output |
make debug |
Run with detailed QEMU logging |
make run-nodisk |
Run without virtual disk |
make run-console |
Run in console mode (no GUI) |
QEMU Configuration:
-no-reboot -no-shutdownqemu_debug.log| Command | Description |
|---|---|
make create-disk |
Create virtual disk image (disk.img) |
make delete-disk |
Delete virtual disk image |
Disk specifications:
scripts/create_disk.sh| Command | Description |
|---|---|
make deptest |
Verify all system dependencies |
make help |
Show complete Makefile help |
make menuconfig |
Launch kernel configuration (ncurses) |
make unibuild FILE=<file> |
Compile individual file |
unibuild System - Multi-Language Compilation:
The unibuild system now supports compiling files in C, C++, and Rust with specific flags:
# Compile C files (default) make unibuild FILE=kernel/memory/kmalloc.c # Compile C++ files make unibuild -cpp FILE=kernel/scheduler/advanced_sched.cpp # Compile Rust drivers make unibuild -rust FILE=drivers/network/rtl8139.rs # Cross-compile to Windows (from Linux) make unibuild -win FILE=kernel/file.c make unibuild -win -cpp FILE=kernel/component.cpp make unibuild -win -rust FILE=drivers/driver.rs # Compile multiple files make unibuild FILES="fs/ramfs.c fs/vfs.c"
Available flags:
-cpp - Use C++ compiler (g++)-rust - Use Rust compiler (rustc)-win - Cross-compile to Windows using MinGW-w64Flags can be combined for different use cases (e.g., -win -cpp to cross-compile C++ to
Windows).
make deptestmake ir0make create-disk (first time)make runmake run-debug
- This section details the main subsystems that compose the IR0 kernel,
their current development status and technical characteristics of each one.
The best way to understand the internal operation is by reviewing the source code in the
GitHub Repository.
The scheduler is the heart of the multiprocessing system. Currently implements a simple Round-Robin algorithm as fallback, but the goal is to migrate to a preemptive scheduler with priority scheme similar to Linux's CFS (Completely Fair Scheduler).
Files: scheduler/scheduler.c, scheduler/task.h, scheduler/switch/switch.asm
Own filesystem based on EXT2 but with modern innovations. The distinctive feature is the integration of a vectorial database to optimize file search and indexing operations.
Status: Active development
Files: fs/ext2.c, fs/victor_index.c, fs/journal.c
Robust interrupt and exception handling system that ensures kernel stability and provides a clean interface for handling hardware and software events.
Files: interrupt/idt.c, interrupt/interrupt.asm, interrupt/isr_handlers.c, interrupt/irq.c
Initialization system that prepares the environment for kernel execution, handling the transition from bootloader to user space.
Files: boot/boot.asm, boot/kmain.c, boot/arch.c, boot/kernel_start.c
Advanced memory management system that provides process isolation, performance optimization and protection against unauthorized access.
Files: mm/page_alloc.c, mm/slab.c, mm/vmalloc.c, mm/protection.c
We are drafting a custom TCP/IP stack written 100% by us, without importing Linux code or external libraries. The focus is on a maintainable, well-understood implementation tailored to IR0.
Status: Research/design phase (no borrowed Linux subsystems).
Modular framework for hardware driver development and management, with support for hot-plugging and automatic device management.
Files: drivers/core.c, drivers/block/, drivers/char/, drivers/net/
Comprehensive security framework that protects the kernel and user processes, implementing multiple layers of protection and security auditing.
Files: security/capability.c, security/seccomp.c, security/lsm/, security/audit.c
Advanced power management system that optimizes battery consumption in mobile devices and reduces energy consumption in servers while maintaining performance.
Files: power/suspend.c, power/cpuidle.c, power/thermal.c, power/battery.c
Virtualization support is a long-term research item aimed at running alternate OS instances for lab work. Containerization is not on the roadmap for IR0.
Status: Concept stage; no containers and no running VMs yet.
Complete monitoring and debugging system that provides deep visibility into kernel operation and enables real-time problem diagnosis.
Files: kernel/trace/, kernel/debug/, kernel/profiling/, kernel/bpf/
Hardware description system that allows the kernel to automatically discover and configure hardware devices without needing hardcoded specific drivers.
Files: drivers/of/, drivers/acpi/, drivers/firmware/
Graphics subsystem that provides hardware acceleration, multi-monitor support and advanced multimedia capabilities.
Files: drivers/gpu/drm/, drivers/media/, drivers/video/
Advanced audio system that provides support for multiple formats, real-time audio processing and management of complex audio devices.
Files: sound/core/, sound/soc/, sound/pci/, sound/usb/
Unified input and output system that handles all user interface devices, from keyboards and mice to touchscreens and sensors.
Files: drivers/input/, drivers/hid/, drivers/iio/