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

---

## 🏛️ 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)"]
    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)"]
    end

    INIT -- "Fast-Path IPC (Syscall)" --> IPC
    PROCMGR -- "Fast-Path IPC (Syscall)" --> IPC
    UART_DRV -- "Fast-Path IPC (Syscall)" --> IPC
    IPC --> CAP
    IPC --> SCHED
```

### 🔀 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
├── config/
│   ├── linker.ld                    # Higher-half kernel linker script (0xffffffff80000000)
│   └── user.ld                      # Userspace ELF linker script (0x400000)
├── 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)
│   ├── Cargo.toml
│   ├── asm/
│   │   ├── context.S                # Cooperative/Preemptive context switcher
│   │   └── syscall_entry.S          # x86_64 fast syscall trampoline
│   └── src/
│       ├── main.rs                  # Kernel entry point & self-tests
│       ├── limine_requests.rs       # Limine protocol responses (HHDM, Memmap)
│       ├── arch/                    # GDT, TSS, IDT, Syscall MSRs
│       ├── mm/                      # Physical Frame Allocator & 4-Level Paging
│       ├── ipc/                     # Register-based Fast-Path IPC
│       └── sched/                   # Thread control blocks & scheduler
├── 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)
```

---

## ⚡ Fast-Path IPC Specification

Short messages (up to 32 bytes of arguments) are passed directly through CPU registers without memory allocations or deep kernel stack copies:

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

---

## 🚀 Building & Running

### Prerequisites

* `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.

---

## 📜 License

Distributed under the MIT / Apache-2.0 License.