Better docs and structure

idt.h

@@ -1,10 +1,22 @@
+/*
+ * idt.h – Interrupt Descriptor Table interface.
+ *
+ * Declares the ISR stack frame layout (pushed by isr_common in isr.S)
+ * and the IDT initialisation function.
+ */
+
 #ifndef IDT_H
 #define IDT_H
 
 #include <efi.h>
 #include "boot_info.h"
 
+/*
+ * ISRFrame – register state saved by isr_common before calling
+ * isr_handler().  The order must match the push sequence in isr.S.
+ */
 typedef struct {
+    /* General-purpose registers (pushed by isr_common) */
     UINT64 r15;
     UINT64 r14;
     UINT64 r13;
@@ -20,13 +32,21 @@ typedef struct {
     UINT64 rcx;
     UINT64 rbx;
     UINT64 rax;
+
+    /* Pushed by the ISR stub macros */
     UINT64 vector;
     UINT64 error_code;
+
+    /* Pushed by the CPU on interrupt entry */
     UINT64 rip;
     UINT64 cs;
     UINT64 rflags;
 } ISRFrame;
 
+/*
+ * Install our IDT: copies firmware entries for vectors 32+,
+ * overrides vectors 0-31 with kernel exception handlers.
+ */
 void idt_init(BootInfo *Boot);
 
-#endif
+#endif /* IDT_H */