/*
 * kido-gic.c — Kido GICv2 interrupt controller driver (distributor
 * + CPU interface, UP, Group0 routing).
 *
 * See kido-gic.h for the register map, the honesty law, and the
 * declared futures. This file is the real logic: the hosted build
 * runs the SAME functions against a scripted GIC double (register
 * file + set/clear semantics + IAR arbitration) instead of MMIO.
 * The bare-metal path is WRITTEN, CROSS-COMPILED, and SGI-PROVEN
 * ON QEMU (scratch harness, /tmp only — see the ledger entry);
 * SPI delivery through a real device is NOT proven.
 *
 * TESTING: gcc -std=c11 -Wall -Wextra -Werror -DKIDO_HOSTED_TEST
 *        -DKIDO_GIC_SELFTEST kido-gic.c -o gic-selftest
 */

#include "kido-gic.h"

#ifdef KIDO_GIC_SELFTEST
#ifndef KIDO_HOSTED_TEST
#error "KIDO_GIC_SELFTEST needs KIDO_HOSTED_TEST."
#endif
#endif

/* ------------------------------------------------------------------ */
/* Registers (IHI 0048B).                                             */
/* ------------------------------------------------------------------ */
#define KIDO_GICD_CTLR_OFF      0x000u
#define KIDO_GICD_TYPER_OFF     0x004u
#define KIDO_GICD_ISENABLER_OFF 0x100u
#define KIDO_GICD_ICENABLER_OFF 0x180u
#define KIDO_GICD_ISPENDR_OFF   0x200u
#define KIDO_GICD_ICPENDR_OFF   0x280u
#define KIDO_GICD_ISACTIVER_OFF 0x300u
#define KIDO_GICD_ICACTIVER_OFF 0x380u
#define KIDO_GICD_IPRIORITYR_OFF 0x400u
#define KIDO_GICD_ITARGETSR_OFF 0x800u
#define KIDO_GICD_ICFGR_OFF     0xC00u
#define KIDO_GICD_SGIR_OFF      0xF00u

#define KIDO_GICC_CTLR_OFF 0x000u
#define KIDO_GICC_PMR_OFF  0x004u
#define KIDO_GICC_BPR_OFF  0x008u
#define KIDO_GICC_IAR_OFF  0x00Cu
#define KIDO_GICC_EOIR_OFF 0x010u

/* CTLR bits used here: EnableGrp0 = bit 0. FIQEn stays 0, so
 * Group0 signals IRQ, not FIQ. */
#define KIDO_GICC_CTLR_ENABLE_GRP0 0x1u

/* ------------------------------------------------------------------ */
/* Driver state. Static BSS: exists before any allocator, survives
 * MMU-off boot. The handler table is 1020 slots (the GICv2
 * source cap) of fn + arg — ~16 KiB on AArch64, stated in the
 * header, no allocator dependency by design. */
/* ------------------------------------------------------------------ */
static uint64_t kido_gic_dist_base = 0u;
static uint64_t kido_gic_cpu_base = 0u;
static uint32_t kido_gic_count = 0u;
static int      kido_gic_ready = 0;

typedef struct kido_gic_slot {
    kido_gic_handler_t fn;
    void *arg;
} kido_gic_slot_t;

static kido_gic_slot_t kido_gic_handlers[KIDO_GIC_MAX_SOURCES];

#if defined(KIDO_HOSTED_TEST)

/* ------------------------------------------------------------------ */
/* Hosted GIC double. A register file with the GIC's set/clear
 * semantics: ISENABLER/ICENABLER alias one enable word per
 * group, ISPENDR/ICPENDR alias one pending word, ISACTIVER/
 * ICACTIVER alias one active word. IPRIORITYR/ITARGETSR/ICFGR
 * are plain words (the driver does byte/field RMW on them).
 * IAR arbitrates: lowest priority value wins, lowest ID breaks
 * ties, among enabled + pending; the read clears pending and
 * sets active. EOIR clears active and is captured for the test.
 * The double models ONE CPU: an SGI to CPU0 pends, to other
 * CPUs it does not (UP by construction). */
/* ------------------------------------------------------------------ */
#include <stdio.h>

static uint32_t kido_dbl_plain[1024];     /* distributor words */
static uint32_t kido_dbl_cpu_plain[1024]; /* CPU interface words */
static uint32_t kido_dbl_enable[32];
static uint32_t kido_dbl_pending[32];
static uint32_t kido_dbl_active[32];
static uint32_t kido_dbl_typer = 4u; /* ITLinesNumber 4 -> 160 IRQs */
static uint32_t kido_dbl_eoir = 0u;
static unsigned kido_dbl_eoir_count = 0u;

