/*
 * kido-serial-irq.c — Kido interrupt-driven PL011 RX.
 *
 * A GIC handler drains the UART RX FIFO into a static ring.
 * See kido-serial-irq.h for the register window, the init order
 * law, and the honesty law.
 *
 * WHAT IS REAL vs DOUBLE: the handler, ring, and GIC calls below
 * are the real logic — the hosted build runs the SAME functions
 * against a scripted UART double (scratch registers + 16-deep RX
 * FIFO) instead of MMIO, and against the real kido-gic.c (whose
 * own double models the distributor/CPU interface). The
 * bare-metal path is WRITTEN, NOT EXECUTED (no cross toolchain
 * this session, 13th data point; no QEMU run — N8toriousAi's witness).
 *
 * TESTING: gcc -std=c11 -Wall -Wextra -Werror -DKIDO_HOSTED_TEST
 *        -DKIDO_SERIAL_IRQ_SELFTEST kido-serial-irq.c kido-gic.c
 *        -o serial-irq-selftest
 * The test drives the chain through PUBLIC GIC API only
 * (init / trigger / dispatch / enable / disable); the UART side
 * uses this file's own double.
 */

#include "kido-serial-irq.h"

/* ------------------------------------------------------------------ */
/* Registers (PL011 TRM, DDI 0183 — the IRQ window only).             */
/* ------------------------------------------------------------------ */
#define KIDO_SIRQ_DR_OFF   0x00u
#define KIDO_SIRQ_RSR_OFF  0x04u /* read: status; write: error clear */
#define KIDO_SIRQ_FR_OFF   0x18u
#define KIDO_SIRQ_IFLS_OFF 0x34u
#define KIDO_SIRQ_IMSC_OFF 0x38u
#define KIDO_SIRQ_MIS_OFF  0x40u
#define KIDO_SIRQ_ICR_OFF  0x44u

/* FR bits. */
#define KIDO_SIRQ_FR_RXFE (1u << 4)

/* DR error bits (OE/BE/PE/FE, bits 11:8). */
#define KIDO_SIRQ_DR_ERR_MASK 0xF00u

/* Interrupt bits: RXIM (IMSC), RXMIS (MIS), RXIC (ICR). */
#define KIDO_SIRQ_RX_INT (1u << 4)

/* IFLS RX trigger: bits 2:0, 001 = interrupt at 1/4 full. */
#define KIDO_SIRQ_IFLS_RX_MASK 0x07u
#define KIDO_SIRQ_IFLS_RX_QUARTER 0x01u

/* Hardware FIFO depth: the handler's per-invocation drain bound. */
#define KIDO_SIRQ_FIFO_DEPTH 16u

#if defined(KIDO_HOSTED_TEST)

/* ------------------------------------------------------------------ */
/* Hosted UART double. Scratch registers + 16-deep RX FIFO. The     */
/* double models ONE port; base is ignored except for the 0 check  */
/* the module itself performs before touching registers. MIS bit 4 */
/* is computed, never stored: raw RX status (FIFO at/above the    */
/* 1/4 trigger) ANDed with the IMSC mask — the real MIS semantic.  */
/* ------------------------------------------------------------------ */
#include <stdio.h>

static uint32_t kido_dbl_ifls = 0u;
static uint32_t kido_dbl_imsc = 0u;
static uint32_t kido_dbl_icr = 0u;
static int      kido_dbl_ecr_cleared = 0;

static uint8_t  kido_dbl_rx[KIDO_SIRQ_FIFO_DEPTH];
static uint32_t kido_dbl_rx_err[KIDO_SIRQ_FIFO_DEPTH];
static unsigned kido_dbl_rx_head = 0u;
static unsigned kido_dbl_rx_count = 0u;

#ifdef KIDO_SERIAL_IRQ_SELFTEST
static void kido_serial_irq_test_reset(void)
{
    kido_dbl_ifls = 0u;
    kido_dbl_imsc = 0u;
    kido_dbl_icr = 0u;
    kido_dbl_ecr_cleared = 0;
    kido_dbl_rx_head = 0u;
    kido_dbl_rx_count = 0u;
}
#endif /* KIDO_SERIAL_IRQ_SELFTEST */

