aarch64: minimal GICv2 driver -- distributor, CPU interface, timer PPI

Punch list §25 item 0.6 complete.

Ruling applied (AskUserQuestion, this session): DTB is confirmed unreachable
on this system's aarch64 firmware too (qemu-efi-aarch64 2025.11-3ubuntu7,
same finding as riscv64's item 0.3), so GICD/GICC base addresses and the
timer PPI are named QEMU-virt constants with a recorded caveat, not
DTB-discovered as the item originally asked.

Nothing here was recalled from memory. Base addresses (GICD 0x08000000,
GICC 0x08010000) and the timer PPI (30, non-secure EL1 physical) were read
out of QEMU 10.2.1's own internal devicetree via
`qemu-system-aarch64 -machine virt,dumpdtb=...`, decoded with this tree's own
fdt.c reader rather than a new tool -- correct for this exact QEMU version,
not assumed stable across others. Bonus finding from the same dump: PPI 26
for the EL2 hypervisor timer, which item 0.7 will need for its EL2 path.
Register offsets within each block (GICD_CTLR, GICC_IAR, etc.) are GICv2
architectural constants, not board-specific, and were cross-checked against
Linux's own arm-gic.h driver header rather than recalled either.

Acceptance amended before implementing (§25.0 "when an item is genuinely
wrong"): the original text required observing a delivered-and-acknowledged
timer interrupt, which cannot happen within this item's own scope --
apic_timer_start() (item 0.7) is still the no-op stub, so nothing arms the
timer. This is the same defect the earlier review's C2 fix already applied to
items 0.2 and 0.5; it was missed here. Acceptance is now: GIC initialises
without fault, the IAR/EOIR path is wired into aarch64_irq_handler() and
ready, boots with no regression -- item 0.7's tick-advance is what proves
delivery, exactly as 0.5 already defers to 0.7.

EL-aware (B3, same discipline as items 0.4/0.5): apic_init() selects PPI 30
or 26 from aarch64_current_el(), decided once and cached, not re-derived per
interrupt.

aarch64_irq_handler() now does real work: reads GICC_IAR (the GICv2
acknowledgement step), dispatches to heartbeat_tick() when the INTID matches
the timer PPI, and always completes with GICC_EOIR (INTID 1023 = spurious
handled per the GICv2 spec, not as a special case of "unrecognised"). This
mirrors exactly how riscv64's item 0.2 built full cause-dispatch logic before
its timer was armed in 0.3.

Investigated and resolved a real scare during verification: QEMU's `-d int`
trace showed 1,728 "Taking exception 5 [IRQ]" events by the time boot reached
the prompt, which looked exactly like an interrupt storm (hypothesis: EDK2
firmware leaves CNTP_CTL_EL0 enabled with a stale comparator, and enabling
the GIC path exposes it before item 0.7 reprograms the timer). A direct
one-shot probe inside aarch64_irq_handler() itself -- ground truth for
whether this code path runs at all -- fired zero times across a clean,
bounded boot. The trace events were almost certainly from EDK2 firmware's
own internal timer usage during its own boot phase, before control passes to
this kernel; the earlier conclusion was drawn from the external trace alone
without checking that distinction, and the probe (not the trace) is what
settled it. Probe code fully reverted; not part of the commit.

Verified: builds clean, boots to ok> with no regression, dict_hash
0x3d4e1daf289da94f unchanged from the item 0.1-0.5 baseline, EL banner and
IDT-installed lines still print in order, GIC init line confirms PPI 30
selected. Only aarch64-scoped files touched; amd64/riscv64 not rebuilt.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

src/starkernel/arch/aarch64/interrupts.c

@@ -11,6 +11,7 @@
 #include <stdint.h>
 #include "arch.h"
 #include "console.h"
+#include "starkernel/timer.h"
 
 volatile const char *g_sk_fault_word = (void *)0;
 
@@ -23,8 +24,22 @@ extern void aarch64_install_vectors(void);
  * arch/riscv64/interrupts.c. */
 extern int aarch64_current_el(void);
 
+/* Defined in apic.c (item 0.6). Same extern-in-place convention: GICv2
+ * register-level details belong to the file that owns the MMIO base
+ * addresses, not the shared apic.h. */
+extern uint32_t apic_read_iar(void);
+extern uint32_t apic_timer_ppi(void);
+extern void     apic_eoi_intid(uint32_t intid);
+
+/* INTID 1023 = "spurious" (GICv2 spec): the CPU interface has nothing
+ * pending, typically because another interrupt at the same or higher
+ * priority raced this one to acknowledgement. Architecturally defined,
+ * not this board's invention, so it is named rather than left as a magic
+ * number in the comparison below. */
+#define GIC_INTID_SPURIOUS  1023u
+
 /**
- * @brief Dispatch an IRQ taken at current-EL with SPx (punch-list item 0.5).
+ * @brief Dispatch an IRQ taken at current-EL with SPx (punch-list item 0.6).
  *
  * Called from @c irq_spx_trampoline in @c isr.S, which has already saved the
  * full caller-saved integer and FP/SIMD register sets plus @c ELR_ELx /
@@ -32,18 +47,33 @@ extern int aarch64_current_el(void);
  * returns — unlike @c aarch64_exception_handler(), this path is designed to
  * return normally.
  *
- * **Deliberately empty at this item.** Distinguishing which interrupt fired
- * requires reading the GIC's Interrupt Acknowledge Register, and
- * acknowledging it requires writing EOIR — neither exists yet (item 0.6).
- * Nothing currently unmasks or routes any interrupt source to this vector,
- * so it is not reachable during a normal boot; item 0.5's own acceptance is
- * "boots with no regression," not having observed a call here (C2). This
- * function exists so the vector split is complete and linkable now, ready
- * for item 0.6 to add the IAR read / cause dispatch / EOIR write, and item
- * 0.7 to route the timer PPI to @c heartbeat_tick() through it.
+ * Reads @c GICC_IAR once (the GICv2 acknowledgement step — this also moves
+ * the interrupt to the active state), dispatches on the returned INTID, and
+ * always completes with the matching @c GICC_EOIR write, spurious or not:
+ * a spurious read must still not be treated as "nothing to clean up," and
+ * an unrecognised real INTID still needs the CPU interface unblocked for
+ * the next one.
+ *
+ * The only INTID actually routed anywhere is the timer PPI
+ * (@c apic_timer_ppi() — 30 at EL1, 26 at EL2, decided once in
+ * @c apic_init()), which calls @c heartbeat_tick(). **Unreachable in
+ * practice at this item**: @c apic_timer_start() (item 0.7) is still the
+ * no-op stub, so nothing ever arms @c CNTP_CTL_EL0 / @c CNTHP_CTL_EL2 and
+ * the GIC never sees the timer line assert. Item 0.7's tick-advance
+ * acceptance is what proves this dispatch actually runs (same deferral
+ * item 0.5 already made, C2).
  */
 void aarch64_irq_handler(void)
 {
+    uint32_t intid = apic_read_iar();
+
+    if (intid == apic_timer_ppi()) {
+        heartbeat_tick();
+    }
+
+    if (intid != GIC_INTID_SPURIOUS) {
+        apic_eoi_intid(intid);
+    }
 }
 
 /**