static uint32_t kido_dbl_count(void)
{
    uint32_t n = ((kido_dbl_typer & 0x1Fu) + 1u) * 32u;
    return (n > KIDO_GIC_MAX_SOURCES) ? KIDO_GIC_MAX_SOURCES : n;
}

static uint32_t kido_dbl_prio(uint32_t irq)
{
    uint32_t w = kido_dbl_plain[(KIDO_GICD_IPRIORITYR_OFF / 4u) + irq / 4u];
    return (w >> ((irq % 4u) * 8u)) & 0xFFu;
}

static uint32_t kido_dbl_rd_dist(uint32_t off)
{
    if (off == KIDO_GICD_TYPER_OFF)
        return kido_dbl_typer;
    if (off >= KIDO_GICD_ISENABLER_OFF && off < 0x180u)
        return kido_dbl_enable[(off - KIDO_GICD_ISENABLER_OFF) / 4u];
    if (off >= KIDO_GICD_ICENABLER_OFF && off < 0x200u)
        return kido_dbl_enable[(off - KIDO_GICD_ICENABLER_OFF) / 4u];
    if (off >= KIDO_GICD_ISPENDR_OFF && off < 0x280u)
        return kido_dbl_pending[(off - KIDO_GICD_ISPENDR_OFF) / 4u];
    if (off >= KIDO_GICD_ICPENDR_OFF && off < 0x300u)
        return kido_dbl_pending[(off - KIDO_GICD_ICPENDR_OFF) / 4u];
    if (off >= KIDO_GICD_ISACTIVER_OFF && off < 0x380u)
        return kido_dbl_active[(off - KIDO_GICD_ISACTIVER_OFF) / 4u];
    if (off >= KIDO_GICD_ICACTIVER_OFF && off < 0x400u)
        return kido_dbl_active[(off - KIDO_GICD_ICACTIVER_OFF) / 4u];
    return kido_dbl_plain[off / 4u];
}

static void kido_dbl_wr_dist(uint32_t off, uint32_t v)
{
    uint32_t i;
    if (off >= KIDO_GICD_ISENABLER_OFF && off < 0x180u) {
        i = (off - KIDO_GICD_ISENABLER_OFF) / 4u;
        kido_dbl_enable[i] |= v;
        return;
    }
    if (off >= KIDO_GICD_ICENABLER_OFF && off < 0x200u) {
        i = (off - KIDO_GICD_ICENABLER_OFF) / 4u;
        kido_dbl_enable[i] &= ~v;
        return;
    }
    if (off >= KIDO_GICD_ISPENDR_OFF && off < 0x280u) {
        i = (off - KIDO_GICD_ISPENDR_OFF) / 4u;
        kido_dbl_pending[i] |= v;
        return;
    }
    if (off >= KIDO_GICD_ICPENDR_OFF && off < 0x300u) {
        i = (off - KIDO_GICD_ICPENDR_OFF) / 4u;
        kido_dbl_pending[i] &= ~v;
        return;
    }
    if (off >= KIDO_GICD_ISACTIVER_OFF && off < 0x380u) {
        i = (off - KIDO_GICD_ISACTIVER_OFF) / 4u;
        kido_dbl_active[i] |= v;
        return;
    }
    if (off >= KIDO_GICD_ICACTIVER_OFF && off < 0x400u) {
        i = (off - KIDO_GICD_ICACTIVER_OFF) / 4u;
        kido_dbl_active[i] &= ~v;
        return;
    }
    if (off == KIDO_GICD_SGIR_OFF) {
        /* Explicit target list only; UP double: CPU0 pends. */
        if ((v >> 16) & 0x1u)
            kido_dbl_pending[0] |= (1u << (v & 0xFu));
        return;
    }
    kido_dbl_plain[off / 4u] = v;
}

static uint32_t kido_dbl_rd_cpu(uint32_t off)
{
    uint32_t irq, best = KIDO_GIC_SPURIOUS_ID, best_prio = 0x100u;
    if (off != KIDO_GICC_IAR_OFF)
        return kido_dbl_cpu_plain[off / 4u];
    for (irq = 0u; irq < kido_dbl_count(); irq++) {
        uint32_t bit = 1u << (irq % 32u);
        uint32_t pr;
        if (!(kido_dbl_enable[irq / 32u] & bit))
            continue;
        if (!(kido_dbl_pending[irq / 32u] & bit))
            continue;
        pr = kido_dbl_prio(irq);
        if (pr < best_prio) {
            best_prio = pr;
            best = irq;
        }
    }
    if (best == KIDO_GIC_SPURIOUS_ID)
        return KIDO_GIC_SPURIOUS_ID;
    /* CPUID 0: the double's SGIs come from CPU0, SPIs carry 0. */
    kido_dbl_pending[best / 32u] &= ~(1u << (best % 32u));
    kido_dbl_active[best / 32u] |= (1u << (best % 32u));
    return best;
}

