Better docs and structure

boot_info.h

@@ -1,22 +1,45 @@
+/*
+ * boot_info.h – Shared interface between the UEFI loader and the kernel.
+ *
+ * The BootInfo struct is populated by the loader (main.c) and passed to
+ * the kernel entry point (kmain).  It provides function pointers that
+ * abstract UEFI Boot/Runtime Services so the kernel can use console I/O,
+ * memory allocation, and system control without linking against GNU-EFI.
+ */
+
 #ifndef BOOT_INFO_H
 #define BOOT_INFO_H
 
 #include <efi.h>
 
+/* Printf-style print function (backed by UEFI ConOut). */
 typedef UINTN (*KernelPrintFn)(const CHAR16 *Format, ...);
 
+/*
+ * BootInfo – everything the kernel needs from the UEFI environment.
+ *
+ * All function pointers are optional: the kernel must NULL-check before
+ * calling.  If a service is unavailable the corresponding field is NULL.
+ */
 typedef struct {
-    EFI_SYSTEM_TABLE *SystemTable;
-    KernelPrintFn print;
-    EFI_STATUS (*clear_screen)(void);
-    EFI_STATUS (*set_attribute)(UINTN Attribute);
-    EFI_STATUS (*read_key)(EFI_INPUT_KEY *Key);
-    EFI_STATUS (*try_read_key)(EFI_INPUT_KEY *Key);  /* non-blocking */
-    void (*shutdown)(void);
+    EFI_SYSTEM_TABLE *SystemTable;          /* UEFI System Table            */
+
+    /* Console I/O */
+    KernelPrintFn print;                    /* formatted text output        */
+    EFI_STATUS (*clear_screen)(void);       /* clear the console            */
+    EFI_STATUS (*set_attribute)(UINTN Attribute); /* set text colour/attr   */
+    EFI_STATUS (*read_key)(EFI_INPUT_KEY *Key);   /* blocking key read      */
+    EFI_STATUS (*try_read_key)(EFI_INPUT_KEY *Key); /* non-blocking key read */
+
+    /* System control */
+    void (*shutdown)(void);                 /* power-off the machine        */
+
+    /* Physical memory */
     EFI_STATUS (*alloc_pages)(UINTN pages, EFI_PHYSICAL_ADDRESS *addr);
     EFI_STATUS (*free_pages)(EFI_PHYSICAL_ADDRESS addr, UINTN pages);
 } BootInfo;
 
+/* Kernel entry point signature (called by the UEFI loader). */
 typedef void (*KernelEntryFn)(BootInfo *Boot);
 
-#endif
+#endif /* BOOT_INFO_H */