Sylva/AGENTS.md

Sylva OS — Agent Guide

x86_64 UEFI hobby OS. C17 boot → C++17 kernel, ELF64 → PE32+ via objcopy.

Build & Run

Command	What
make	Build build/BOOTX64.EFI + build/Kernel.elf
make run	QEMU + OVMF, serial 1 → serial.log, serial 2 → stdio, paused for GDB (:1234)
make vdir	Stage both binaries into vdir/EFI/BOOT/ for manual boot
make clean	Always before commit — untracked build artifacts leak outside build/

Architecture

• Two-stage boot: boot.c (UEFI app) loads Kernel.elf from FAT volume, parses ELF PHDRs, jumps to entry
• kernel/entry.cpp — _start saves SystemTable, calls kernel_main()
• kernel/main.cpp — extern "C" kernel_main(): init GOP → serial → PMM → heap → idle (hlt)
• kernel/serial.cpp — UEFI serial protocol wrapper (write/read/hex)
• kernel/memory/pmm.cpp — bitmap + free-list physical page allocator
• kernel/memory/heap.cpp — kmalloc/kfree/kcalloc/krealloc (first-fit w/ coalescing)
• graphics/ — GOP framebuffer, fonts/ — Hankaku 8×16 font via pf_print()
• efi/ — bundled gnu-efi sources: gnuefi/ (crt0, lds, reloc), lib/, inc/
• Kernel linked at 0x100000 (kernel/kernel.ld)

Conventions

• Commits: [type] message with types feat, fix, chore, docs (git log)
• #define ASM asm volatile in include/common.h
• C17 (boot.c), C++17 (kernel/) — -ffreestanding -fno-stack-protector -fshort-wchar -mno-red-zone
• uefi_call_wrapper required for all UEFI protocol calls (omission → page-fault)
• kernel_main must be extern "C" (C→C++ linkage)
• QEMU starts paused: connect GDB to :1234 to proceed
• No tests, no CI, no lint config