#ifdef KIDO_SERIAL_IRQ_SELFTEST
static void kido_serial_irq_test_feed(uint8_t byte, uint32_t errbits)
{
    unsigned slot;
    if (kido_dbl_rx_count >= KIDO_SIRQ_FIFO_DEPTH)
        return; /* FIFO full: the double drops, the test never does */
    slot = (kido_dbl_rx_head + kido_dbl_rx_count) % KIDO_SIRQ_FIFO_DEPTH;
    kido_dbl_rx[slot] = byte;
    kido_dbl_rx_err[slot] = errbits;
    kido_dbl_rx_count++;
}
#endif /* KIDO_SERIAL_IRQ_SELFTEST */

static uint32_t kido_serial_irq_rd(uint64_t base, uint32_t off)
{
    uint32_t v;
    (void)base; /* one modeled port; the module checks base != 0 */
    if (off == KIDO_SIRQ_FR_OFF) {
        v = 0u;
        if (kido_dbl_rx_count == 0u)
            v |= KIDO_SIRQ_FR_RXFE;
        return v;
    }
    if (off == KIDO_SIRQ_DR_OFF) {
        uint8_t byte;
        uint32_t err;
        if (kido_dbl_rx_count == 0u)
            return 0u; /* handler guards with RXFE; never reached */
        byte = kido_dbl_rx[kido_dbl_rx_head];
        err = kido_dbl_rx_err[kido_dbl_rx_head];
        kido_dbl_rx_head = (kido_dbl_rx_head + 1u) % KIDO_SIRQ_FIFO_DEPTH;
        kido_dbl_rx_count--;
        return ((uint32_t)byte) | err;
    }
    if (off == KIDO_SIRQ_IFLS_OFF)
        return kido_dbl_ifls;
    if (off == KIDO_SIRQ_IMSC_OFF)
        return kido_dbl_imsc;
    if (off == KIDO_SIRQ_MIS_OFF) {
        /* Raw RX status: FIFO at/above the 1/4 trigger (4 bytes);
         * MIS = raw AND mask, as on hardware. */
        if ((kido_dbl_imsc & KIDO_SIRQ_RX_INT) != 0u &&
            kido_dbl_rx_count >= 4u)
            return KIDO_SIRQ_RX_INT;
        return 0u;
    }
    if (off == KIDO_SIRQ_ICR_OFF)
        return kido_dbl_icr;
    return 0u;
}

static void kido_serial_irq_wr(uint64_t base, uint32_t off, uint32_t val)
{
    (void)base; /* one modeled port */
    if (off == KIDO_SIRQ_IFLS_OFF) {
        kido_dbl_ifls = val;
        return;
    }
    if (off == KIDO_SIRQ_IMSC_OFF) {
        kido_dbl_imsc = val;
        return;
    }
    if (off == KIDO_SIRQ_ICR_OFF) {
        kido_dbl_icr = val;
        return;
    }
    if (off == KIDO_SIRQ_RSR_OFF)
        kido_dbl_ecr_cleared = 1; /* any ECR write clears errors */
}

#else /* bare metal */

/* Real MMIO. Volatile: the compiler must not reorder or elide the
 * status polls. */
static uint32_t kido_serial_irq_rd(uint64_t base, uint32_t off)
{
    return *(volatile uint32_t *)(uintptr_t)(base + off);
}

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

#endif /* KIDO_HOSTED_TEST */

/* ------------------------------------------------------------------ */
/* Module state: one port, static, never allocated.                    */
/* ------------------------------------------------------------------ */
static uint64_t s_base = 0u;
static uint32_t s_irq = 0u;
static int      s_ready = 0;

static char     s_ring[KIDO_SERIAL_IRQ_RING_DEPTH];
static unsigned s_ring_head = 0u;
static unsigned s_ring_count = 0u;

static kido_serial_irq_stats_t s_stats;

/* The handler. Runs in interrupt context (from the vec stub via
 * kido_gic_dispatch): short, bounded, no blocking, no allocator.
 * Drains until RXFE or the FIFO-depth bound; error bytes are
 * discarded + counted; a full ring drops bytes + counted; the
 * ICR clear runs even on an empty drain (a spurious invocation
 * must not leave a stale interrupt asserted). */
