kva_alloc: document linear mapping overlap with boot.S

Add documentation note explaining that the KVA allocator region
(0xC0500000..0xC0800000) falls within the initial 16MB linear mapping
set up by boot.S (0xC0000000..0xC0100000). This means V2P() works by
coincidence for addresses in this range, but code should use
vmm_virt_to_phys() instead to be portable and future-proof.

This documents the architectural fragility identified during H6
regression analysis.

Test: make test-battery PASS (157/157), make analyzer PASS

diff --git a/include/kva_alloc.h b/include/kva_alloc.h
index ec87458cdd2178a9d3aa8d1c1c6bc674b343e5df..b4ebfb35e9e9e5eaba6476a5a0c792ce176d3f0f 100644 (file)
--- a/include/kva_alloc.h
+++ b/include/kva_alloc.h
@@ -21,6 +21,11 @@
  * Allocator region: 0xC0500000 .. 0xC0800000 (3 MB, 768 pages)
  * - Below 0xC0500000: Fixed MMIO regions (ACPI, ATA, E1000, LAPIC, IOAPIC)
  * - Above 0xC0800000: Kernel stacks, heap, initrd, framebuffer
+ *
+ * NOTE: The allocator region (0xC0500000..0xC0800000) falls within the initial
+ * 16MB linear mapping set up by boot.S (0xC0000000..0xC0100000). This means
+ * V2P() works by coincidence for addresses in this range, but code should use
+ * vmm_virt_to_phys() instead to be portable and future-proof.
  */
 
 /* Initialize the KVA allocator */