cleonos/docs/stage2.md

# CLeonOS Stage2

## Stage Goal
- Introduce foundational memory management for CLKS.
- Initialize physical memory manager (PMM) from Limine memmap.
- Add kernel heap allocator (`clks_kmalloc`/`clks_kfree`) without external libc.
- Emit memory statistics via kernel log during boot.

## Acceptance Criteria
- Kernel receives valid Limine memmap response.
- PMM initializes and prints managed/free/used/dropped page counts.
- Heap initializes and prints total/free bytes.
- `clks_kmalloc` self-test allocates and frees successfully.
- Kernel still reaches idle loop without panic.

## Build Targets
- `make setup`
- `make iso`
- `make run`
- `make debug`

## QEMU Command
- `qemu-system-x86_64 -M q35 -m 1024M -cdrom build/CLeonOS-x86_64.iso -serial stdio`

## Common Bugs and Debugging
- `NO LIMINE MEMMAP RESPONSE`:
  - Check Limine protocol entry in `configs/limine.conf` and ensure `protocol: limine` is used.
- PMM managed pages are 0:
  - Validate `LIMINE_MEMMAP_REQUEST` ID and section placement in `limine_requests.c`.
- Heap self-test failed:
  - Inspect `heap.c` block split/merge logic and verify allocator init was called.
- Limine panic about ELF segment permissions:
  - Ensure linker sections are page-aligned and segment permissions do not share pages.
- Limine artifacts missing during ISO packaging:
  - Verify `make setup` completed and `limine/bin/*` files exist.