static void kido_serial_irq_handler(uint32_t irq, void *arg)
{
    unsigned i;
    int drained = 0;
    (void)arg; /* single port: state is module-global (see C4) */

    s_stats.handler_runs++;
    if (!s_ready || irq != s_irq) {
        s_stats.spurious_runs++;
        return;
    }
    for (i = 0u; i < KIDO_SIRQ_FIFO_DEPTH; i++) {
        uint32_t v;
        if ((kido_serial_irq_rd(s_base, KIDO_SIRQ_FR_OFF) &
             KIDO_SIRQ_FR_RXFE) != 0u)
            break; /* FIFO empty: drain complete */
        v = kido_serial_irq_rd(s_base, KIDO_SIRQ_DR_OFF);
        drained = 1;
        if ((v & KIDO_SIRQ_DR_ERR_MASK) != 0u) {
            /* Corrupt byte: clear the error, deliver nothing. */
            kido_serial_irq_wr(s_base, KIDO_SIRQ_RSR_OFF, 0xFFu);
            s_stats.errors++;
            continue;
        }
        if (s_ring_count >= KIDO_SERIAL_IRQ_RING_DEPTH) {
            s_stats.dropped++;
            continue;
        }
        s_ring[(s_ring_head + s_ring_count) %
               KIDO_SERIAL_IRQ_RING_DEPTH] = (char)(v & 0xFFu);
        s_ring_count++;
        s_stats.received++;
    }
    /* Clear the RX interrupt source at the UART, always. */
    kido_serial_irq_wr(s_base, KIDO_SIRQ_ICR_OFF, KIDO_SIRQ_RX_INT);
    if (!drained)
        s_stats.spurious_runs++;
}

kido_status_t kido_serial_irq_init(uint64_t base, uint32_t irq)
{
    kido_status_t st;
    uint32_t v;

    if (base == 0u || s_ready)
        return KIDO_ERR_EARLY_ENV;
    /* GIC first: handler before enable before unmask (init order
     * law). Any GIC failure leaves this module uninitialized and
     * no UART register touched. */
    st = kido_gic_register_handler(irq, kido_serial_irq_handler, NULL);
    if (st != KIDO_OK)
        return st;
    st = kido_gic_set_config(irq, KIDO_GIC_TRIG_LEVEL);
    if (st != KIDO_OK) {
        kido_gic_register_handler(irq, NULL, NULL);
        return st;
    }
    st = kido_gic_enable(irq);
    if (st != KIDO_OK) {
        kido_gic_register_handler(irq, NULL, NULL);
        return st;
    }
    /* UART last: trigger level, then unmask, then clear stale. */
    v = kido_serial_irq_rd(base, KIDO_SIRQ_IFLS_OFF);
    v = (v & ~KIDO_SIRQ_IFLS_RX_MASK) | KIDO_SIRQ_IFLS_RX_QUARTER;
    kido_serial_irq_wr(base, KIDO_SIRQ_IFLS_OFF, v);
    v = kido_serial_irq_rd(base, KIDO_SIRQ_IMSC_OFF);
    kido_serial_irq_wr(base, KIDO_SIRQ_IMSC_OFF,
                       v | KIDO_SIRQ_RX_INT);
    kido_serial_irq_wr(base, KIDO_SIRQ_ICR_OFF, KIDO_SIRQ_RX_INT);
    s_base = base;
    s_irq = irq;
    s_ready = 1;
    return KIDO_OK;
}

kido_status_t kido_serial_irq_stop(void)
{
    kido_status_t st;
    uint32_t v;

    if (!s_ready)
        return KIDO_ERR_EARLY_ENV;
    /* Reverse of init: mask UART, disable GIC, unregister. The
     * ring is kept (stop ends delivery, not history — see C6). */
    v = kido_serial_irq_rd(s_base, KIDO_SIRQ_IMSC_OFF);
    kido_serial_irq_wr(s_base, KIDO_SIRQ_IMSC_OFF,
                       v & ~KIDO_SIRQ_RX_INT);
    st = kido_gic_disable(s_irq);
    if (st != KIDO_OK)
        return st;
    st = kido_gic_register_handler(s_irq, NULL, NULL);
    if (st != KIDO_OK)
        return st;
    s_ready = 0;
    return KIDO_OK;
}

