Elyz/README.md

<h1 align="center">
  <img width="512" src="./logo.png" alt="Elyz">
</h1>

<p align="center">
  <b>H2O</b>
</p>

**Elyz is a microkernel OS** that radically rejects the technological deadwood of the past. While traditional systems are hamstrung by decades of legacy code, Elyz is built on a foundation of uncompromising modernity.

We implement technologies that others can't afford. This isn't an attempt to fix the old, but to create a flexible and secure environment, building a proper OS from scratch, capable of instantly adapting to the challenges of tomorrow.

## Project Structure

| Directory/File | Description                            |
| -------------- | -------------------------------------- |
| `kernel/`      | Kernel source code                     |
| `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:**

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

**Arch Linux:**

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

## Building and Running

### Preparation

```bash
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:**

```bash
# 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:**

```bash
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 | Initial physical frame management |
| Page Tables (x86_64) | ✅ Done | 4-level paging, HHDM support |
| Kernel Heap | ✅ Done | Slab Allocator (8MB) |
| Framebuffer/Console | ✅ Done | Graphical output with font rendering |
| PMActor Subsystem | ✅ Done | Distributed memory ownership model |
| PMRouter | ✅ Done | Lock-free MPSC response routing |
| Capability Model | ✅ Done | Base `CNode` & `Capability` primitives |

## Memory System Development Status

| Task | Status | Note |
| --- | --- | --- |
| **Basic Initialization** | ✅ Ready | Boot, MMU, IDT, PMM |
| **Buddy Allocator** | ✅ Ready | Efficient per-actor memory carving |
| **Async PM Messaging** | ✅ Ready | Actor-based allocation requests |
| **Lock-free Routing** | ✅ Ready | Zero-copy response dispatching |
| **Descriptor Model** | ⏳ In Progress | `MemoryObject` & refcounting logic |
| **Process Isolation** | ⏳ Not Started | Address space cloning/switching |
| **Memory Syscalls** | ⏳ Not Started | `allocate`, `transfer`, `grant` |
| **Weak References** | ⏳ Not Started | `borrow`/`release` for capabilities |

## Development Plan (TODO)

| # | Task | Subtasks | Priority | Dependencies |
| --- | --- | --- | --- | --- |
| 1 | **Capabilities System** |  | High | PMActor |
|  |  | 1.1. Capability refcounting |  |  |
|  |  | 1.2. Inter-process delegation |  |  |
| 2 | **Process Management** |  | High | Capabilities |
|  |  | 2.1. PCB & Context switching |  |  |
|  |  | 2.2. Address Space isolation |  |  |
|  |  | 2.3. Auto-cleanup on exit |  |  |
| 3 | **Syscalls API** |  | Medium | Processes |
|  |  | 3.1. `transfer(desc, target)` |  |  |
|  |  | 3.2. `mint(desc)` (delegation) |  |  |
| 4 | **Advanced MMU** |  | Medium | Syscalls |
|  |  | 4.1. Lazy paging / Copy-on-Write |  |  |
|  |  | 4.2. TLB Shootdown (SMP support) |  |  |
| 5 | **Security/Hardening** |  | Low | All above |
|  |  | 5.1. Circular ref detection |  |  |
|  |  | 5.2. Capability revocation depth |  |  |

## Debugging

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

**Useful QEMU options:**

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

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

**Cleanup:**

```bash
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