Update README.md

2026-03-30 14:22:37 +03:00
parent d9e43aedbe
commit 927b0979b6
1 changed files with 136 additions and 68 deletions
--- a/README.md
+++ b/README.md
@@ -1,98 +1,166 @@
-<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>Микроядерная операционная система</b></p>
+<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>

-* `kernel/` — Исходный код ядра на.
-* `limine/` — Файлы загрузчика Limine.
-* `ovmf/` — Файлы прошивки для поддержки загрузки через UEFI.
-* `limine.conf` — Конфигурация меню загрузки.
-* `GNUmakefile` — Основной сценарий сборки и запуска.
+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 |

-| Инструмент | Описание |
-| :--- | :--- |
-| **GNU Make** | Утилита для сборки (`make`). |
-| **Rust** | Nightly версия, включая `rust-src`. |
-| **xorriso** | Необходим для создания загрузочных ISO-образов. |
-| **sgdisk & mtools** | Необходимы для создания образов жесткого диска (HDD/USB). |
-| **QEMU** | Эмулятор для тестирования ядра. |
+## 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 |

-* **Склонируйте репозиторий**
-    ```bash
-    git clone https://git.inotfail.com/INotFail/Elyz.git
-    cd elyz
-    ```
+**Installing dependencies:**

-* **Сборка ядра**
-    ```bash
-  cd kernel
-  make all
-  cd ../
-    ```
+**Ubuntu/Debian:**
+```bash
+sudo apt install make rustc xorriso gdisk mtools qemu-system-x86
+rustup toolchain install nightly --component rust-src
+```

-* **Запуск (основные способы)**
-    ```bash
-    make run-bios
-    ```
-    или
-    ```bash
-    make run
-    ```
-    или
-    ```bash
-    make run-uefi
-    ```
+**Arch Linux:**
+```bash
+sudo pacman -S make rust xorriso gdisk mtools qemu-desktop
+rustup toolchain install nightly --component rust-src
+```

+## Building and Running

-`make all` скомпилирует ядро (из kernel/), а затем сгенерирует загрузочный ISO-образ. 
+### Preparation
+```bash
+git clone https://git.inotfail.com/INotFail/Elyz.git
+cd Elyz
+rustup override set nightly
+```

-`make run` соберет ядро и загрузочный ISO-образ (эквивалент команды make all), а затем запустит его с помощью команды qemu (если установлено). 
+### Main Makefile Targets

-`make all-hdd` скомпилирует ядро, а затем сгенерирует исходный образ, подходящий для записи на USB-накопитель или жесткий диск/SSD. 
+| 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 | — |

-`make run-hdd` соберет ядро и необработанный образ жесткого диска (эквивалентно созданию образа для всех жестких дисков), а затем запустит его с помощью qemu (если установлено). 
+**Run examples:**
+```bash
+# BIOS with auto-build
+make run

-`run-uefi` и `run-hdd-uefi` цели эквивалентны своим нецелевым `-uefi` аналогам, за исключением того, что они загружаются `qemu` с использованием прошивки, совместимой с UEFI. 
+# UEFI mode
+make run-uefi

+# USB/HDD image
+make all-hdd
+```

-## 🏗 Поддерживаемые архитектуры
+## Supported Architectures

-Переменная `KARCH` определяет целевую архитектуру. По умолчанию используется `x86_64`.
+The `KARCH` environment variable sets the target architecture (default: `x86_64`).

-Вы можете изменить архитектуру при вызове `make`:
+| 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
 ```

-**Доступные варианты:**
-* `x86_64` (Default)
-* `aarch64`
-* `riscv64`
-* `loongarch64`
+> For non-x86_64 architectures, `kernel/rust-toolchain.toml` setup is required.

-> Для архитектур, отличных от x86, потребуется настройка соответствующих целевых платформ в `kernel/rust-toolchain.toml`.
+## 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 |

-* **Очистка проекта:** Чтобы удалить все артефакты сборки и скомпилированные файлы, выполните:
-    ```bash
-    make clean
-    ```
-* **Логи:** Ядро выводит данные в консоль QEMU.
+## Memory System Development Status

-## 🔗 Ccылки
+| 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 scheduler |
+| **Memory syscalls** | ⏳ Not Started | allocate/clone/transfer |
+| **Weak references** | ⏳ Not Started | borrow/release |
+| **Process auto-cleanup** | ⏳ Not Started | On exit |

- Репозиторий: https://git.inotfail.com/INotFail/Elyz
- Трекер задач: https://git.inotfail.com/INotFail/Elyz/issues
- Связанные проекты:
-  - Оригинальный шаблон с загрузчиком: https://github.com/jasondyoungberg/limine-rust-template
+## Development Plan (TODO)

-## 📔 Лицензия
+### Detailed Task List

-Код данного проекта распространяется по лицензии Apache-2.0.
+| # | 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
+```
+
+## Kernel Architecture