H2O

Elyz is a microkernel operating system written in Rust. The project uses the Limine bootloader and supports multiple architectures. The current implementation includes basic kernel initialization, physical memory management, paging, and graphical output via framebuffer.

Project Structure

Directory/File	Description
kernel/	Kernel source code (Rust)
limine/	Limine bootloader
ovmf/	UEFI firmware for emulation
limine.conf	Boot menu configuration
GNUmakefile	Main Makefile for building and running

System Requirements

Tool	Version/Requirements	Purpose
GNU Make	≥ 4.0	Project building
Rust	Nightly with rust-src	Kernel compilation
xorriso	Any	ISO image creation
sgdisk	Any	Disk image creation
mtools	Any	Disk image handling
QEMU	≥ 6.0	Emulation

Installing dependencies:

Ubuntu/Debian:

sudo apt install make rustc xorriso gdisk mtools qemu-system-x86
rustup toolchain install nightly --component rust-src

Arch Linux:

sudo pacman -S make rust xorriso gdisk mtools qemu-desktop
rustup toolchain install nightly --component rust-src

Building and Running

Preparation

git clone https://git.inotfail.com/INotFail/Elyz.git
cd Elyz
rustup override set nightly

Main Makefile Targets

Target	Description	Result
make all	Kernel compilation + ISO creation	Elyz.iso
make run	Full build + QEMU launch (BIOS)	UEFI emulation
make run-bios	Run existing image (BIOS)	BIOS emulation
make run-uefi	Full build + QEMU launch (UEFI)	UEFI emulation
make all-hdd	Compilation + HDD/USB image	Elyz.hdd
make run-hdd	Build HDD + QEMU launch	HDD emulation
make clean	Clean build artifacts	—

Run examples:

# BIOS with auto-build
make run

# UEFI mode
make run-uefi

# USB/HDD image
make all-hdd

Supported Architectures

The KARCH environment variable sets the target architecture (default: x86_64).

Architecture	KARCH value	Status
x86_64	x86_64	Full support
AArch64	aarch64	Experimental
RISC-V 64	riscv64	Experimental
LoongArch 64	loongarch64	Experimental

Running other architecture:

make run KARCH=aarch64

For non-x86_64 architectures, kernel/rust-toolchain.toml setup is required.

Current Functionality

Component	Status	Description
Limine Bootloader	✅ Done	BIOS/UEFI support
Physical MM (Bitmap)	✅ Done	Page bitmap
Page Tables (x86_64)	✅ Done	4-level addressing
Global Allocator	✅ Done	Bump allocator (8MB)
Framebuffer	✅ Done	Graphical output
Console	✅ Done	Text output with scrolling

Memory System Development Status

Task	Status	Note
Basic initialization	✅ Ready	Limine, MMU, PMM
Physical allocator	✅ Ready	BitmapPMM working
Paging	✅ Ready	P4->P1 mapping
Global heap	✅ Ready	8MB bump allocator
Descriptor memory model	⏳ Not Started	Planned
Processes and spaces	⏳ Not Started	No IPC
Memory syscalls	⏳ Not Started	allocate/clone/transfer
Weak references	⏳ Not Started	borrow/release
Process auto-cleanup	⏳ Not Started	On exit

Development Plan (TODO)

#	Task	Subtasks	Priority	Dependencies
1	Descriptor memory model		High	PMM, VMM
		1.1. MemoryObject structure
		1.2. Descriptor table per process
		1.3. Refcounting (strong/weak)
		1.4. Syscalls: allocate, clone
2	Processes		High	Descriptors
		2.1. PCB structure
		2.2. Descriptor Table per process
		2.3. Auto-cleanup on exit
3	Syscalls API		Medium	Processes
		3.1. transfer(desc, target)
		3.2. borrow(desc, duration)
		3.3. release(desc)
4	MMU Integration		Medium	Syscalls
		4.1. Page table per process
		4.2. Mapping by descriptors
		4.3. Unmapping on release
5	Circular references		Low	All above

Debugging

Logs are output to QEMU console. Panic output via serial port (COM1).

Useful QEMU options:

# Serial port for logs
make run QEMU_FLAGS="-serial stdio"

# GDB debugging
make run QEMU_FLAGS="-s -S"

Cleanup:

make clean    # Remove all artifacts
make distclean # + git clean

Links

• Original Repository: https://git.inotfail.com/INotFail/Elyz

• Related projects:

• Original template with bootloader: https://github.com/jasondyoungberg/limine-rust-template