<h1 align="center">
  <img width="512" src="https://git.inotfail.com/ami-chuu/Elyz/raw/commit/3831cfd967afb60efe108a7579a767ec2309631b/logo.png" alt="Elyz">
</h1>

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

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:**
```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) | BIOS 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