static void kido_dbl_wr_cpu(uint32_t off, uint32_t v)
{
    uint32_t id;
    if (off != KIDO_GICC_EOIR_OFF) {
        kido_dbl_cpu_plain[off / 4u] = v;
        return;
    }
    kido_dbl_eoir = v;
    kido_dbl_eoir_count++;
    id = v & 0x3FFu;
    if (id < KIDO_GIC_MAX_SOURCES)
        kido_dbl_active[id / 32u] &= ~(1u << (id % 32u));
}

#ifdef KIDO_GIC_SELFTEST
static void kido_gic_test_reset(void)
{
    unsigned i;
    for (i = 0u; i < 1024u; i++) {
        kido_dbl_plain[i] = 0u;
        kido_dbl_cpu_plain[i] = 0u;
    }
    for (i = 0u; i < 32u; i++) {
        kido_dbl_enable[i] = 0u;
        kido_dbl_pending[i] = 0u;
        kido_dbl_active[i] = 0u;
    }
    kido_dbl_typer = 4u;
    kido_dbl_eoir = 0u;
    kido_dbl_eoir_count = 0u;
}

static void kido_gic_test_set_typer_lines(uint32_t lines)
{
    kido_dbl_typer = lines & 0x1Fu;
}

static uint32_t kido_gic_test_rd_dist(uint32_t off)
{
    return kido_dbl_rd_dist(off);
}

static uint32_t kido_gic_test_rd_cpu(uint32_t off)
{
    return kido_dbl_rd_cpu(off);
}
#endif /* KIDO_GIC_SELFTEST */

static uint32_t kido_gic_rd_dist(uint64_t base, uint32_t off)
{
    (void)base; /* one modeled GIC; the driver checks base != 0 */
    return kido_dbl_rd_dist(off);
}

static void kido_gic_wr_dist(uint64_t base, uint32_t off, uint32_t v)
{
    (void)base;
    kido_dbl_wr_dist(off, v);
}

static uint32_t kido_gic_rd_cpu(uint64_t base, uint32_t off)
{
    (void)base;
    return kido_dbl_rd_cpu(off);
}

static void kido_gic_wr_cpu(uint64_t base, uint32_t off, uint32_t v)
{
    (void)base;
    kido_dbl_wr_cpu(off, v);
}

#else /* bare metal: real MMIO */

static uint32_t kido_gic_rd_dist(uint64_t base, uint32_t off)
{
    return *(volatile uint32_t *)(uintptr_t)(base + off);
}

static void kido_gic_wr_dist(uint64_t base, uint32_t off, uint32_t v)
{
    *(volatile uint32_t *)(uintptr_t)(base + off) = v;
}

static uint32_t kido_gic_rd_cpu(uint64_t base, uint32_t off)
{
    return *(volatile uint32_t *)(uintptr_t)(base + off);
}

static void kido_gic_wr_cpu(uint64_t base, uint32_t off, uint32_t v)
{
    *(volatile uint32_t *)(uintptr_t)(base + off) = v;
}

#endif /* KIDO_HOSTED_TEST */

/* ------------------------------------------------------------------ */
/* Internal helpers.                                                  */
/* ------------------------------------------------------------------ */
static int kido_gic_irq_ok(uint32_t irq)
{
    return kido_gic_ready && irq < kido_gic_count;
}

/* Byte field inside a 32-bit register (priority, target). */
static void kido_gic_wr_byte(uint64_t base, uint32_t reg, uint32_t irq,
                             uint8_t v, int is_dist)
{
    uint32_t off = reg + (irq / 4u) * 4u;
    uint32_t shift = (irq % 4u) * 8u;
    uint32_t w;
    if (is_dist) {
        w = kido_gic_rd_dist(base, off);
        w = (w & ~(0xFFu << shift)) | ((uint32_t)v << shift);
        kido_gic_wr_dist(base, off, w);
    } else {
        w = kido_gic_rd_cpu(base, off);
        w = (w & ~(0xFFu << shift)) | ((uint32_t)v << shift);
        kido_gic_wr_cpu(base, off, w);
    }
}

