/*
 * kido-gic.h — Kido GICv2 interrupt controller driver, public interface.
 *
 * The ARM Generic Interrupt Controller, version 2, MMIO CPU
 * interface: distributor (routing, enable, priority, target,
 * config) + one CPU interface (acknowledge, end-of-interrupt).
 * Companion to kido-pl011: this is the controller that will one
 * day deliver the PL011 RX interrupt (QEMU virt SPI 33). It does
 * NOT replace anything — no existing file is touched this session
 * (fence: new files only; HAL wiring and the exception-vector
 * module are future Gate items).
 *
 * REGISTERS (ARM GIC Architecture Specification, IHI 0048B):
 * Distributor: CTLR 0x000, TYPER 0x004, IIDR 0x008, IGROUPR
 * 0x080, ISENABLER 0x100, ICENABLER 0x180, ISPENDR 0x200,
 * ICPENDR 0x280, ISACTIVER 0x300, ICACTIVER 0x380, IPRIORITYR
 * 0x400, ITARGETSR 0x800 (0x800-0x81C read-only: SGI/PPI targets
 * are fixed), ICFGR 0xC00, SGIR 0xF00.
 * CPU interface: CTLR 0x000, PMR 0x004, BPR 0x008, IAR 0x00C,
 * EOIR 0x010, RPR 0x014, HPPIR 0x018, ABPR 0x01C, AIAR 0x020,
 * AEOIR 0x024, AHPPIR 0x028, IIDR 0x0FC, DIR 0x1000.
 *
 * KNOWN BASES (verified 2026-10-25, see the deliberation record):
 *   QEMU virt GICv2: distributor 0x08000000, CPU interface
 *     0x08010000 (DTB intc@8000000 reg regions, gic-version=2).
 *   No Pi4 GIC base is named here: the Pi4 GIC-400 base was not
 *     verified from a source this session, and a guessed base
 *     would silently program the wrong MMIO. A Pi4 caller
 *     supplies both bases — same discipline as the PL011 clock.
 *
 * INTERRUPT CLASSES: SGI 0-15 (software, per-CPU), PPI 16-31
 * (private, per-CPU), SPI 32+ (shared, routed). Spurious ID 1023.
 * ICFGR field: 0b00 = level-sensitive, 0b10 = edge-triggered.
 * SGIR: filter bits 25:24 (= 0 here: explicit target list),
 * CPU target list bits 23:16, SGIINTID bits 3:0.
 *
 * HONESTY LAW:
 *  - GICv2 only, UP only. One CPU interface; all SPI targets
 *    CPU0. GICv3, SMP targets, and virtual interfaces are named
 *    futures, not flags on this driver.
 *  - Group0-only routing (distributor CTLR = 1, CPU CTLR = 1,
 *    FIQEn = 0 so Group0 signals IRQ). Validated by the QEMU
 *    SGI proof this session; Group1 classification is deferred
 *    (deliberation D2), not silently enabled.
 *  - init guarantees routability only: distributor off, SPI
 *    targets CPU0, enables cleared, pending cleared, PMR = 0xFF,
 *    BPR = 0, distributor on. Priorities stay at reset (0) and
 *    trigger config stays at reset (level); the caller assigns
 *    them through set_priority / set_config.
 *  - dispatch owns EOIR always (even with no handler), except
 *    the spurious ID, where there is nothing to complete and
 *    no EOIR is written. EOIR echoes the full IAR value so
 *    SGI source-CPUID bits (12:10) deactivate the right source.
 *  - The IRQ bound comes from GICD_TYPER ITLinesNumber:
 *    (lines + 1) * 32, capped at the architectural 1020
 *    sources. No hardcoded QEMU interrupt count is trusted.
 *  - set_target / set_config accept SPI only (SGI/PPI targets
 *    are read-only/fixed by the architecture) — loud EARLY_ENV
 *    otherwise, never a write to a read-only register.
 *  - Programming the GIC does NOT deliver interrupts: the core
 *    still needs DAIF unmasked and a VBAR table whose IRQ stub
 *    calls kido_gic_dispatch(). That is the future
 *    exception-vector module's job, stated here so nobody
 *    claims "interrupts work" from this driver alone.
 *  - WRITTEN, HOSTED-PROVEN, CROSS-COMPILED, SGI-PROVEN ON
 *    QEMU (see the ledger entry): the hosted double pins the
 *    register image and every loud failure; the QEMU scratch
 *    harness proves SGI delivery through these exact
 *    functions. SPI delivery through a real device is NOT
 *    proven — that is the vector module's proof.
 *  - No new header code (N8toriousAi's call, sched-D1 precedent):
 *    every failure maps to KIDO_ERR_EARLY_ENV.
 *
 * FUTURES (named, not built): exception-vector module (VBAR +
 * DAIF + IRQ stub -> dispatch), SPI delivery proof (UART RX IRQ
 * 33), GICv3 module, SMP targets, SGI broadcast filters,
 * Group1 classification for a secure-world caller.
 *
 * Draft status: DRAFT (2026-10-25, session 27). No bootable kernel
 * is finalized without N8toriousAi; first boot is his to witness.
 */