kido_status_t kido_serial_irq_available(uint32_t *out)
{
    if (!s_ready || out == NULL)
        return KIDO_ERR_EARLY_ENV;
    *out = s_ring_count;
    return KIDO_OK;
}

kido_status_t kido_serial_irq_getc(char *out)
{
    if (!s_ready || out == NULL)
        return KIDO_ERR_EARLY_ENV;
    if (s_ring_count == 0u)
        return KIDO_ERR_EARLY_ENV; /* empty ring: caller checks first */
    *out = s_ring[s_ring_head];
    s_ring_head = (s_ring_head + 1u) % KIDO_SERIAL_IRQ_RING_DEPTH;
    s_ring_count--;
    return KIDO_OK;
}

kido_status_t kido_serial_irq_stats(kido_serial_irq_stats_t *out)
{
    if (!s_ready || out == NULL)
        return KIDO_ERR_EARLY_ENV;
    *out = s_stats;
    return KIDO_OK;
}

/* ------------------------------------------------------------------ */
/* Self-test: drives the real dispatch chain (GIC trigger ->       */
/* dispatch -> handler -> ring) through public GIC API, against    */
/* this file's UART double.                                        */
/* ------------------------------------------------------------------ */
#ifdef KIDO_SERIAL_IRQ_SELFTEST
#ifndef KIDO_HOSTED_TEST
#error "KIDO_SERIAL_IRQ_SELFTEST needs KIDO_HOSTED_TEST (it runs the hosted double)."
#endif

#define KIDO_SIRQ_BASE 0x09000000u /* the modeled port's address */