/* ------------------------------------------------------------------ */
/* Public API.                                                        */
/* ------------------------------------------------------------------ */
kido_status_t kido_gic_init(uint64_t dist_base, uint64_t cpu_base)
{
    uint32_t typer, lines, nwords, i, irq;
    if (dist_base == 0u || cpu_base == 0u)
        return KIDO_ERR_EARLY_ENV;
    kido_gic_dist_base = dist_base;
    kido_gic_cpu_base = cpu_base;
    typer = kido_gic_rd_dist(dist_base, KIDO_GICD_TYPER_OFF);
    lines = typer & 0x1Fu;
    kido_gic_count = (lines + 1u) * 32u;
    if (kido_gic_count > KIDO_GIC_MAX_SOURCES)
        kido_gic_count = KIDO_GIC_MAX_SOURCES;
    kido_gic_ready = 1;

    /* Distributor off, then configure, then CPU interface, then
     * distributor on (deliberation C9). */
    kido_gic_wr_dist(dist_base, KIDO_GICD_CTLR_OFF, 0u);
    nwords = (kido_gic_count + 31u) / 32u;
    for (i = 0u; i < nwords; i++) {
        kido_gic_wr_dist(dist_base,
                         KIDO_GICD_ICENABLER_OFF + i * 4u, 0xFFFFFFFFu);
        kido_gic_wr_dist(dist_base,
                         KIDO_GICD_ICPENDR_OFF + i * 4u, 0xFFFFFFFFu);
        kido_gic_wr_dist(dist_base,
                         KIDO_GICD_ICACTIVER_OFF + i * 4u, 0xFFFFFFFFu);
    }
    for (irq = KIDO_GIC_SPI_BASE; irq < kido_gic_count; irq++)
        kido_gic_wr_byte(dist_base, KIDO_GICD_ITARGETSR_OFF, irq, 0x01u, 1);
    kido_gic_wr_cpu(cpu_base, KIDO_GICC_PMR_OFF, 0xFFu);
    kido_gic_wr_cpu(cpu_base, KIDO_GICC_BPR_OFF, 0u);
    kido_gic_wr_cpu(cpu_base, KIDO_GICC_CTLR_OFF,
                    KIDO_GICC_CTLR_ENABLE_GRP0);
    kido_gic_wr_dist(dist_base, KIDO_GICD_CTLR_OFF,
                     KIDO_GICC_CTLR_ENABLE_GRP0);
    for (i = 0u; i < KIDO_GIC_MAX_SOURCES; i++) {
        kido_gic_handlers[i].fn = NULL;
        kido_gic_handlers[i].arg = NULL;
    }
    return KIDO_OK;
}

kido_status_t kido_gic_irq_count(uint32_t *out)
{
    if (!kido_gic_ready || out == NULL)
        return KIDO_ERR_EARLY_ENV;
    *out = kido_gic_count;
    return KIDO_OK;
}

kido_status_t kido_gic_enable(uint32_t irq)
{
    if (!kido_gic_irq_ok(irq))
        return KIDO_ERR_EARLY_ENV;
    kido_gic_wr_dist(kido_gic_dist_base,
                     KIDO_GICD_ISENABLER_OFF + (irq / 32u) * 4u,
                     1u << (irq % 32u));
    return KIDO_OK;
}

kido_status_t kido_gic_disable(uint32_t irq)
{
    if (!kido_gic_irq_ok(irq))
        return KIDO_ERR_EARLY_ENV;
    kido_gic_wr_dist(kido_gic_dist_base,
                     KIDO_GICD_ICENABLER_OFF + (irq / 32u) * 4u,
                     1u << (irq % 32u));
    return KIDO_OK;
}

kido_status_t kido_gic_set_priority(uint32_t irq, uint8_t prio)
{
    if (!kido_gic_irq_ok(irq))
        return KIDO_ERR_EARLY_ENV;
    kido_gic_wr_byte(kido_gic_dist_base, KIDO_GICD_IPRIORITYR_OFF,
                     irq, prio, 1);
    return KIDO_OK;
}

kido_status_t kido_gic_set_target(uint32_t irq, uint8_t cpu_mask)
{
    if (!kido_gic_irq_ok(irq) || irq < KIDO_GIC_SPI_BASE ||
        cpu_mask == 0u)
        return KIDO_ERR_EARLY_ENV;
    kido_gic_wr_byte(kido_gic_dist_base, KIDO_GICD_ITARGETSR_OFF,
                     irq, cpu_mask, 1);
    return KIDO_OK;
}

kido_status_t kido_gic_set_config(uint32_t irq, uint8_t trig)
{
    uint32_t off, shift, w;
    if (!kido_gic_irq_ok(irq) || irq < KIDO_GIC_SPI_BASE || trig > 1u)
        return KIDO_ERR_EARLY_ENV;
    off = KIDO_GICD_ICFGR_OFF + (irq / 16u) * 4u;
    shift = (irq % 16u) * 2u;
    w = kido_gic_rd_dist(kido_gic_dist_base, off);
    w = (w & ~(0x3u << shift)) | ((trig ? 0x2u : 0x0u) << shift);
    kido_gic_wr_dist(kido_gic_dist_base, off, w);
    return KIDO_OK;
}