#ifndef KIDO_GIC_H
#define KIDO_GIC_H

#include "kido-boot.h"

#if !defined(__aarch64__) && !defined(KIDO_HOSTED_TEST)
#error "kido-gic: refusing to compile for unknown arch. GIC MMIO lives in per-arch files; define KIDO_HOSTED_TEST for the hosted draft harness."
#endif

/* Verified bases (see the header's KNOWN BASES note). */
#define KIDO_GIC_QEMU_VIRT_DIST_BASE 0x08000000u
#define KIDO_GIC_QEMU_VIRT_CPU_BASE  0x08010000u
/* No Pi4 bases: unverified this session (see above). */

/* Architectural constants. */
#define KIDO_GIC_SGI_MAX      15u   /* SGI IDs 0-15 */
#define KIDO_GIC_PPI_BASE     16u   /* PPI IDs 16-31 */
#define KIDO_GIC_SPI_BASE     32u   /* SPI IDs 32+ */
#define KIDO_GIC_MAX_SOURCES  1020u /* architectural source cap */
#define KIDO_GIC_SPURIOUS_ID  1023u /* IAR value when nothing pends */

/* Trigger config values for kido_gic_set_config. */
#define KIDO_GIC_TRIG_LEVEL 0u
#define KIDO_GIC_TRIG_EDGE  1u

/* Handler signature: called by dispatch() with the interrupt ID
 * and the caller's arg. Runs in interrupt context (from the
 * future vector stub): keep it short, no blocking, no allocator. */
typedef void (*kido_gic_handler_t)(uint32_t irq, void *arg);

/* Initialize the distributor + CPU interface. Distributor off,
 * SPI targets CPU0, enables cleared, pending cleared, PMR = 0xFF,
 * BPR = 0, distributor on. Re-init is allowed and clears the
 * handler table (init rebuilds the world). Returns EARLY_ENV on
 * zero bases. No register is touched when an argument check
 * fails first. */
kido_status_t kido_gic_init(uint64_t dist_base, uint64_t cpu_base);

/* Number of implemented interrupt sources, from GICD_TYPER at
 * init time. EARLY_ENV before init or on a NULL out-pointer. */
kido_status_t kido_gic_irq_count(uint32_t *out);

/* Enable / disable one interrupt. Out-of-range IRQ is EARLY_ENV. */
kido_status_t kido_gic_enable(uint32_t irq);
kido_status_t kido_gic_disable(uint32_t irq);

/* Priority for one interrupt (0 = highest, 0xFF = lowest; the
 * byte is written whole — the GIC implements the top bits).
 * Out-of-range IRQ is EARLY_ENV. */
kido_status_t kido_gic_set_priority(uint32_t irq, uint8_t prio);

/* CPU target mask for one SPI (bit n = CPU n; UP kernels pass
 * 0x01). SGI/PPI targets are architecturally fixed: EARLY_ENV.
 * A zero mask routes nowhere and is EARLY_ENV, not a silent
 * black hole. */
kido_status_t kido_gic_set_target(uint32_t irq, uint8_t cpu_mask);

/* Trigger mode for one SPI: KIDO_GIC_TRIG_LEVEL (0b00) or
 * KIDO_GIC_TRIG_EDGE (0b10). SGI/PPI config is fixed or
 * IMPLEMENTATION DEFINED: EARLY_ENV. Any other value is
 * EARLY_ENV. */
kido_status_t kido_gic_set_config(uint32_t irq, uint8_t trig);

/* Pending state of one interrupt (1 = pending). Software
 * trigger / clear through the set-pending / clear-pending
 * registers: trigger asserts without a device (useful for
 * self-test and for the future shell); clear withdraws it.
 * Out-of-range IRQ is EARLY_ENV. */
kido_status_t kido_gic_pending(uint32_t irq, uint8_t *out);
kido_status_t kido_gic_trigger(uint32_t irq);
kido_status_t kido_gic_clear_pending(uint32_t irq);

/* Send a software interrupt to the CPUs in cpu_mask (bit n =
 * CPU n; filter = explicit list only). sgi_id must be 0-15,
 * cpu_mask nonzero, else EARLY_ENV. */
kido_status_t kido_gic_send_sgi(uint8_t cpu_mask, uint8_t sgi_id);

/* Register (or unregister, fn = NULL) a handler for one
 * interrupt. Out-of-range IRQ is EARLY_ENV. The handler runs
 * in interrupt context; dispatch() still writes EOIR after
 * it returns. */
kido_status_t kido_gic_register_handler(uint32_t irq,
                                         kido_gic_handler_t fn,
                                         void *arg);

/* Acknowledge + dispatch one interrupt: read IAR, call the
 * registered handler if any, write EOIR with the full IAR
 * value. Spurious ID 1023 returns OK with no handler call
 * and no EOIR write. EARLY_ENV before init, or on a reserved
 * ID (1020-1022) after writing EOIR. This is what the future
 * vector stub calls from the IRQ entry. */
kido_status_t kido_gic_dispatch(void);

#endif /* KIDO_GIC_H */