int main(void)
{
    int failures = 0;
    int checks = 0;
    uint32_t n = 0u;
    char c = '\0';
    kido_serial_irq_stats_t st;
    unsigned i;

#define KIDO_SIRQ_CHECK(cond, msg) do { \
    checks++; \
    if (!(cond)) { printf("[FAIL] " msg "\n"); failures++; } \
} while (0)

    /* A. Guards before init: nothing works, all loud. */
    KIDO_SIRQ_CHECK(kido_serial_irq_available(&n) ==
                    KIDO_ERR_EARLY_ENV, "available pre-init not refused");
    KIDO_SIRQ_CHECK(kido_serial_irq_getc(&c) == KIDO_ERR_EARLY_ENV,
                    "getc pre-init not refused");
    KIDO_SIRQ_CHECK(kido_serial_irq_stats(&st) == KIDO_ERR_EARLY_ENV,
                    "stats pre-init not refused");
    KIDO_SIRQ_CHECK(kido_serial_irq_stop() == KIDO_ERR_EARLY_ENV,
                    "stop pre-init not refused");
    KIDO_SIRQ_CHECK(kido_serial_irq_init(0u,
                    KIDO_SERIAL_IRQ_QEMU_VIRT_IRQ) ==
                    KIDO_ERR_EARLY_ENV, "init base 0 not refused");
    /* GIC not initialized yet: registration must fail loud, and
     * no UART register may have been touched by the attempt. */
    kido_serial_irq_test_reset();
    KIDO_SIRQ_CHECK(kido_serial_irq_init(KIDO_SIRQ_BASE,
                    KIDO_SERIAL_IRQ_QEMU_VIRT_IRQ) ==
                    KIDO_ERR_EARLY_ENV, "init pre-GIC not refused");
    KIDO_SIRQ_CHECK(kido_dbl_imsc == 0u,
                    "failed init touched IMSC");
    KIDO_SIRQ_CHECK(kido_dbl_ifls == 0u,
                    "failed init touched IFLS");

    /* B. Init image: handler registered, level config, enabled,
     * UART unmasked with a 1/4 trigger, stale interrupt cleared. */
    KIDO_SIRQ_CHECK(kido_gic_init(KIDO_GIC_QEMU_VIRT_DIST_BASE,
                                  KIDO_GIC_QEMU_VIRT_CPU_BASE) ==
                    KIDO_OK, "gic init failed");
    KIDO_SIRQ_CHECK(kido_serial_irq_init(KIDO_SIRQ_BASE, 31u) ==
                    KIDO_ERR_EARLY_ENV, "PPI irq 31 not refused");
    KIDO_SIRQ_CHECK(kido_serial_irq_init(KIDO_SIRQ_BASE, 160u) ==
                    KIDO_ERR_EARLY_ENV, "out-of-range irq not refused");
    KIDO_SIRQ_CHECK(kido_serial_irq_init(KIDO_SIRQ_BASE,
                    KIDO_SERIAL_IRQ_QEMU_VIRT_IRQ) == KIDO_OK,
                    "init 33 failed");
    KIDO_SIRQ_CHECK(kido_dbl_imsc == KIDO_SIRQ_RX_INT,
                    "IMSC RXIM not set");
    KIDO_SIRQ_CHECK((kido_dbl_ifls & KIDO_SIRQ_IFLS_RX_MASK) ==
                    KIDO_SIRQ_IFLS_RX_QUARTER, "IFLS RX trigger not 1/4");
    KIDO_SIRQ_CHECK(kido_dbl_icr == KIDO_SIRQ_RX_INT,
                    "ICR RXIC not written at init");
    KIDO_SIRQ_CHECK(kido_serial_irq_init(KIDO_SIRQ_BASE,
                    KIDO_SERIAL_IRQ_QEMU_VIRT_IRQ) ==
                    KIDO_ERR_EARLY_ENV, "double init not refused");
    KIDO_SIRQ_CHECK(kido_serial_irq_available(&n) == KIDO_OK &&
                    n == 0u, "available not 0 after init");
    KIDO_SIRQ_CHECK(kido_serial_irq_getc(&c) == KIDO_ERR_EARLY_ENV,
                    "getc on empty ring not loud");

    /* C. Delivery through the real chain: feed -> trigger ->
     * dispatch -> handler -> ring, in order. */
    kido_serial_irq_test_feed((uint8_t)'H', 0u);
    kido_serial_irq_test_feed((uint8_t)'i', 0u);
    KIDO_SIRQ_CHECK(kido_gic_trigger(KIDO_SERIAL_IRQ_QEMU_VIRT_IRQ) ==
                    KIDO_OK, "gic trigger 33 failed");
    KIDO_SIRQ_CHECK(kido_gic_dispatch() == KIDO_OK,
                    "gic dispatch failed");
    KIDO_SIRQ_CHECK(kido_serial_irq_available(&n) == KIDO_OK &&
                    n == 2u, "ring count not 2 after dispatch");
    KIDO_SIRQ_CHECK(kido_serial_irq_getc(&c) == KIDO_OK && c == 'H',
                    "ring byte 0 not H");
    KIDO_SIRQ_CHECK(kido_serial_irq_getc(&c) == KIDO_OK && c == 'i',
                    "ring byte 1 not i");
    KIDO_SIRQ_CHECK(kido_serial_irq_available(&n) == KIDO_OK &&
                    n == 0u, "ring not empty after drain");
    KIDO_SIRQ_CHECK(kido_serial_irq_stats(&st) == KIDO_OK &&
                    st.received == 2u && st.handler_runs == 1u &&
                    st.dropped == 0u && st.errors == 0u &&
                    st.spurious_runs == 0u, "stats wrong after C");

    /* D. MIS observation: 4 bytes reach the 1/4 trigger, so the
     * masked status bit reads set before the dispatch. */
    kido_serial_irq_test_feed((uint8_t)'A', 0u);
    kido_serial_irq_test_feed((uint8_t)'B', 0u);
    kido_serial_irq_test_feed((uint8_t)'C', 0u);
    KIDO_SIRQ_CHECK(kido_serial_irq_rd(KIDO_SIRQ_BASE,
                    KIDO_SIRQ_MIS_OFF) == 0u,
                    "MIS set below trigger");
    kido_serial_irq_test_feed((uint8_t)'D', 0u);
    KIDO_SIRQ_CHECK(kido_serial_irq_rd(KIDO_SIRQ_BASE,
                    KIDO_SIRQ_MIS_OFF) == KIDO_SIRQ_RX_INT,
                    "MIS not set at trigger");
    KIDO_SIRQ_CHECK(kido_gic_trigger(KIDO_SERIAL_IRQ_QEMU_VIRT_IRQ) ==
                    KIDO_OK, "gic trigger 33 (D) failed");
    KIDO_SIRQ_CHECK(kido_gic_dispatch() == KIDO_OK,
                    "gic dispatch (D) failed");
    KIDO_SIRQ_CHECK(kido_serial_irq_available(&n) == KIDO_OK &&
                    n == 4u, "ring count not 4 after D");
    /* Drain the D bytes so later sections start clean. */
    for (i = 0u; i < 4u; i++)
        KIDO_SIRQ_CHECK(kido_serial_irq_getc(&c) == KIDO_OK,
                        "drain D failed");

    /* E. Error byte: OE set -> discarded, ECR cleared, counted,
     * and the following good byte still delivered. */
    kido_serial_irq_test_feed((uint8_t)'X', 0x800u); /* OE, bit 11 */
    kido_serial_irq_test_feed((uint8_t)'Y', 0u);
    KIDO_SIRQ_CHECK(kido_gic_trigger(KIDO_SERIAL_IRQ_QEMU_VIRT_IRQ) ==
                    KIDO_OK, "gic trigger 33 (E) failed");
    KIDO_SIRQ_CHECK(kido_gic_dispatch() == KIDO_OK,
                    "gic dispatch (E) failed");
    KIDO_SIRQ_CHECK(kido_dbl_ecr_cleared == 1, "ECR not cleared on OE");
    KIDO_SIRQ_CHECK(kido_serial_irq_available(&n) == KIDO_OK &&
                    n == 1u, "ring count not 1 after OE (X leaked?)");
    KIDO_SIRQ_CHECK(kido_serial_irq_getc(&c) == KIDO_OK && c == 'Y',
                    "byte after OE not Y");
    KIDO_SIRQ_CHECK(kido_serial_irq_stats(&st) == KIDO_OK &&
                    st.errors == 1u, "error count not 1");

    /* F. Ring full: 17 dispatches x 16 bytes = 272 offered to a
     * 256-deep ring -> 256 received, 16 dropped, order kept. */
    for (i = 0u; i < 17u; i++) {
        unsigned j;
        for (j = 0u; j < 16u; j++)
            kido_serial_irq_test_feed((uint8_t)('a' + (j % 26u)), 0u);
        KIDO_SIRQ_CHECK(kido_gic_trigger(
                        KIDO_SERIAL_IRQ_QEMU_VIRT_IRQ) == KIDO_OK,
                        "gic trigger 33 (F) failed");
        KIDO_SIRQ_CHECK(kido_gic_dispatch() == KIDO_OK,
                        "gic dispatch (F) failed");
    }
    KIDO_SIRQ_CHECK(kido_serial_irq_available(&n) == KIDO_OK &&
                    n == 256u, "ring not full (256) after F");
    KIDO_SIRQ_CHECK(kido_serial_irq_stats(&st) == KIDO_OK &&
                    st.dropped == 16u, "drop count not 16");
    KIDO_SIRQ_CHECK(kido_serial_irq_getc(&c) == KIDO_OK && c == 'a',
                    "ring head not 'a' after F");
    /* Drain the rest so the stop section starts from a known state. */
    while (kido_serial_irq_available(&n) == KIDO_OK && n > 0u)
        KIDO_SIRQ_CHECK(kido_serial_irq_getc(&c) == KIDO_OK,
                        "drain F failed");

    /* G. Spurious invocation: trigger with an empty FIFO drains
     * nothing and is counted, not hidden. */
    KIDO_SIRQ_CHECK(kido_serial_irq_stats(&st) == KIDO_OK,
                    "stats read (G) failed");
    {
        uint32_t spurious_before = st.spurious_runs;
        uint32_t runs_before = st.handler_runs;
        KIDO_SIRQ_CHECK(kido_gic_trigger(
                        KIDO_SERIAL_IRQ_QEMU_VIRT_IRQ) == KIDO_OK,
                        "gic trigger 33 (G) failed");
        KIDO_SIRQ_CHECK(kido_gic_dispatch() == KIDO_OK,
                        "gic dispatch (G) failed");
        KIDO_SIRQ_CHECK(kido_serial_irq_stats(&st) == KIDO_OK &&
                        st.spurious_runs == spurious_before + 1u &&
                        st.handler_runs == runs_before + 1u,
                        "spurious run not counted");
    }

    /* H. GIC enable gating: disabled at the GIC, a trigger stays
     * spurious at dispatch — the handler never runs. */
    KIDO_SIRQ_CHECK(kido_serial_irq_stats(&st) == KIDO_OK,
                    "stats read (H) failed");
    {
        uint32_t runs_before = st.handler_runs;
        KIDO_SIRQ_CHECK(kido_gic_disable(
                        KIDO_SERIAL_IRQ_QEMU_VIRT_IRQ) == KIDO_OK,
                        "gic disable 33 failed");
        KIDO_SIRQ_CHECK(kido_gic_trigger(
                        KIDO_SERIAL_IRQ_QEMU_VIRT_IRQ) == KIDO_OK,
                        "gic trigger 33 (H) failed");
        KIDO_SIRQ_CHECK(kido_gic_dispatch() == KIDO_OK,
                        "gic dispatch (H) failed");
        KIDO_SIRQ_CHECK(kido_serial_irq_stats(&st) == KIDO_OK &&
                        st.handler_runs == runs_before,
                        "handler ran while GIC-disabled");
        KIDO_SIRQ_CHECK(kido_gic_enable(
                        KIDO_SERIAL_IRQ_QEMU_VIRT_IRQ) == KIDO_OK,
                        "gic re-enable 33 failed");
        /* The stale pending bit from the disabled trigger is
         * still pending; clear it so later sections see a clean
         * controller, then confirm the handler runs again. */
        KIDO_SIRQ_CHECK(kido_gic_clear_pending(
                        KIDO_SERIAL_IRQ_QEMU_VIRT_IRQ) == KIDO_OK,
                        "gic clear pending failed");
    }

    /* I. Stop: mask + disable + unregister; a later trigger
     * dispatches to no handler. stats() is unreadable while
     * stopped (by design), so the "handler did not run" proof
     * captures the count BEFORE stop and reads it AFTER the
     * re-init below; the restart delivery then proves the
     * re-init path. The ring keeps no bytes here (drained
     * in F). */
    KIDO_SIRQ_CHECK(kido_serial_irq_stats(&st) == KIDO_OK,
                    "stats read (I) failed");
    {
        uint32_t runs_before = st.handler_runs;
        KIDO_SIRQ_CHECK(kido_serial_irq_stop() == KIDO_OK,
                        "stop failed");
        KIDO_SIRQ_CHECK((kido_dbl_imsc & KIDO_SIRQ_RX_INT) == 0u,
                        "IMSC RXIM not cleared by stop");
        KIDO_SIRQ_CHECK(kido_serial_irq_stop() == KIDO_ERR_EARLY_ENV,
                        "double stop not refused");
        KIDO_SIRQ_CHECK(kido_gic_trigger(
                        KIDO_SERIAL_IRQ_QEMU_VIRT_IRQ) == KIDO_OK,
                        "gic trigger 33 (I) failed");
        KIDO_SIRQ_CHECK(kido_gic_dispatch() == KIDO_OK,
                        "gic dispatch (I) failed");
        KIDO_SIRQ_CHECK(kido_serial_irq_init(KIDO_SIRQ_BASE,
                        KIDO_SERIAL_IRQ_QEMU_VIRT_IRQ) == KIDO_OK,
                        "re-init after stop failed");
        KIDO_SIRQ_CHECK(kido_serial_irq_stats(&st) == KIDO_OK &&
                        st.handler_runs == runs_before,
                        "handler ran after stop");
    }
    kido_serial_irq_test_feed((uint8_t)'Z', 0u);
    KIDO_SIRQ_CHECK(kido_gic_trigger(KIDO_SERIAL_IRQ_QEMU_VIRT_IRQ) ==
                    KIDO_OK, "gic trigger 33 (restart) failed");
    KIDO_SIRQ_CHECK(kido_gic_dispatch() == KIDO_OK,
                    "gic dispatch (restart) failed");
    KIDO_SIRQ_CHECK(kido_serial_irq_getc(&c) == KIDO_OK && c == 'Z',
                    "restart delivery not Z");

    if (failures == 0)
        printf("kido-serial-irq self-test: ALL PASS (%d checks)\n",
               checks);
    else
        printf("kido-serial-irq self-test: %d FAILURES (%d checks)\n",
               failures, checks);
    return failures != 0;
#undef KIDO_SIRQ_CHECK
}
#endif /* KIDO_SERIAL_IRQ_SELFTEST */