kido_status_t kido_gic_pending(uint32_t irq, uint8_t *out)
{
    uint32_t w;
    if (!kido_gic_irq_ok(irq) || out == NULL)
        return KIDO_ERR_EARLY_ENV;
    w = kido_gic_rd_dist(kido_gic_dist_base,
                         KIDO_GICD_ISPENDR_OFF + (irq / 32u) * 4u);
    *out = (uint8_t)((w >> (irq % 32u)) & 0x1u);
    return KIDO_OK;
}

kido_status_t kido_gic_trigger(uint32_t irq)
{
    if (!kido_gic_irq_ok(irq))
        return KIDO_ERR_EARLY_ENV;
    kido_gic_wr_dist(kido_gic_dist_base,
                     KIDO_GICD_ISPENDR_OFF + (irq / 32u) * 4u,
                     1u << (irq % 32u));
    return KIDO_OK;
}

kido_status_t kido_gic_clear_pending(uint32_t irq)
{
    if (!kido_gic_irq_ok(irq))
        return KIDO_ERR_EARLY_ENV;
    kido_gic_wr_dist(kido_gic_dist_base,
                     KIDO_GICD_ICPENDR_OFF + (irq / 32u) * 4u,
                     1u << (irq % 32u));
    return KIDO_OK;
}

kido_status_t kido_gic_send_sgi(uint8_t cpu_mask, uint8_t sgi_id)
{
    uint32_t v;
    if (!kido_gic_ready || cpu_mask == 0u || sgi_id > KIDO_GIC_SGI_MAX)
        return KIDO_ERR_EARLY_ENV;
    /* Filter 0 (explicit list), NSATT 0: the SGI's group follows
     * the target's IGROUPR (reset Group0). */
    v = ((uint32_t)cpu_mask << 16) | (uint32_t)sgi_id;
    kido_gic_wr_dist(kido_gic_dist_base, KIDO_GICD_SGIR_OFF, v);
    return KIDO_OK;
}

kido_status_t kido_gic_register_handler(uint32_t irq,
                                         kido_gic_handler_t fn,
                                         void *arg)
{
    if (!kido_gic_irq_ok(irq))
        return KIDO_ERR_EARLY_ENV;
    kido_gic_handlers[irq].fn = fn;
    kido_gic_handlers[irq].arg = arg;
    return KIDO_OK;
}

kido_status_t kido_gic_dispatch(void)
{
    uint32_t iar, id;
    if (!kido_gic_ready)
        return KIDO_ERR_EARLY_ENV;
    iar = kido_gic_rd_cpu(kido_gic_cpu_base, KIDO_GICC_IAR_OFF);
    id = iar & 0x3FFu;
    if (id == KIDO_GIC_SPURIOUS_ID)
        return KIDO_OK; /* nothing pends: no handler, no EOIR */
    if (id >= KIDO_GIC_MAX_SOURCES) {
        /* Reserved 1020-1022: complete it, then report loud. */
        kido_gic_wr_cpu(kido_gic_cpu_base, KIDO_GICC_EOIR_OFF, iar);
        return KIDO_ERR_EARLY_ENV;
    }
    if (kido_gic_handlers[id].fn != NULL)
        kido_gic_handlers[id].fn(id, kido_gic_handlers[id].arg);
    /* Full IAR value: SGI EOIR needs the source-CPUID bits. */
    kido_gic_wr_cpu(kido_gic_cpu_base, KIDO_GICC_EOIR_OFF, iar);
    return KIDO_OK;
}

#if defined(KIDO_GIC_SELFTEST)

/* ------------------------------------------------------------------ */
/* Self-test.                                                          */
/* ------------------------------------------------------------------ */
static int kido_gic_checks = 0;
static int kido_gic_failures = 0;

#define GIC_CHECK(cond) do { \
    kido_gic_checks++; \
    if (!(cond)) { \
        kido_gic_failures++; \
        printf("GIC FAIL line %d: %s\n", __LINE__, #cond); \
    } \
} while (0)

static int kido_gic_h_calls = 0;
static uint32_t kido_gic_h_last = 0xFFFFFFFFu;
static int kido_gic_h_arg_hits = 0;
static uint32_t kido_gic_h_log[8];
static unsigned kido_gic_h_log_n = 0u;

