Better docs and structure

memory.h

@@ -1,41 +1,51 @@
+/*
+ * memory.h – Memory management subsystem declarations.
+ *
+ * Three layers:
+ *   PMM   – bitmap-based physical page-frame allocator (16 MB pool)
+ *   Paging – walks / creates 4-level x86-64 page tables
+ *   Heap  – first-fit free-list allocator with block coalescing
+ */
+
 #ifndef MEMORY_H
 #define MEMORY_H
 
 #include <efi.h>
 #include "boot_info.h"
 
-/* Page size constants */
+/* ================================================================
+ *  Page-level constants
+ * ================================================================ */
+
 #define PAGE_SIZE       4096
 #define PAGE_SHIFT      12
 #define PAGE_MASK       (~(UINT64)(PAGE_SIZE - 1))
 
-/* Page table entry flags */
-#define PTE_PRESENT     (1ULL << 0)
-#define PTE_WRITABLE    (1ULL << 1)
-#define PTE_USER        (1ULL << 2)
+/* ================================================================
+ *  Page-table entry flags  (x86-64 4-level paging)
+ * ================================================================ */
+
+#define PTE_PRESENT      (1ULL << 0)
+#define PTE_WRITABLE     (1ULL << 1)
+#define PTE_USER         (1ULL << 2)
 #define PTE_WRITETHROUGH (1ULL << 3)
-#define PTE_NOCACHE     (1ULL << 4)
-#define PTE_ACCESSED    (1ULL << 5)
-#define PTE_DIRTY       (1ULL << 6)
-#define PTE_HUGE        (1ULL << 7)
-#define PTE_GLOBAL      (1ULL << 8)
-#define PTE_NX          (1ULL << 63)
+#define PTE_NOCACHE      (1ULL << 4)
+#define PTE_ACCESSED     (1ULL << 5)
+#define PTE_DIRTY        (1ULL << 6)
+#define PTE_HUGE         (1ULL << 7)   /* 2 MB or 1 GB page */
+#define PTE_GLOBAL       (1ULL << 8)
+#define PTE_NX           (1ULL << 63)  /* No-Execute             */
 
-#define PTE_ADDR_MASK   0x000FFFFFFFFFF000ULL
+#define PTE_ADDR_MASK    0x000FFFFFFFFFF000ULL
 
-/* PMM pool: 16 MB managed by the kernel */
-#define PMM_POOL_SIZE   (16ULL * 1024 * 1024)
+/* ================================================================
+ *  Physical Memory Manager (PMM)
+ * ================================================================ */
+
+/* Size of the PMM-managed pool (allocated from UEFI at boot). */
+#define PMM_POOL_SIZE   (16ULL * 1024 * 1024)   /* 16 MB  */
 #define PMM_POOL_PAGES  (PMM_POOL_SIZE / PAGE_SIZE)
 
-/* Heap constants */
-#define HEAP_INITIAL_PAGES  64   /* 256 KB initial heap */
-#define HEAP_BLOCK_MAGIC    0xDEADBEEFU
-#define HEAP_BLOCK_FREE     0
-#define HEAP_BLOCK_USED     1
-#define HEAP_ALIGN          16
-
-/* -------- Physical Memory Manager -------- */
-
 void    pmm_init(BootInfo *Boot);
 UINT64  pmm_alloc_page(void);
 void    pmm_free_page(UINT64 phys_addr);
@@ -44,19 +54,33 @@ void    pmm_free_pages(UINT64 phys_addr, UINTN count);
 UINTN   pmm_get_free_pages(void);
 UINTN   pmm_get_total_pages(void);
 
-/* -------- Paging -------- */
+/* ================================================================
+ *  Paging
+ * ================================================================ */
 
 void    paging_init(BootInfo *Boot);
 BOOLEAN paging_map_page(UINT64 virt, UINT64 phys, UINT64 flags);
 void    paging_unmap_page(UINT64 virt);
 UINT64  paging_get_phys(UINT64 virt);
 
-/* -------- Heap Allocator -------- */
+/* ================================================================
+ *  Heap allocator
+ * ================================================================ */
 
+#define HEAP_INITIAL_PAGES  64          /* 256 KB initial heap          */
+#define HEAP_BLOCK_MAGIC    0xDEADBEEFU /* corruption-detection canary  */
+#define HEAP_BLOCK_FREE     0
+#define HEAP_BLOCK_USED     1
+#define HEAP_ALIGN          16          /* minimum allocation alignment */
+
+/*
+ * HeapBlock – header placed immediately before each allocation.
+ * Blocks form a doubly-linked free-list.
+ */
 typedef struct HeapBlock {
-    UINT32 magic;
-    UINT32 state;
-    UINTN  size;              /* usable bytes (excludes header) */
+    UINT32 magic;               /* must be HEAP_BLOCK_MAGIC     */
+    UINT32 state;               /* HEAP_BLOCK_FREE / _USED      */
+    UINTN  size;                /* usable bytes (excludes hdr)  */
     struct HeapBlock *next;
     struct HeapBlock *prev;
 } HeapBlock;
@@ -67,9 +91,14 @@ void  kfree(void *ptr);
 void  heap_get_stats(UINTN *total, UINTN *used, UINTN *free_mem,
                      UINTN *num_blocks);
 
-/* -------- Top-level helpers -------- */
+/* ================================================================
+ *  Top-level helpers
+ * ================================================================ */
 
+/* Initialise all memory subsystems (PMM → paging → heap). */
 void memory_init(BootInfo *Boot);
+
+/* Print PMM, heap, and paging statistics to the console. */
 void memory_print_stats(BootInfo *Boot);
 
-#endif
+#endif /* MEMORY_H */