|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +Serix is a hybrid-kernel x86_64 operating system written in Rust (`#![no_std]`, nightly toolchain). It boots via the Limine v10.x bootloader and uses capability-based security. Currently at v0.0.6, Phase 4 development (FAT32 filesystem). |
| 8 | + |
| 9 | +## Build Commands |
| 10 | + |
| 11 | +```bash |
| 12 | +cargo build --release # Build kernel only |
| 13 | +cargo build -p <crate> --release # Build a specific crate |
| 14 | +make init # Build userspace init binary (required before iso) |
| 15 | +make iso # Build bootable ISO (kernel + init + Limine) |
| 16 | +make run # Build everything and run in QEMU |
| 17 | +make clean && cargo clean # Remove all build artifacts |
| 18 | +cargo fmt # Format (tabs, 100-char width) |
| 19 | +cargo clippy # Lint |
| 20 | +``` |
| 21 | + |
| 22 | +No automated test suite exists. Validate by booting in QEMU (`make run`) and checking serial output + framebuffer. |
| 23 | + |
| 24 | +**QEMU debug flags**: `qemu-system-x86_64 ... -d int,cpu_reset -no-reboot` to catch triple faults. |
| 25 | + |
| 26 | +## Architecture |
| 27 | + |
| 28 | +### Workspace Structure |
| 29 | + |
| 30 | +Cargo workspace with 16 member crates. `.cargo/config.toml` sets `x86_64-unknown-none` as default target and enables `build-std` — no `--target` flag needed. |
| 31 | + |
| 32 | +Key crates: `kernel/` (entry, GDT, syscalls), `memory/` (paging, heap, frame allocator), `hal/` (serial, CPU, I/O ports), `apic/` (LAPIC, I/O APIC, timer), `idt/` (exception handlers), `graphics/` (framebuffer console), `task/` (async executor, scheduler), `capability/` (security), `drivers/` (VirtIO, PCI), `vfs/` (ramdisk), `ipc/` (port-based messaging), `loader/` (ELF loader), `ulib/` (userspace syscall wrappers), `keyboard/` (PS/2 driver). |
| 33 | + |
| 34 | +Internal crate dependencies use `{ path = "../crate_name" }`. |
| 35 | + |
| 36 | +### Memory Layout |
| 37 | + |
| 38 | +- **HHDM**: All physical RAM mapped at `0xFFFF_8000_0000_0000` — always use `HHDM_REQ.get_response()` for offset, never hardcode |
| 39 | +- **Kernel heap**: `0xFFFF_8000_4444_0000` (1 MB, configured in `memory/src/heap.rs`) |
| 40 | +- **Userspace**: Lower half, entry at `0x200000` (via `user.ld` linker script) |
| 41 | + |
| 42 | +### Boot Flow (kernel/src/main.rs `_start`) |
| 43 | + |
| 44 | +Serial init → disable PIC/enable APIC → load IDT → enable interrupts/start LAPIC timer → process Limine responses → init page tables from CR3 → init heap → init graphics → init VFS → load init binary → idle loop. |
| 45 | + |
| 46 | +**Critical ordering**: heap must exist before any allocations; IDT must be loaded before enabling interrupts. |
| 47 | + |
| 48 | +### Interrupt Vectors |
| 49 | + |
| 50 | +0-31: CPU exceptions, 32: PIT (disabled), 33: PS/2 keyboard, 49: LAPIC timer (~625 Hz). All handlers must signal EOI to APIC. |
| 51 | + |
| 52 | +### Syscall Interface |
| 53 | + |
| 54 | +Linux-style ABI via `SYSCALL`/`SYSRET`. RAX=number, RDI/RSI/RDX/R10/R8/R9=args. Dispatch in `kernel/src/syscall.rs`, wrappers in `ulib/src/lib.rs`. Syscalls: READ(0), WRITE(1), SEND(20), RECV(21), YIELD(24), EXIT(60). |
| 55 | + |
| 56 | +### Task/Scheduler Model |
| 57 | + |
| 58 | +`TaskCB` stores state + stack pointer. `Scheduler` with `RunQueue` (round-robin). `AsyncTask` with `Future` trait. Context switch via assembly in `task/` crate (callee-saved GPRs + CR3 swap). |
| 59 | + |
| 60 | +## Code Conventions |
| 61 | + |
| 62 | +- **Tabs, not spaces** (`hard_tabs = true`, `tab_spaces = 8`, `max_width = 100`) |
| 63 | +- **C-style block comments** for function headers: `/* function_name - description */` |
| 64 | +- **Global state pattern**: `static INSTANCE: Once<Mutex<Type>> = Once::new()` |
| 65 | +- **Debug output**: `serial_println!` (kernel), `fb_println!` (framebuffer) |
| 66 | +- **Address types**: Use `x86_64::PhysAddr` and `x86_64::VirtAddr`, not raw integers |
| 67 | +- **Syscall naming**: prefix with `serix_` (e.g., `serix_write`) |
| 68 | +- **Handler naming**: suffix with `_handler` (e.g., `timer_interrupt_handler`) |
| 69 | +- **Commit format**: `<type>(<scope>): <subject>` — types: feat/fix/docs/style/refactor/perf/test/build/ci/chore, scopes: crate names |
| 70 | + |
| 71 | +## Documentation |
| 72 | + |
| 73 | +Each subsystem crate has its own `README.md`. Technical docs in `docs/` cover: `ARCHITECTURE.md`, `BOOT_PROCESS.md`, `MEMORY_LAYOUT.md`, `INTERRUPT_HANDLING.md`, `KERNEL_API.md`, `GRAPHICS_API.md`, `HAL_API.md`, `ROADMAP.md`. |
0 commit comments