static void kido_gic_test_handler(uint32_t irq, void *arg)
{
    kido_gic_h_calls++;
    kido_gic_h_last = irq;
    if (arg != NULL)
        kido_gic_h_arg_hits++;
    if (kido_gic_h_log_n < 8u)
        kido_gic_h_log[kido_gic_h_log_n++] = irq;
}

/* Byte / field readers for register-image pins (test only). */
static uint32_t kido_gic_test_byte(uint32_t reg, uint32_t irq)
{
    uint32_t w = kido_gic_test_rd_dist(reg + (irq / 4u) * 4u);
    return (w >> ((irq % 4u) * 8u)) & 0xFFu;
}

static uint32_t kido_gic_test_cfg(uint32_t irq)
{
    uint32_t w = kido_gic_test_rd_dist(KIDO_GICD_ICFGR_OFF +
                                       (irq / 16u) * 4u);
    return (w >> ((irq % 16u) * 2u)) & 0x3u;
}

int main(void)
{
    uint32_t count = 0u;
    uint8_t pend = 0u;
    int marker = 0;
    unsigned eoir_before;

    /* §1: guards before init, then init. */
    GIC_CHECK(kido_gic_dispatch() == KIDO_ERR_EARLY_ENV);
    GIC_CHECK(kido_gic_irq_count(&count) == KIDO_ERR_EARLY_ENV);
    GIC_CHECK(kido_gic_enable(33u) == KIDO_ERR_EARLY_ENV);
    GIC_CHECK(kido_gic_init(0u, 0u) == KIDO_ERR_EARLY_ENV);
    GIC_CHECK(kido_gic_init(KIDO_GIC_QEMU_VIRT_DIST_BASE, 0u) ==
              KIDO_ERR_EARLY_ENV);
    kido_gic_test_reset();
    GIC_CHECK(kido_gic_init(KIDO_GIC_QEMU_VIRT_DIST_BASE,
                            KIDO_GIC_QEMU_VIRT_CPU_BASE) == KIDO_OK);
    GIC_CHECK(kido_gic_irq_count(&count) == KIDO_OK);
    GIC_CHECK(count == 160u); /* TYPER lines 4 -> (4+1)*32 */

    /* §2: init register image. */
    GIC_CHECK(kido_gic_test_rd_dist(KIDO_GICD_CTLR_OFF) == 1u);
    GIC_CHECK(kido_gic_test_rd_cpu(KIDO_GICC_CTLR_OFF) == 1u);
    GIC_CHECK(kido_gic_test_rd_cpu(KIDO_GICC_PMR_OFF) == 0xFFu);
    GIC_CHECK(kido_gic_test_rd_cpu(KIDO_GICC_BPR_OFF) == 0u);
    GIC_CHECK(kido_gic_test_rd_dist(KIDO_GICD_ISENABLER_OFF) == 0u);
    GIC_CHECK(kido_gic_test_rd_dist(KIDO_GICD_ISENABLER_OFF + 4u) == 0u);
    GIC_CHECK(kido_gic_test_byte(KIDO_GICD_ITARGETSR_OFF, 33u) == 0x01u);
    GIC_CHECK(kido_gic_test_byte(KIDO_GICD_ITARGETSR_OFF, 159u) == 0x01u);

    /* §3: enable / disable + range. */
    GIC_CHECK(kido_gic_enable(33u) == KIDO_OK);
    GIC_CHECK((kido_gic_test_rd_dist(KIDO_GICD_ISENABLER_OFF + 4u) &
               (1u << 1)) != 0u);
    GIC_CHECK(kido_gic_disable(33u) == KIDO_OK);
    GIC_CHECK((kido_gic_test_rd_dist(KIDO_GICD_ISENABLER_OFF + 4u) &
               (1u << 1)) == 0u);
    GIC_CHECK(kido_gic_enable(160u) == KIDO_ERR_EARLY_ENV);
    GIC_CHECK(kido_gic_enable(1020u) == KIDO_ERR_EARLY_ENV);
    GIC_CHECK(kido_gic_disable(160u) == KIDO_ERR_EARLY_ENV);

    /* §4: priority byte RMW + neighbor pin. */
    GIC_CHECK(kido_gic_set_priority(33u, 0xA0u) == KIDO_OK);
    GIC_CHECK(kido_gic_test_byte(KIDO_GICD_IPRIORITYR_OFF, 33u) == 0xA0u);
    GIC_CHECK(kido_gic_test_byte(KIDO_GICD_IPRIORITYR_OFF, 34u) == 0x00u);
    GIC_CHECK(kido_gic_set_priority(160u, 0xA0u) == KIDO_ERR_EARLY_ENV);

    /* §5: target byte RMW + SGI/PPI/zero/range refusals. */
    GIC_CHECK(kido_gic_set_target(33u, 0x03u) == KIDO_OK);
    GIC_CHECK(kido_gic_test_byte(KIDO_GICD_ITARGETSR_OFF, 33u) == 0x03u);
    GIC_CHECK(kido_gic_test_byte(KIDO_GICD_ITARGETSR_OFF, 34u) == 0x01u);
    GIC_CHECK(kido_gic_set_target(0u, 0x01u) == KIDO_ERR_EARLY_ENV);
    GIC_CHECK(kido_gic_set_target(16u, 0x01u) == KIDO_ERR_EARLY_ENV);
    GIC_CHECK(kido_gic_set_target(33u, 0u) == KIDO_ERR_EARLY_ENV);
    GIC_CHECK(kido_gic_set_target(160u, 0x01u) == KIDO_ERR_EARLY_ENV);

    /* §6: config 2-bit RMW + refusals. */
    GIC_CHECK(kido_gic_set_config(33u, KIDO_GIC_TRIG_EDGE) == KIDO_OK);
    GIC_CHECK(kido_gic_test_cfg(33u) == 0x2u);
    GIC_CHECK(kido_gic_set_config(33u, KIDO_GIC_TRIG_LEVEL) == KIDO_OK);
    GIC_CHECK(kido_gic_test_cfg(33u) == 0x0u);
    GIC_CHECK(kido_gic_test_cfg(34u) == 0x0u);
    GIC_CHECK(kido_gic_set_config(0u, KIDO_GIC_TRIG_EDGE) ==
              KIDO_ERR_EARLY_ENV);
    GIC_CHECK(kido_gic_set_config(33u, 2u) == KIDO_ERR_EARLY_ENV);

    /* §7: pending / trigger / clear + enable-gated delivery. */
    GIC_CHECK(kido_gic_pending(33u, &pend) == KIDO_OK);
    GIC_CHECK(pend == 0u);
    GIC_CHECK(kido_gic_trigger(33u) == KIDO_OK);
    GIC_CHECK(kido_gic_pending(33u, &pend) == KIDO_OK);
    GIC_CHECK(pend == 1u);
    GIC_CHECK(kido_gic_clear_pending(33u) == KIDO_OK);
    GIC_CHECK(kido_gic_pending(33u, &pend) == KIDO_OK);
    GIC_CHECK(pend == 0u);
    GIC_CHECK(kido_gic_pending(33u, NULL) == KIDO_ERR_EARLY_ENV);
    GIC_CHECK(kido_gic_trigger(160u) == KIDO_ERR_EARLY_ENV);
    /* Pending but not enabled: dispatch stays spurious. */
    eoir_before = kido_dbl_eoir_count;
    GIC_CHECK(kido_gic_trigger(35u) == KIDO_OK);
    GIC_CHECK(kido_gic_dispatch() == KIDO_OK);
    GIC_CHECK(kido_dbl_eoir_count == eoir_before);
    GIC_CHECK(kido_gic_pending(35u, &pend) == KIDO_OK);
    GIC_CHECK(pend == 1u);
    GIC_CHECK(kido_gic_clear_pending(35u) == KIDO_OK);

    /* §8: handlerless dispatch completes + spurious no-op. */
    GIC_CHECK(kido_gic_enable(34u) == KIDO_OK);
    GIC_CHECK(kido_gic_trigger(34u) == KIDO_OK);
    GIC_CHECK(kido_gic_dispatch() == KIDO_OK);
    GIC_CHECK(kido_dbl_eoir == 34u);
    GIC_CHECK(kido_dbl_eoir_count == eoir_before + 1u);
    GIC_CHECK(kido_gic_pending(34u, &pend) == KIDO_OK);
    GIC_CHECK(pend == 0u);
    eoir_before = kido_dbl_eoir_count;
    GIC_CHECK(kido_gic_dispatch() == KIDO_OK); /* spurious */
    GIC_CHECK(kido_dbl_eoir_count == eoir_before);

    /* §9: handler path. */
    GIC_CHECK(kido_gic_register_handler(33u, kido_gic_test_handler,
                                        &marker) == KIDO_OK);
    GIC_CHECK(kido_gic_enable(33u) == KIDO_OK);
    GIC_CHECK(kido_gic_trigger(33u) == KIDO_OK);
    GIC_CHECK(kido_gic_dispatch() == KIDO_OK);
    GIC_CHECK(kido_gic_h_calls == 1);
    GIC_CHECK(kido_gic_h_last == 33u);
    GIC_CHECK(kido_gic_h_arg_hits == 1);
    GIC_CHECK(kido_dbl_eoir == 33u);
    GIC_CHECK(kido_gic_pending(33u, &pend) == KIDO_OK);
    GIC_CHECK(pend == 0u);
    GIC_CHECK(kido_gic_register_handler(33u, NULL, NULL) == KIDO_OK);
    GIC_CHECK(kido_gic_register_handler(160u, kido_gic_test_handler,
                                        NULL) == KIDO_ERR_EARLY_ENV);

    /* §10: SGI send -> pending -> dispatch -> EOIR. */
    GIC_CHECK(kido_gic_register_handler(0u, kido_gic_test_handler,
                                        NULL) == KIDO_OK);
    GIC_CHECK(kido_gic_enable(0u) == KIDO_OK);
    GIC_CHECK(kido_gic_send_sgi(0x01u, 0u) == KIDO_OK);
    GIC_CHECK(kido_gic_pending(0u, &pend) == KIDO_OK);
    GIC_CHECK(pend == 1u);
    GIC_CHECK(kido_gic_dispatch() == KIDO_OK);
    GIC_CHECK(kido_gic_h_last == 0u);
    GIC_CHECK(kido_dbl_eoir == 0u); /* CPUID 0, full IAR echo */
    GIC_CHECK(kido_gic_send_sgi(0u, 0u) == KIDO_ERR_EARLY_ENV);
    GIC_CHECK(kido_gic_send_sgi(0x01u, 16u) == KIDO_ERR_EARLY_ENV);

    /* §11: priority arbitration — lower value wins. */
    kido_gic_h_log_n = 0u;
    GIC_CHECK(kido_gic_register_handler(40u, kido_gic_test_handler,
                                        NULL) == KIDO_OK);
    GIC_CHECK(kido_gic_register_handler(41u, kido_gic_test_handler,
                                        NULL) == KIDO_OK);
    GIC_CHECK(kido_gic_set_priority(40u, 0x20u) == KIDO_OK);
    GIC_CHECK(kido_gic_set_priority(41u, 0x10u) == KIDO_OK);
    GIC_CHECK(kido_gic_enable(40u) == KIDO_OK);
    GIC_CHECK(kido_gic_enable(41u) == KIDO_OK);
    GIC_CHECK(kido_gic_trigger(40u) == KIDO_OK);
    GIC_CHECK(kido_gic_trigger(41u) == KIDO_OK);
    GIC_CHECK(kido_gic_dispatch() == KIDO_OK);
    GIC_CHECK(kido_gic_dispatch() == KIDO_OK);
    GIC_CHECK(kido_gic_h_log_n == 2u);
    GIC_CHECK(kido_gic_h_log[0] == 41u);
    GIC_CHECK(kido_gic_h_log[1] == 40u);

    /* §12: re-init clears handlers but keeps dispatch working. */
    GIC_CHECK(kido_gic_register_handler(33u, kido_gic_test_handler,
                                        NULL) == KIDO_OK);
    GIC_CHECK(kido_gic_init(KIDO_GIC_QEMU_VIRT_DIST_BASE,
                            KIDO_GIC_QEMU_VIRT_CPU_BASE) == KIDO_OK);
    {
        int calls_before = kido_gic_h_calls;
        GIC_CHECK(kido_gic_enable(33u) == KIDO_OK);
        GIC_CHECK(kido_gic_trigger(33u) == KIDO_OK);
        GIC_CHECK(kido_gic_dispatch() == KIDO_OK);
        GIC_CHECK(kido_gic_h_calls == calls_before);
        GIC_CHECK(kido_dbl_eoir == 33u);
    }

    /* §13: TYPER derivation — lines 0 means SGI+PPI only. */
    kido_gic_test_set_typer_lines(0u);
    GIC_CHECK(kido_gic_init(KIDO_GIC_QEMU_VIRT_DIST_BASE,
                            KIDO_GIC_QEMU_VIRT_CPU_BASE) == KIDO_OK);
    GIC_CHECK(kido_gic_irq_count(&count) == KIDO_OK);
    GIC_CHECK(count == 32u);
    GIC_CHECK(kido_gic_enable(32u) == KIDO_ERR_EARLY_ENV);
    kido_gic_test_set_typer_lines(4u);
    GIC_CHECK(kido_gic_init(KIDO_GIC_QEMU_VIRT_DIST_BASE,
                            KIDO_GIC_QEMU_VIRT_CPU_BASE) == KIDO_OK);
    GIC_CHECK(kido_gic_irq_count(&count) == KIDO_OK);
    GIC_CHECK(count == 160u);

    printf("kido-gic self-test: %d checks, %d failures\n",
           kido_gic_checks, kido_gic_failures);
    return (kido_gic_failures == 0) ? 0 : 1;
}

#endif /* KIDO_GIC_SELFTEST */
