From 866c3e4d0324f1f337e5c9a95bac2a6baadb416b Mon Sep 17 00:00:00 2001 From: pyao12 Date: Sat, 6 Jun 2026 10:49:52 +0800 Subject: [PATCH] [chore] Update AGENTS.md --- AGENTS.md | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index cb49691..bdf9a0c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -50,9 +50,26 @@ All `string_utils.h` helpers are `static inline` — header-only, no link issues ## Conventions -- **Commits:** `[type] message` — types: `feat`, `fix`, `chore`, `docs`, `refactor` (see `git log`). +- **Commits:** `[type] message` — types: `feat`, `fix`, `chore`, `docs`, `refactor`, `optm` (see `git log`). - **Languages:** C17 (`boot.c`), C++17 (`kernel/`) — `-ffreestanding -fno-stack-protector -fshort-wchar -mno-red-zone -fcf-protection=none`. Kernel adds `-DGNU_EFI_USE_MS_ABI -fno-pic`. - **`kernel_main` must be `extern "C"`** — `boot.c` (C) calls into C++ (`kernel/entry.cpp:6`). - **All UEFI protocol calls must use `uefi_call_wrapper`** — calling the member fn directly page-faults in long mode. See `kernel/main.cpp:23-24` and throughout. - **Kernel linked at `0x100000`** (`kernel/kernel.ld`); `.bss` start/end symbols exposed as `__bss_start` / `__bss_end`. - **No tests, no CI, no lint config** — `make` is the only verification step. Boot by hand in QEMU to confirm kernel output in `serial.log`. + +## Global state + +| Symbol | File | Type | +|--------|------|------| +| `ST` | `kernel/entry.cpp` | `EFI_SYSTEM_TABLE*` — saved from UEFI boot | +| `g_gfx` | `include/graphics/context.h` | `gfx_context` — GOP framebuffer info | +| `g_draw_target` | `include/graphics/context.h` | `draw_target` — current draw surface | +| `g_pmm` | `include/memory/pmm.h` | `pmm_t` — physical page allocator state | +| `g_serial` | `kernel/serial.cpp` | `serial_context` — serial protocol handle | + +## Gotchas + +- **No paging** — kernel runs in physical memory, identity-mapped. +- **No libc** — all string/memory ops go through `string_utils.h` (header-only, `static inline`). +- **Window switching** uses Shift+F10 (hardcoded PS/2 scan codes in `kernel/graphics/layer.cpp`). +- **`third_party/`** is empty — no external deps beyond bundled gnu-efi in `efi/`.