/*
 * kido-vec-arm64.h — Kido ARM64 exception-vector module, public interface.
 *
 * The table the GIC driver (session 27) was waiting for: VBAR_EL1
 * + DAIF controls + the IRQ stub that calls kido_gic_dispatch().
 * Implementation lives in kido-vec-arm64.S (the table must be
 * assembly: 2048-byte alignment, 128-byte entries, a frame save
 * the compiler cannot be trusted to emit for the interrupted
 * context — the scheduler .S lesson, applied to interrupts).
 *
 * TABLE LAYOUT (ARM AArch64 exception model):
 *   16 entries, 128 bytes apart, base 2048-byte aligned, in four
 *   groups of four — EL1t (SP_EL0), EL1h (SP_EL1), EL0 AArch64,
 *   EL0 AArch32 — each ordered Sync / IRQ / FIQ / SError.
 *   Kido runs EL1h, so the live IRQ entry is entry 5.
 *   The constants below name the vector index each unhandled
 *   handler stashes into kido_vec_last_kind.
 *
 * HONESTY LAW:
 *  - Only IRQ from EL1h is live. Every other entry stashes its
 *    index + ESR_EL1 into the BSS slots below and spins: Kido
 *    has no EL0, no EL1t stack, and no FIQ source (the GIC is
 *    configured Group0 -> IRQ only), so any other entry firing
 *    means the system's own assumptions broke. Spinning with
 *    the evidence stashed is loud (the console stops); returning
 *    would resume a state nobody vouches for.
 *  - FIQ is NOT routed to dispatch: a FIQ firing means the
 *    controller was misconfigured. Routing it would let a
 *    misconfiguration masquerade as a handled interrupt.
 *  - No nesting: exception entry masks IRQ, and the stub never
 *    unmasks. A second IRQ cannot land inside the first
 *    handler's frame. Handlers must stay short (GIC contract);
 *    a future IRQ-stack module is the named fix for long ones.
 *  - No console at this layer: the unhandled handler cannot
 *    print (the HAL owns the UART, and the handler may fire
 *    before HAL init). Evidence lives in BSS for a later,
 *    console-owning layer or a debugger — the reloc module's
 *    BSS-report precedent.
 *  - Install uses adr (PC-relative): the table address is true
 *    wherever the image runs, including after the phase-3
 *    relocator. The table holds branches only and the file
 *    holds no absolute literal, so it adds ZERO entries to
 *    .rela.dyn and needs ZERO carve-outs from the phase-3
 *    walk — a design property to be confirmed by disassembly
 *    at the proof gate, not a claim made today.
 *  - No status codes: at EL1 these controls cannot fail, so
 *    there is no failure mode to map. Below EL1 the msr
 *    faults by architecture — the caller contract is EL1,
 *    stated here, not enforced by a code.
 *
 * INSTALL ORDER LAW (VBAR is undefined at reset):
 *   1. kido_vec_install()   — VBAR_EL1 = table address
 *   2. kido_gic_init()      — controller programmed
 *   3. handlers registered + enabled at the GIC
 *   4. kido_vec_irq_enable() — LAST, DAIF.I cleared
 *   Enabling IRQ before install would vector an interrupt to
 *   a stale or zero base — a fault with no handler.
 *
 * SEAM (Gate item, not this session): this module ships
 * uncalled. The Gate session wires kido_vec_install() into the
 * boot path after kido_reloc_verify() OK and before GIC
 * enable, and retires the session-27 scratch stub from all
 * records. Zero Gate-approved files are touched this session.
 *
 * PROOF STATUS (honest): ASSEMBLED AND PROVEN ON QEMU
 * 2026-10-27 (session 31, deliberations/
 * 2026-10-27-kido-irq-proof-design.md + qemu-irq-proof.log):
 * the committed table (not the session-27 scratch stub) ran
 * under QEMU virt (gic-version=2): VBAR readback == table
 * address (0x40080800, 2048-aligned), 5 IRQ entries taken
 * through entry 5 with 5 clean exception returns, zero
 * fault-class entries. The SGI-only shape from session 27
 * is superseded by this run: the timer PPI-30 IRQ and the
 * UART SPI-33 IRQ both arrived through this table.
 * Still Gate items: wiring kido_vec_install into the boot
 * path, Pi4 identities, the scheduler-tick policy.
 *
 * Draft status: DRAFT (2026-10-25, session 28). No bootable
 * kernel is finalized without N8toriousAi; first boot is his to
 * witness.
 */
#ifndef KIDO_VEC_ARM64_H
#define KIDO_VEC_ARM64_H

#include <stdint.h>

#if !defined(__aarch64__) && !defined(KIDO_HOSTED_TEST)
#error "kido-vec-arm64: refusing to compile for unknown arch. The vector table lives in per-arch assembly; define KIDO_HOSTED_TEST for the hosted draft harness."
#endif

/* Vector indices, in table order. The unhandled handler stashes
 * one of these into kido_vec_last_kind. Entry 5 is the live one. */
#define KIDO_VEC_SYNC_EL1T   0u
#define KIDO_VEC_IRQ_EL1T    1u
#define KIDO_VEC_FIQ_EL1T    2u
#define KIDO_VEC_ERR_EL1T    3u
#define KIDO_VEC_SYNC_EL1H   4u
#define KIDO_VEC_IRQ_EL1H    5u  /* THE live entry */
#define KIDO_VEC_FIQ_EL1H    6u
#define KIDO_VEC_ERR_EL1H    7u
#define KIDO_VEC_SYNC_EL0_64 8u
#define KIDO_VEC_IRQ_EL0_64  9u
#define KIDO_VEC_FIQ_EL0_64  10u
#define KIDO_VEC_ERR_EL0_64  11u
#define KIDO_VEC_SYNC_EL0_32 12u
#define KIDO_VEC_IRQ_EL0_32  13u
#define KIDO_VEC_FIQ_EL0_32  14u
#define KIDO_VEC_ERR_EL0_32  15u

/* The table itself (defined in kido-vec-arm64.S). A proof harness
 * takes its address and compares it against the VBAR_EL1
 * readback after kido_vec_install() — the install-order check. */
extern const char kido_vec_table[];

/* Unhandled-exception evidence (BSS, zeroed by the entry .S at
 * boot). kido_vec_last_kind = vector index 0-15, or 0 when no
 * unexpected exception has fired yet (note: index 0 is also a
 * real entry — a kind of 0 with a nonzero ESR is the tell).
 * kido_vec_last_esr = ESR_EL1 at that exception. */
extern uint64_t kido_vec_last_kind;
extern uint64_t kido_vec_last_esr;

/* Write VBAR_EL1 = table address, then ISB. EL1 only. Must run
 * before any IRQ is unmasked (install order law, above). */
void kido_vec_install(void);

/* PSTATE.I controls. EL1 only. irq_enable clears the I mask
 * (IRQs may fire); irq_disable sets it. irq_masked returns 1
 * when IRQs are currently masked, 0 when unmasked. */
void kido_vec_irq_enable(void);
void kido_vec_irq_disable(void);
int kido_vec_irq_masked(void);

#endif /* KIDO_VEC_ARM64_H */
