Better docs and structure

isr.S

@@ -1,8 +1,28 @@
+/*
+ * isr.S – Interrupt Service Routine stubs for x86-64.
+ *
+ * Provides 256 thin stub functions (isr0 – isr255) and a common body
+ * (isr_common) that saves all general-purpose registers, calls the C
+ * handler isr_handler(ISRFrame *), restores registers, and returns
+ * via IRETQ.
+ *
+ * Two macros generate the stubs:
+ *   ISR_NOERR – pushes a dummy error code (0) for vectors that don't
+ *   ISR_ERR   – the CPU already pushed an error code
+ *
+ * A pointer table (isr_stub_table) is emitted at the end so that
+ * idt.c can look up the stub address for each vector by index.
+ */
+
 .text
 
 .global isr_handler
 .global isr_stub_table
 
+/* ----------------------------------------------------------------
+ *  Stub macros
+ * ---------------------------------------------------------------- */
+
 .macro ISR_NOERR num
 .global isr\num
 isr\num:
@@ -18,6 +38,10 @@ isr\num:
     jmp isr_common
 .endm
 
+/* ----------------------------------------------------------------
+ *  Common ISR body – saves state, calls C handler, restores state
+ * ---------------------------------------------------------------- */
+
 isr_common:
     cld
 
@@ -59,6 +83,15 @@ isr_common:
     addq $16, %rsp
     iretq
 
+/* ----------------------------------------------------------------
+ *  Stub instantiation  (vectors 0-255)
+ *
+ *  Vectors 0-31:  CPU exceptions (some push error codes)
+ *  Vectors 32-47: legacy 8259 PIC hardware IRQs
+ *  Vectors 48+:   available for software / APIC use
+ * ---------------------------------------------------------------- */
+
+/* CPU exceptions */
 ISR_NOERR 0
 ISR_NOERR 1
 ISR_NOERR 2
@@ -316,6 +349,11 @@ ISR_NOERR 253
 ISR_NOERR 254
 ISR_NOERR 255
 
+/* ----------------------------------------------------------------
+ *  Stub pointer table – indexed by vector number (0-255)
+ *  Used by idt_set_gate() in idt.c to populate the IDT.
+ * ---------------------------------------------------------------- */
+
 isr_stub_table:
     .quad isr0
     .quad isr1