<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 | 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)

### Detailed Task List

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