Sylva OS — Agent Guide

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

Build & Run

Command	What
`make`	Build `build/BOOTX64.EFI`
`make run`	QEMU + OVMF, serial port 1 → `serial.log`, serial port 2 → stdio, paused for GDB (`-s -S`)
`make clean`	Always before commit — gnu-efi build produces untracked files outside `build/`

boot.c — UEFI entrypoint (efi_main → kernel_main())
kernel/main.cpp — extern "C" kernel_main(): init GOP → serial → PMM → heap → idle (hlt)
kernel/serial.cpp — UEFI serial protocol wrapper
kernel/memory/pmm.cpp — bitmap + free-list physical page allocator
kernel/memory/heap.cpp — kmalloc/kfree/kcalloc/krealloc (first-fit, coalescing)
graphics/ — GOP framebuffer pixel drawing, fonts/ — Hankaku 8×16 font renderer
efi/ — bundled gnu-efi source; gnu-efi/ is an unregistered submodule reference

uefi_call_wrapper required for all UEFI protocol calls — omitting it causes page-faults (see kernel/main.cpp:49)
kernel_main must be extern "C" (C→C++ linkage)
QEMU starts paused — connect GDB to :1234 to proceed
Compiler standards: C17 (boot.c), C++17 (kernel/), -ffreestanding -fno-stack-protector -fshort-wchar -mno-red-zone
#define ASM asm volatile in include/common.h
BUILD_INFOS.h — placeholder for CI; .github/ is empty
No tests, no CI, no lint/formatter config