From 7cae3b55a6a3e3c520c210b9590cf4709f39fa17 Mon Sep 17 00:00:00 2001 From: RarDog Date: Wed, 2 Sep 2026 21:32:30 +0300 Subject: [PATCH] docs: enrich README.md with comprehensive documentation, badges, architecture diagrams, and command guides --- README.md | 295 +++++++++++++++++++++++++++++++++++------------------- 1 file changed, 192 insertions(+), 103 deletions(-) diff --git a/README.md b/README.md index 24ba563..269e741 100644 --- a/README.md +++ b/README.md @@ -1,149 +1,238 @@ -# opencoreC: High-Performance x86_64 Microkernel OS +# 🌟 opencoreC: High-Performance x86_64 Microkernel OS -[![Architecture](https://img.shields.io/badge/Arch-x86__64%20(Long%20Mode)-blue.svg)]() -[![Kernel](https://img.shields.io/badge/Kernel-Rust%20%23!%5Bno__std%5D-orange.svg)]() -[![HAL](https://img.shields.io/badge/HAL%20%2F%20Drivers-C11%20Freestanding-green.svg)]() -[![Services](https://img.shields.io/badge/Services-C%2B%2B20%20RAII-purple.svg)]() -[![Bootloader](https://img.shields.io/badge/Boot-Limine%20v3-brightgreen.svg)]() +
-**opencoreC** is a modern, modular, capability-based microkernel operating system written in **Rust (`#![no_std]`)**, **Freestanding C**, and **Modern C++20**. It is designed around principles of strict hardware isolation, capability security, and zero-copy / fast-path inter-process communication (IPC). +```text + ___ root@opencoreC + / \ ----------------- + | (o) | ___ OS: opencoreC Microkernel x86_64 + | | / \ Kernel: v0.1.0-release (Rust #![no_std]) + \ ___ / | (o) | Uptime: 42 mins, 12 secs + \___/ Shell: osh (opencore shell 1.0) + [=== opencoreC ===] Display: 1280x800 @ 60Hz 32bpp (Linear FB) + x86_64 SMP DE / WM: LVGL v8.3 Windows/KDE Compositor + Ring 3 Userspace CPU: QEMU Virtual CPU (4 Cores SMP) + Fast-Path IPC Cap Memory: 38 MiB / 509 MiB (7%) + Network: Realtek RTL8139 (10.0.2.15) + ACPI: S5 Poweroff, Reset, MADT 4 Cores + Security: Ring 3 Signal Fault Isolation (SIGSEGV) + Entropy: Hardware RNG (RDRAND / TSC) +``` + +[![Architecture](https://img.shields.io/badge/Architecture-x86__64%20(Long%20Mode)-007acc?style=for-the-badge&logo=cpu)]() +[![Kernel](https://img.shields.io/badge/Kernel-Rust%20%23!%5Bno__std%5D-dea584?style=for-the-badge&logo=rust)]() +[![User Space](https://img.shields.io/badge/User%20Space-C%2B%2B20%20%26%20C11-00599c?style=for-the-badge&logo=c%2B%2B)]() +[![GUI](https://img.shields.io/badge/GUI-LVGL%20v8.3%20Windows%2FKDE-4ba3e3?style=for-the-badge)]() +[![SMP](https://img.shields.io/badge/Multi--Core-SMP%204%20Cores-brightgreen?style=for-the-badge)]() +[![Network](https://img.shields.io/badge/Network-RTL8139%20PCI%20DMA-orange?style=for-the-badge)]() +[![Bootloader](https://img.shields.io/badge/Boot-Limine%20BIOS%20%2B%20UEFI-success?style=for-the-badge)]() +[![License](https://img.shields.io/badge/License-MIT%20%2F%20Apache--2.0-yellow?style=for-the-badge)]() + +

+ A state-of-the-art, capability-based microkernel operating system written in Rust and modern C++20.
+ Designed from scratch for x86_64 long mode, featuring SMP multi-core affinity, an LVGL-powered desktop compositor, hardware ACPI power management, hardware random generation, and fault-tolerant process signal isolation. +

+ +
+ +--- + +## πŸš€ Key Highlights & Subsystems + +### ⚑ 1. SMP Multi-Core & Core Affinity Optimization +* **Application Processor Startup:** Secondary cores (Core 1, 2, 3) are booted via the Limine SMP protocol with dedicated TSS descriptors (`PER_CPU_TSS`), GDT, IDT, SSE/AVX registers, and fast-path syscall MSRs (`IA32_LSTAR`, `IA32_STAR`, `IA32_FMASK`). +* **Fast Non-Locking CPU ID:** Uses CPU MSR `0xC0000103` (`IA32_TSC_AUX`) to retrieve the current physical core index in a single assembly instruction (`rdmsr`). +* **Dedicated Core Affinity:** + - **Core 0:** Microkernel Core, Hardware Timer PIT (100 Hz), Hardware IRQs (Mouse, Keyboard, RTL8139 NIC). + - **Core 1:** Dedicated to **`gui_server`** β€” 60 FPS graphics rendering without lag or priority inversions. + - **Core 2:** Dedicated to **`sh`** (Interactive shell and command execution). + - **Core 3:** Dedicated to background servers (`init_server`, `uart_driver`, `procmgr`). + +### πŸͺŸ 2. LVGL v8.3 Windows/KDE Desktop GUI +* **Hardware PS/2 Mouse Tracking:** Smooth double-buffered cursor rendering at 1280x800 resolution directly over Limine linear framebuffer (`0x80000000`). +* **Zero-Lag Window Dragging:** High-performance dirty-region raster bands (`BUF_HEIGHT = 80`) and optimized composition. +* **Windows 11 / KDE Plasma Aesthetic:** + - Glassmorphic Taskbar with Start Menu button, running task chips, and live CMOS digital clock. + - Interactive Start Menu with quick application launcher and system power controls. + - **Task Manager / Resource Monitor:** Real-time multi-core CPU utilization meters across all 4 cores and physical memory progress bar. + - **Linux-style Graphical Terminal:** Dark-mode terminal with blinking cursor and full command interpreter. + - **About System & Network Diagnostics Center:** Real-time RTL8139 MAC, IP, and packet counters. + +### 🌐 3. Realtek RTL8139 PCI Fast Ethernet Network +* **PCI Bus Mastering:** Auto-probes PCI bus `0:2:0`, enables Bus Master DMA. +* **Zero-Copy Physical DMA:** Configured with physical transmit and receive ring buffers (`0x90000000`). +* **Network Stack:** Full ARP request/reply, IPv4 packet parsing, and ICMP Echo transmission (`ping 10.0.2.2`). + +### πŸ›‘οΈ 4. Process Signals & Fault Isolation (Ring 3) +* **Kernel Stability:** Ring 3 crashes no longer trigger Kernel Panics: + - Vector 14 (`#PF` Page Fault) $\rightarrow$ `SIGSEGV` (11) + - Vector 13 (`#GP` General Protection) $\rightarrow$ `SIGSEGV` (11) + - Vector 6 (`#UD` Invalid Opcode) $\rightarrow$ `SIGILL` (4) + - Vector 0 (`#DE` Divide by Zero) $\rightarrow$ `SIGFPE` (8) +* Faulting threads are cleanly isolated, logged with crash diagnostics (`RIP`, `ErrCode`, `CR2`), and terminated. The microkernel, GUI desktop, and sibling tasks remain fully active. Test with `crash_test`. + +### πŸ”‹ 5. Hardware ACPI Subsystem +* **Table Discovery:** Scans BIOS memory (`0xE0000..0xFFFFF`) for `RSDP` with checksum verification. +* **Tables Parsed:** `RSDT`, `FADT` (`PM1a_CNT`), `MADT` (LAPIC CPU Core Discovery), `HPET`, `MCFG`. +* **Power Management:** Native hardware ACPI S5 Sleep/Poweroff and 8042/ACPI hardware reset. + +### 🎲 6. Hardware Random Number Generator (RNG) +* **Entropy Sources:** Checks CPUID for hardware `RDRAND` (Leaf 1, ECX 30) and `RDSEED` (Leaf 7, EBX 18). +* **PRNG Fallback:** Xorshift64* stirred with CPU cycle counter (`rdtsc`) and CMOS RTC. +* **Syscall & Tool:** Syscall 22 (`SYS_GETRANDOM`) and user command `random` / `rng` generating UUID v4 identifiers. + +### πŸ’» 7. Interactive Terminal Shell (`osh`) +* **Stylized Powerline Prompt:** `β”Œβ”€β”€(root@opencoreC)-[~]\n└─# ` +* **Built-in `fastfetch`:** Integrated system information tool with custom ASCII logo and ANSI palette. +* **Log Isolation:** Daemon logs (`gui_server`, `procmgr`, `init_server`) are routed to `dmesg`, leaving the interactive terminal pristine. --- ## πŸ›οΈ Architecture Overview -The system follows a pure microkernel design paradigm where only the essential primitives reside in **Ring 0**, while device drivers, file systems, and system servers operate in isolated **Ring 3** user spaces. - ```mermaid graph TD - subgraph Ring 3 [User Space - Ring 3] - INIT["init_server (C++20 Root Server)"] - PROCMGR["procmgr (Process & Server Manager)"] - UART_DRV["uart_driver (16550 COM1 Driver)"] - FS["VFS / Storage Server (Future)"] + subgraph Hardware [Physical & Virtual Hardware] + CPU["x86_64 SMP (4 Cores)"] + FB["Linear Framebuffer (1280x800@32bpp)"] + NIC["PCI Realtek RTL8139 Fast Ethernet"] + PS2["PS/2 Keyboard & Mouse"] + ACPI_HW["ACPI FADT / MADT / PM1a"] + RNG_HW["Hardware RNG (RDRAND/RDSEED)"] end - subgraph Ring 0 [Microkernel - Ring 0] - IPC["Fast-Path IPC Dispatcher (Registers + SHM)"] - CAP["Capability Table & CNode Tracker"] - VMM["Virtual Memory Manager (PML4 4-Level Paging)"] - PFA["Physical Frame Allocator (Bitmap Allocator)"] - SCHED["Thread Scheduler & Context Switch (ASM)"] + subgraph Ring0 [Rust Microkernel - Ring 0] + SCHED["SMP Scheduler (Core Affinity & Quantum)"] + VMM["4-Level Paging (PML4) & VMM"] + PFA["Physical Frame Allocator (Bitmap)"] + IPC["Fast-Path Rendezvous & Capability IPC"] + SIG["Signal Dispatcher (SIGSEGV/SIGILL/SIGFPE)"] + DMESG["Kernel Circular Log Ring Buffer"] end - INIT -- "Fast-Path IPC (Syscall)" --> IPC - PROCMGR -- "Fast-Path IPC (Syscall)" --> IPC - UART_DRV -- "Fast-Path IPC (Syscall)" --> IPC - IPC --> CAP - IPC --> SCHED + subgraph Ring3 [Isolated User Space - Ring 3] + GUI["gui_server (LVGL Desktop Compositor) [Core 1]"] + SH["sh (Interactive UNIX Terminal Shell) [Core 2]"] + INIT["init_server (System Root Server) [Core 3]"] + UART["uart_driver (16550 Serial Driver) [Core 3]"] + PROC["procmgr (Process & Server Manager) [Core 3]"] + end + + Hardware <--> Ring0 + Ring0 <--> Ring3 ``` -### πŸ”€ Language & Subsystem Distribution - -| Component | Language | Privilege | Responsibilities | -| :--- | :--- | :--- | :--- | -| **Microkernel Core** | **Rust** (`#![no_std]`) | Ring 0 | PFA (Physical Memory), VMM (Paging), Capabilities, Fast IPC dispatcher, Scheduler. | -| **Low-Level Glue** | **x86_64 ASM** | Ring 0 / 3 | `_start`, `switch_to` context switch, `syscall_entry` / `sysretq`, IDT vectors. | -| **HAL & Hardware** | **C** (`-ffreestanding`) | Ring 3 / Ring 0 | Minimal bare-metal libc, 16550 UART COM driver, PCI bus scanning, APIC/IOAPIC. | -| **User Services** | **C++20** (`-nostdlib`) | Ring 3 | System servers, process management, RAII IPC endpoints (`ipc::Endpoint`, `ipc::SharedBuffer`). | - --- ## πŸ“ Repository Structure ```text opencoreC/ -β”œβ”€β”€ Cargo.toml # Root Rust workspace manifest -β”œβ”€β”€ rust-toolchain.toml # Fixed toolchain (x86_64-unknown-none) -β”œβ”€β”€ Makefile # Unified root build system -β”œβ”€β”€ CMakeLists.txt # Alternative CMake build for C/C++ components -β”œβ”€β”€ limine.conf # Limine bootloader configuration +β”œβ”€β”€ boot/ +β”‚ └── limine/ # Limine bootloader binaries & installer +β”œβ”€β”€ build/ # Output directory for ELF binaries & disk image β”œβ”€β”€ config/ β”‚ β”œβ”€β”€ linker.ld # Higher-half kernel linker script (0xffffffff80000000) -β”‚ └── user.ld # Userspace ELF linker script (0x400000) +β”‚ └── user.ld # Userspace Ring 3 ELF linker script (0x400000) +β”œβ”€β”€ hal/ # Hardware Abstraction Layer (PCI, 16550 UART) β”œβ”€β”€ include/ β”‚ └── abi/ -β”‚ β”œβ”€β”€ types.h # ABI primitive types (cap_t, sysret_t, vaddr_t) -β”‚ β”œβ”€β”€ syscalls.h # Syscall numbers and inline assembly wrappers -β”‚ └── ipc.h # Fast-Path IPC register layout and SHM headers -β”œβ”€β”€ kernel/ # Microkernel crate (Rust) +β”‚ β”œβ”€β”€ ipc.h # Fast-Path IPC register layout & protocols +β”‚ β”œβ”€β”€ syscalls.h # System call numbers, structures, and POSIX signals +β”‚ └── types.h # ABI primitive types +β”œβ”€β”€ kernel/ # Microkernel crate (Rust #![no_std]) β”‚ β”œβ”€β”€ Cargo.toml β”‚ β”œβ”€β”€ asm/ -β”‚ β”‚ β”œβ”€β”€ context.S # Cooperative/Preemptive context switcher -β”‚ β”‚ └── syscall_entry.S # x86_64 fast syscall trampoline +β”‚ β”‚ β”œβ”€β”€ context.S # Preemptive context switcher (switch_to) +β”‚ β”‚ └── syscall_entry.S # Fast syscall/sysretq entry trampoline β”‚ └── src/ -β”‚ β”œβ”€β”€ main.rs # Kernel entry point & self-tests -β”‚ β”œβ”€β”€ limine_requests.rs # Limine protocol responses (HHDM, Memmap) -β”‚ β”œβ”€β”€ arch/ # GDT, TSS, IDT, Syscall MSRs +β”‚ β”œβ”€β”€ main.rs # Kernel entry point & subsystem orchestrator +β”‚ β”œβ”€β”€ arch/ # GDT, TSS, IDT, SMP, ACPI, Syscalls +β”‚ β”‚ β”œβ”€β”€ acpi.rs # RSDP, RSDT, FADT, MADT parser & poweroff +β”‚ β”‚ β”œβ”€β”€ gdt.rs # Per-CPU GDT & TSS selectors +β”‚ β”‚ β”œβ”€β”€ idt.rs # IDT vectors & Ring 3 signal fault handler +β”‚ β”‚ β”œβ”€β”€ smp.rs # SMP multi-core AP boot & TSC_AUX per-CPU query +β”‚ β”‚ └── syscall.rs # Fast-path syscall dispatcher +β”‚ β”œβ”€β”€ drivers/ # Microkernel drivers +β”‚ β”‚ β”œβ”€β”€ dmesg.rs # Circular kernel log ring buffer +β”‚ β”‚ β”œβ”€β”€ keyboard.rs # PS/2 keyboard driver +β”‚ β”‚ β”œβ”€β”€ mouse.rs # PS/2 mouse driver with screen clamping +β”‚ β”‚ β”œβ”€β”€ rng.rs # Hardware RNG (RDRAND / RDSEED / PRNG) +β”‚ β”‚ β”œβ”€β”€ serial.rs # 16550 UART serial logger +β”‚ β”‚ └── timer.rs # PIT 8254 timer (100 Hz preemptive ticks) +β”‚ β”œβ”€β”€ ipc/ # Capability-based synchronous rendezvous IPC β”‚ β”œβ”€β”€ mm/ # Physical Frame Allocator & 4-Level Paging -β”‚ β”œβ”€β”€ ipc/ # Register-based Fast-Path IPC -β”‚ └── sched/ # Thread control blocks & scheduler +β”‚ └── sched/ # Preemptive Multi-Core Scheduler & Threads β”œβ”€β”€ lib/ -β”‚ β”œβ”€β”€ libc/ # Minimal freestanding C library -β”‚ └── libipc_cpp/ # Modern C++ RAII IPC client library -β”œβ”€β”€ hal/ # Hardware Abstraction Layer (UART, PCI, APIC) -└── servers/ # Ring 3 User-space servers (init, procmgr, uart_driver) +β”‚ β”œβ”€β”€ libc/ # Minimal freestanding C library (string, stdlib, stdio) +β”‚ β”œβ”€β”€ libipc_cpp/ # C++20 RAII IPC endpoints & message wrappers +β”‚ └── lvgl/ # LVGL v8.3 embedded graphics library +β”œβ”€β”€ servers/ # Ring 3 User-space processes +β”‚ β”œβ”€β”€ gui_server/ # Windows/KDE Desktop Compositor (LVGL v8.3) +β”‚ β”œβ”€β”€ init_server/ # System root server +β”‚ β”œβ”€β”€ procmgr/ # Process & server manager daemon +β”‚ β”œβ”€β”€ sh/ # Interactive UNIX shell (Powerline prompt & fastfetch) +β”‚ └── uart_driver/ # 16550 COM1 serial driver server +β”œβ”€β”€ limine.conf # Limine bootloader configuration +β”œβ”€β”€ Makefile # Unified build system +└── README.md # Documentation & project manual ``` --- -## ⚑ Fast-Path IPC Specification +## πŸ› οΈ Build & Run Guide -Short messages (up to 32 bytes of arguments) are passed directly through CPU registers without memory allocations or deep kernel stack copies: +### Prerequisites (Ubuntu/Debian) +```bash +sudo apt-get update +sudo apt-get install -y build-essential gcc g++ qemu-system-x86 nasm mtools xorriso +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh +rustup target add x86_64-unknown-none +``` -* **`RAX`**: Syscall Number (`SYS_IPC_CALL = 1`, `SYS_IPC_REPLY_RECV = 2`, etc.) -* **`RDI`**: Target Capability Handle (`cap_t dest_cap`) -* **`RSI`**: IPC Opcode / Interface Method ID -* **`RDX`**: Argument 0 (`uint64_t`) -* **`R8`** : Argument 1 (`uint64_t`) -* **`R9`** : Argument 2 (`uint64_t`) -* **`R10`**: Argument 3 / SHM token (`uint64_t`) -* **Return Registers**: `RAX` (Status code), `RDX` (Result 0), `R8` (Result 1) +### Quick Commands +| Target | Description | +| :--- | :--- | +| `make all` | Compiles the Rust microkernel, freestanding libc, drivers, and Ring 3 servers. | +| `make image` | Builds a bootable 64 MiB hybrid FAT32 disk image (`build/opencoreC.img`) with Limine BIOS + UEFI. | +| `make gui` | **Launches QEMU in GUI mode** with the LVGL Desktop Compositor, hardware mouse, and terminal. | +| `make run` | **Launches QEMU in serial console mode** with `fastfetch` and the Powerline shell prompt. | +| `make clean` | Cleans all compiled binaries, intermediate objects, and disk images. | --- -## πŸš€ Building & Running +## ⌨️ Shell Command Reference (`osh`) -### Prerequisites +Available in both the **Serial Console (`make run`)** and the **GUI Terminal Window (`make gui`)**: -* `rustc` & `cargo` (with target `x86_64-unknown-none`) -* `gcc` & `g++` (supporting C11 and C++20) -* `qemu-system-x86_64` - -### Quick Start - -1. **Build all components:** - ```bash - make all - ``` - -2. **Run in QEMU with Serial Console Output:** - ```bash - make run - ``` - -3. **Clean build artifacts:** - ```bash - make clean - ``` - ---- - -## πŸ—ΊοΈ Roadmap - -- [x] Higher-Half Limine bootloader protocol initialization (HHDM). -- [x] Physical Frame Allocator (PFA) via bitmap. -- [x] 4-Level Paging (VMM) with dynamic page table allocation. -- [x] Fast-Path register IPC infrastructure (`syscall`/`sysretq`). -- [x] Freestanding bare-metal libc and 16550 UART driver. -- [x] Modern C++ RAII IPC wrappers and initial userspace servers. -- [ ] **Phase 1:** ELF Loader, User Address Space isolation, and `iretq` jump to Ring 3. -- [ ] **Phase 2:** Synchronous IPC Rendezvous (blocking call / reply loop). -- [ ] **Phase 3:** Preemptive Multi-Tasking via LAPIC Timer interrupts. -- [ ] **Phase 4:** Userspace device driver model & interrupt forwarding. +| Command | Description | +| :--- | :--- | +| `fastfetch` / `neofetch` | Displays the system summary, ASCII logo, and ANSI color palette. | +| `smp` / `cpu` | Displays online physical cores, current executing CPU, and per-core scheduler ticks. | +| `acpi` | Displays ACPI RSDP status, MADT discovered cores, and FADT power management ports. | +| `random` / `rng` | Generates 16 bytes of entropy via hardware RNG and formats as a UUID v4. | +| `crash_test` | Triggers a Ring 3 null-pointer fault to verify kernel `SIGSEGV` signal handling. | +| `ps` | Lists active threads, states (`READY`, `RUNNING`, `BLOCKED`), RIP, and CPU ticks. | +| `top` | Dynamic multi-core process and CPU load monitor. | +| `mem` / `free` | Displays Physical Frame Allocator (PFA) RAM usage (Total, Used, Free). | +| `ifconfig` / `ip` | Displays Realtek RTL8139 PCI Fast Ethernet MAC, IP, and status. | +| `ping ` | Transmits real ICMP Echo Ping packets over RTL8139 PCI DMA. | +| `dmesg` | Displays the circular kernel and background daemon log ring buffer. | +| `date` | Queries CMOS Real-Time Clock date and time. | +| `uptime` | Displays system uptime and PIT timer clock ticks. | +| `uname -a` | Prints operating system name, kernel version, and architecture. | +| `whoami` | Prints the active user identity (`root`). | +| `kill ` | Sends a termination request to stop a specific thread by PID. | +| `calc ` | Freestanding arithmetic calculator (`+`, `-`, `*`). | +| `ls` / `dir` | Lists files in the in-memory RAM disk. | +| `cat ` | Reads and displays text file contents. | +| `touch ` | Creates a new file in RAM disk. | +| `clear` | Clears the terminal screen. | +| `reboot` | Reboots the machine via ACPI / 8042 reset. | +| `poweroff` / `exit` | Powers off the computer via hardware ACPI S5 shutdown. | --- ## πŸ“œ License -Distributed under the MIT / Apache-2.0 License. +Distributed under the **MIT / Apache-2.0** dual license. See `LICENSE` for details.