/*
 * kido-mmu.c — Kido ARM64 stage-1 MMU: static identity-mapped tables.
 *
 * Draft 2026-10-22 (session 22). Design record:
 * deliberations/2026-10-22-kido-session22-mmu-design.md.
 *
 * WHAT IS REAL: table construction. Portable C over a caller-supplied
 * map, largest-fitting blocks (L1 1 GiB / L2 2 MiB / L3 4 KiB), exact
 * coverage, every descriptor bit chosen and stated. Fully host-tested
 * by the independent walker in the self-test below.
 *
 * WHAT IS WRITTEN, NOT PROVEN: the enable register sequence (real
 * ARM64 inline asm; the cross toolchain is absent this session — 5th
 * data point, see ledger — so it is unassembled and unexecuted). A
 * hosted double records the sequence + values; the encoding waits for
 * PENDING #1's toolchain. The call-site seam (after kido_reloc_verify
 * OK, before kido_boot) is DECLARED, NOT WIRED — a future Gate item.
 * This file touches no approved file.
 *
 * TESTING: KIDO_HOSTED_TEST builds the portable core + self-test.
 *  gcc -std=c11 -Wall -Wextra -Werror -DKIDO_HOSTED_TEST \
 *      -DKIDO_MMU_SELFTEST modules/kido-mmu.c -o /tmp/kido-mmu-test
 * Cross (ARM64, real asm): aarch64-linux-gnu-gcc -ffreestanding -c
 *  modules/kido-mmu.c  (queued with the toolchain, like PENDING #1)
 *
 * No bootable kernel is finalized without N8toriousAi; first boot is his
 * to witness.
 */

#include "kido-mmu.h"

/* ------------------------------------------------------------------ */
/* Descriptor bit layout (ARMv8-A VMSAv8-64, EL1, 4 KiB granule).      */
/* Every constant below is derived from the architecture, not copied   */
/* blind: the self-test pins the assembled values bit-for-bit.        */
/* ------------------------------------------------------------------ */
#define D_VALID_TABLE  0x3u   /* [1:0] = 0b11: table descriptor      */
#define D_VALID_BLOCK  0x1u   /* [1:0] = 0b01: block descriptor      */
#define D_AF           (1u << 10)      /* Access Flag: no AF faults  */
#define D_UXN          (1ull << 54)   /* UXN=1 (PXN=0: EL1 executes) */
#define D_TABLE_MASK   0x0000FFFFFFFFF000ull  /* next-table base      */
#define D_L1_BLOCK_MASK 0xFFFFFC0000000ull    /* OA[47:30], 1 GiB     */
#define D_L2_BLOCK_MASK 0xFFFFFFE00000ull     /* OA[47:21], 2 MiB     */

#define L1_IDX(va) (((va) >> 30) & 0x1FFu)
#define L2_IDX(va) (((va) >> 21) & 0x1FFu)
#define L3_IDX(va) (((va) >> 12) & 0x1FFu)

/* ------------------------------------------------------------------ */
/* Static tables (P2). BSS; the entry .S zeroes BSS before C runs, and */
/* build() zeroes explicitly anyway (idempotent rebuild). Page 0 is   */
/* the L1 root (the TTBR0 value); the rest are bump-allocated L2/L3.  */
/*                                                                    */
/* 4 KiB ALIGNMENT IS LOAD-BEARING (found by the self-test 2026-10-   */
/* -22): the architecture ignores descriptor/TTBR address bits        */
/* [11:0] — a merely 8/16-byte-aligned BSS array silently corrupts    */
/* every table address (the test caught bit 6 being masked out of a   */
/* descriptor). Without this attribute the MMU would walk garbage.    */
/* ------------------------------------------------------------------ */
static uint64_t s_tables[KIDO_MMU_MAX_TABLE_PAGES][512]
    __attribute__((aligned(KIDO_MMU_PAGE_SIZE)));
static unsigned s_next_page;   /* next free page; 1 after L1 root    */
static int      s_built;       /* build() has succeeded              */

#ifdef KIDO_HOSTED_TEST
static kido_mmu_hosted_trace_t s_trace;
#endif

/* ------------------------------------------------------------------ */
/* Pure register values (P4).                                          */
/* ------------------------------------------------------------------ */
uint64_t kido_mmu_tcr_el1(void)
{
    uint64_t tcr = 0u;
    tcr |= 25u;          /* T0SZ = 25: 39-bit VA                      */
    tcr |= (1u << 8);    /* IRGN0 = 0b01: inner WBWA                  */
    tcr |= (1u << 10);   /* ORGN0 = 0b01: outer WBWA                  */
    tcr |= (3u << 12);   /* SH0 = 0b11: inner-shareable               */
    /* TG0 = 0b00: 4 KiB granule (reset value, stated)                */
    tcr |= (25u << 16);  /* T1SZ: don't-care-but-sane (EPD1 set)      */
    /* EPD0 = 0: TTBR0 walks enabled                                  */
    tcr |= (1u << 23);   /* EPD1 = 1: TTBR1 walks disabled, explicit   */
    tcr |= (2ull << 32); /* IPS = 0b010: 40-bit PA (QEMU virt)        */
    return tcr;          /* == 0x200993519, pinned by test            */
}

uint64_t kido_mmu_mair_el1(void)
{
    /* Attr0 = 0x00 Device-nGnRnE, Attr1 = 0xFF Normal WBWA (P3). */
    return (0xFFu << 8) | 0x00u;   /* == 0xFF00, pinned by test */
}

/* Per-attribute descriptor bits (P3). NORMAL: AttrIndx=1, ISH.
 * DEVICE: AttrIndx=0, OSH. Both: AP=EL1 RW, AF=1, UXN=1/PXN=0. */
static uint64_t mmu_attr_bits(kido_mmu_attr_t attr)
{
    uint64_t d = 0u;
    if (attr == KIDO_MMU_ATTR_NORMAL) {
        d |= (1u << 2);    /* AttrIndx = 1 */
        d |= (3u << 8);    /* SH = ISH     */
    } else {
        d |= (0u << 2);    /* AttrIndx = 0 */
        d |= (2u << 8);    /* SH = OSH     */
    }
    /* AP[7:6] = 0b00: EL1 read/write, EL0 no access (stated zero). */
    d |= D_AF;
    d |= D_UXN;
    return d;
}

static uint64_t mmu_table_desc(uint64_t next_base)
{
    return (next_base & D_TABLE_MASK) | D_VALID_TABLE;
}

static uint64_t mmu_block_desc(uint64_t oa, uint64_t attrbits,
                               uint64_t oa_mask)
{
    return (oa & oa_mask) | attrbits | D_VALID_BLOCK;
}

static uint64_t mmu_page_desc(uint64_t oa, uint64_t attrbits)
{
    return (oa & D_TABLE_MASK) | attrbits | D_VALID_TABLE;
}

/* On-demand table getters. Impossible-by-construction conflicts
 * (a block where a table is needed) fail EARLY_ENV — defense in
 * depth behind the input overlap check. Exhaustion fails NO_MEMORY. */
static kido_status_t mmu_get_l2(uint64_t va, uint64_t **out)
{
    uint64_t e = s_tables[0][L1_IDX(va)];
    if ((e & 0x3u) == D_VALID_TABLE) {
        *out = (uint64_t *)(uintptr_t)(e & D_TABLE_MASK);
        return KIDO_OK;
    }
    if (e != 0u)
        return KIDO_ERR_EARLY_ENV;   /* block here: cannot happen */
    if (s_next_page >= KIDO_MMU_MAX_TABLE_PAGES)
        return KIDO_ERR_NO_MEMORY;
    *out = &s_tables[s_next_page++][0];
    s_tables[0][L1_IDX(va)] = mmu_table_desc((uint64_t)(uintptr_t)*out);
    return KIDO_OK;
}

static kido_status_t mmu_get_l3(uint64_t *l2, uint64_t va, uint64_t **out)
{
    uint64_t e = l2[L2_IDX(va)];
    if ((e & 0x3u) == D_VALID_TABLE) {
        *out = (uint64_t *)(uintptr_t)(e & D_TABLE_MASK);
        return KIDO_OK;
    }
    if (e != 0u)
        return KIDO_ERR_EARLY_ENV;   /* block here: cannot happen */
    if (s_next_page >= KIDO_MMU_MAX_TABLE_PAGES)
        return KIDO_ERR_NO_MEMORY;
    *out = &s_tables[s_next_page++][0];
    l2[L2_IDX(va)] = mmu_table_desc((uint64_t)(uintptr_t)*out);
    return KIDO_OK;
}

/* Largest-fitting block walk (P1): 1 GiB L1 blocks where a whole GiB
 * is inside the range and aligned, else L2 2 MiB blocks, else L3
 * 4 KiB pages. Identity: OA == VA everywhere. */
static kido_status_t mmu_map_range(uint64_t va, uint64_t size,
                                   kido_mmu_attr_t attr)
{
    uint64_t end = va + size;
    uint64_t attrbits = mmu_attr_bits(attr);
    while (va < end) {
        uint64_t remain = end - va;
        kido_status_t st;
        if ((va & 0x3FFFFFFFu) == 0u && remain >= 0x40000000u) {
            s_tables[0][L1_IDX(va)] =
                mmu_block_desc(va, attrbits, D_L1_BLOCK_MASK);
            va += 0x40000000u;
        } else {
            uint64_t *l2;
            st = mmu_get_l2(va, &l2);
            if (st != KIDO_OK)
                return st;
            if ((va & 0x1FFFFFu) == 0u && remain >= 0x200000u) {
                l2[L2_IDX(va)] =
                    mmu_block_desc(va, attrbits, D_L2_BLOCK_MASK);
                va += 0x200000u;
            } else {
                uint64_t *l3;
                st = mmu_get_l3(l2, va, &l3);
                if (st != KIDO_OK)
                    return st;
                l3[L3_IDX(va)] = mmu_page_desc(va, attrbits);
                va += 0x1000u;
            }
        }
    }
    return KIDO_OK;
}

kido_status_t kido_mmu_build(const kido_mmu_map_entry_t *map, size_t n)
{
    size_t i, j, k;
    kido_status_t st;
    if (map == NULL || n == 0u)
        return KIDO_ERR_EARLY_ENV;
    /* Pass 1: every entry valid on its own. */
    for (i = 0u; i < n; i++) {
        uint64_t end;
        if (map[i].size == 0u)
            return KIDO_ERR_EARLY_ENV;
        if ((map[i].base & 0xFFFu) != 0u || (map[i].size & 0xFFFu) != 0u)
            return KIDO_ERR_EARLY_ENV;   /* 4 KiB unit (C2/C3) */
        if (map[i].attr != KIDO_MMU_ATTR_NORMAL &&
            map[i].attr != KIDO_MMU_ATTR_DEVICE)
            return KIDO_ERR_EARLY_ENV;
        end = map[i].base + map[i].size;
        if (end < map[i].base)
            return KIDO_ERR_EARLY_ENV;   /* wrap */
        if (end > KIDO_MMU_VA_LIMIT)
            return KIDO_ERR_EARLY_ENV;   /* 39-bit walk stays 39-bit */
    }
    /* Pass 2: pairwise non-overlap (half-open). A clipped overlap
     * would be silent corruption of the map — loud instead. */
    for (i = 0u; i < n; i++) {
        uint64_t bi = map[i].base, ei = map[i].base + map[i].size;
        for (j = i + 1u; j < n; j++) {
            uint64_t bj = map[j].base, ej = map[j].base + map[j].size;
            if (bi < ej && bj < ei)
                return KIDO_ERR_EARLY_ENV;
        }
    }
    /* Idempotent: zero everything, L1 root is page 0. */
    for (i = 0u; i < KIDO_MMU_MAX_TABLE_PAGES; i++)
        for (j = 0u; j < 512u; j++)
            s_tables[i][j] = 0u;
    s_next_page = 1u;
    s_built = 0;
    for (k = 0u; k < n; k++) {
        st = mmu_map_range(map[k].base, map[k].size, map[k].attr);
        if (st != KIDO_OK)
            return st;
    }
    s_built = 1;
    return KIDO_OK;
}

kido_status_t kido_mmu_enable(void)
{
    if (!s_built)
        return KIDO_ERR_EARLY_ENV;   /* tables first, always */
#if defined(__aarch64__) && !defined(KIDO_HOSTED_TEST)
    /* PROOF STATUS: written, not assembled, never executed (no
     * toolchain this session). The sequence is P4: TLBI, then
     * TTBR0/TCR/MAIR fully programmed, barriers, then the M bit. */
    {
        uint64_t ttbr0 = (uint64_t)(uintptr_t)&s_tables[0][0];
        uint64_t tcr   = kido_mmu_tcr_el1();
        uint64_t mair  = kido_mmu_mair_el1();
        uint64_t sctlr;
        __asm__ volatile("tlbi vmalle1" ::: "memory");
        __asm__ volatile("dsb sy" ::: "memory");
        __asm__ volatile("msr ttbr0_el1, %0" :: "r"(ttbr0) : "memory");
        __asm__ volatile("msr tcr_el1, %0"   :: "r"(tcr)   : "memory");
        __asm__ volatile("msr mair_el1, %0"  :: "r"(mair)  : "memory");
        __asm__ volatile("dsb sy" ::: "memory");
        __asm__ volatile("isb"    ::: "memory");
        __asm__ volatile("mrs %0, sctlr_el1" : "=r"(sctlr));
        sctlr |= KIDO_MMU_SCTLR_ENABLE_BITS;   /* M | C | I, pure C */
        __asm__ volatile("msr sctlr_el1, %0" :: "r"(sctlr) : "memory");
        __asm__ volatile("isb" ::: "memory");
    }
    return KIDO_OK;
#else
    /* Hosted double (HAL precedent): record the sequence + values. */
    s_trace.ttbr0     = (uint64_t)(uintptr_t)&s_tables[0][0];
    s_trace.tcr       = kido_mmu_tcr_el1();
    s_trace.mair      = kido_mmu_mair_el1();
    s_trace.sctlr_old = 0u;   /* reset-state SCTLR on the entry path */
    s_trace.sctlr_new = s_trace.sctlr_old | KIDO_MMU_SCTLR_ENABLE_BITS;
    s_trace.order[0]  = (unsigned char)KIDO_MMU_STEP_TLBI;
    s_trace.order[1]  = (unsigned char)KIDO_MMU_STEP_TTBR0;
    s_trace.order[2]  = (unsigned char)KIDO_MMU_STEP_TCR;
    s_trace.order[3]  = (unsigned char)KIDO_MMU_STEP_MAIR;
    s_trace.order[4]  = (unsigned char)KIDO_MMU_STEP_SCTLR;
    s_trace.nsteps    = 5u;
    return KIDO_OK;
#endif
}

const uint64_t *kido_mmu_l1(void) { return &s_tables[0][0]; }
size_t kido_mmu_pages_used(void)  { return (size_t)s_next_page; }
int    kido_mmu_built(void)       { return s_built; }

#ifdef KIDO_HOSTED_TEST
void kido_mmu_hosted_trace_reset(void)
{
    unsigned i;
    s_trace.ttbr0 = 0u; s_trace.tcr = 0u; s_trace.mair = 0u;
    s_trace.sctlr_old = 0u; s_trace.sctlr_new = 0u;
    s_trace.nsteps = 0u;
    for (i = 0u; i < 8u; i++)
        s_trace.order[i] = 0xFFu;
}
const kido_mmu_hosted_trace_t *kido_mmu_hosted_trace(void)
{
    return &s_trace;
}
#endif

/* ================================================================== */
/* Hosted self-test. An INDEPENDENT walker (not the builder's own     */
/* accessors) reads the tables back: descriptor types, OA bases,      */
/* attributes, and unmapped-VA behavior.                              */
/* ================================================================== */
#ifdef KIDO_MMU_SELFTEST
#ifndef KIDO_HOSTED_TEST
#error "KIDO_MMU_SELFTEST needs KIDO_HOSTED_TEST."
#endif
#include <stdio.h>

static int s_failures = 0;
static int s_checks = 0;
#define CHECK(cond, msg) do { \
    s_checks++; \
    if (!(cond)) { printf("[FAIL] %s\n", msg); s_failures++; } \
} while (0)

/* kind: 0 = unmapped, 1 = L1 block, 2 = L2 block, 3 = L3 page */
static uint64_t test_walk(uint64_t va, int *kind_out)
{
    const uint64_t *l1 = kido_mmu_l1();
    uint64_t e = l1[L1_IDX(va)];
    if (e == 0u) { *kind_out = 0; return 0u; }
    if ((e & 0x3u) == D_VALID_BLOCK) { *kind_out = 1; return e; }
    {
        const uint64_t *l2 = (const uint64_t *)(uintptr_t)(e & D_TABLE_MASK);
        e = l2[L2_IDX(va)];
        if (e == 0u) { *kind_out = 0; return 0u; }
        if ((e & 0x3u) == D_VALID_BLOCK) { *kind_out = 2; return e; }
        {
            const uint64_t *l3 = (const uint64_t *)(uintptr_t)(e & D_TABLE_MASK);
            e = l3[L3_IDX(va)];
            if (e == 0u) { *kind_out = 0; return 0u; }
            *kind_out = 3; return e;
        }
    }
}

static int desc_attr_ok(uint64_t d, unsigned attrindx, unsigned sh)
{
    if (((d >> 2) & 0x7u) != attrindx) return 0;
    if (((d >> 8) & 0x3u) != sh) return 0;
    if (((d >> 6) & 0x3u) != 0u) return 0;   /* AP = EL1 RW */
    if ((d & D_AF) == 0u) return 0;
    if ((d & D_UXN) == 0u) return 0;
    if ((d >> 53) & 0x1u) return 0;           /* PXN = 0 */
    return 1;
}

int main(void)
{
    int kind;
    uint64_t d;
    unsigned i;
    const uint64_t *l1 = kido_mmu_l1();

    /* §1: pure register values, bit-exact. */
    CHECK(kido_mmu_tcr_el1() == 0x200993519ull, "tcr bit-exact");
    CHECK(kido_mmu_mair_el1() == 0xFF00ull, "mair bit-exact");

    /* §2: argument guards — all loud, none silent. */
    {
        kido_mmu_map_entry_t e1[] = { { 0x40000000u, 0x200000u,
                                        KIDO_MMU_ATTR_NORMAL } };
        kido_mmu_map_entry_t e0s[] = { { 0x40000000u, 0u,
                                         KIDO_MMU_ATTR_NORMAL } };
        kido_mmu_map_entry_t eba[] = { { 0x40000001u, 0x200000u,
                                        KIDO_MMU_ATTR_NORMAL } };
        kido_mmu_map_entry_t esz[] = { { 0x40000000u, 0x200001u,
                                        KIDO_MMU_ATTR_NORMAL } };
        kido_mmu_map_entry_t ewr[] = { { 0xFFFFFFFFFFFFF000ull, 0x2000u,
                                        KIDO_MMU_ATTR_NORMAL } };
        kido_mmu_map_entry_t elim[] = { { 0x7FFFFFFFF000ull, 0x2000u,
                                         KIDO_MMU_ATTR_NORMAL } };
        kido_mmu_map_entry_t eattr[] = { { 0x40000000u, 0x200000u, 7 } };
        kido_mmu_map_entry_t eov[] = { { 0x40000000u, 0x200000u,
                                        KIDO_MMU_ATTR_NORMAL },
                                       { 0x40100000u, 0x200000u,
                                        KIDO_MMU_ATTR_NORMAL } };
        CHECK(kido_mmu_build(NULL, 1u) == KIDO_ERR_EARLY_ENV,
              "null map loud");
        CHECK(kido_mmu_build(e1, 0u) == KIDO_ERR_EARLY_ENV,
              "empty map loud");
        CHECK(kido_mmu_build(e0s, 1u) == KIDO_ERR_EARLY_ENV,
              "zero size loud");
        CHECK(kido_mmu_build(eba, 1u) == KIDO_ERR_EARLY_ENV,
              "misaligned base loud");
        CHECK(kido_mmu_build(esz, 1u) == KIDO_ERR_EARLY_ENV,
              "misaligned size loud");
        CHECK(kido_mmu_build(ewr, 1u) == KIDO_ERR_EARLY_ENV,
              "wrap loud");
        CHECK(kido_mmu_build(elim, 1u) == KIDO_ERR_EARLY_ENV,
              "VA-limit breach loud");
        CHECK(kido_mmu_build(eattr, 1u) == KIDO_ERR_EARLY_ENV,
              "bad attr loud");
        CHECK(kido_mmu_build(eov, 2u) == KIDO_ERR_EARLY_ENV,
              "overlap loud");
    }

    /* §2b: enable before any successful build is loud. (§2's builds
     * all failed validation, so s_built is still 0 here.) */
    kido_mmu_hosted_trace_reset();
    CHECK(kido_mmu_enable() == KIDO_ERR_EARLY_ENV,
          "enable before build loud");

    /* §3: the canonical map — 128 MiB RAM + UART window. */
    {
        kido_mmu_map_entry_t cmap[] = {
            { 0x40000000u, 0x8000000u, KIDO_MMU_ATTR_NORMAL },
            { 0x09000000u, 0x200000u,  KIDO_MMU_ATTR_DEVICE }
        };
        const uint64_t *rl1;
        const uint64_t *rl2;
        const uint64_t *ul2;
        CHECK(kido_mmu_build(cmap, 2u) == KIDO_OK, "canonical build ok");
        CHECK(kido_mmu_built() == 1, "built flag set");
        CHECK(kido_mmu_pages_used() == 3u, "3 pages: L1 + 2xL2");
        CHECK(((uint64_t)(uintptr_t)kido_mmu_l1() & 0xFFFu) == 0u,
              "L1 root 4KiB-aligned (architectural)");
        rl1 = kido_mmu_l1();
        /* RAM GiB -> L1 table descriptor. */
        d = rl1[1];
        CHECK((d & 0x3u) == D_VALID_TABLE, "L1[1] is table desc");
        rl2 = (const uint64_t *)(uintptr_t)(d & D_TABLE_MASK);
        CHECK(rl2 >= &s_tables[0][0] &&
              rl2 < &s_tables[KIDO_MMU_MAX_TABLE_PAGES][0],
              "L1[1] target inside static tables");
        /* 64 x 2 MiB blocks, exact OA, normal attrs. L2 index for
         * VA 0x40000000+k*2MiB is k (bits [29:21] within GiB 1). */
        for (i = 0u; i < 64u; i++) {
            uint64_t e = rl2[i];
            uint64_t want_oa = 0x40000000u + (uint64_t)i * 0x200000u;
            if ((e & 0x3u) != D_VALID_BLOCK ||
                (e & D_L2_BLOCK_MASK) != want_oa ||
                !desc_attr_ok(e, 1u, 3u)) {
                printf("[FAIL] RAM block %u bad: 0x%llx\n", i,
                       (unsigned long long)e);
                s_failures++;
            }
            s_checks++;
        }
        CHECK(rl2[64] == 0u, "block above RAM unmapped");
        /* UART GiB -> L1 table; 2 MiB device block at 0x48. */
        d = rl1[0];
        CHECK((d & 0x3u) == D_VALID_TABLE, "L1[0] is table desc");
        ul2 = (const uint64_t *)(uintptr_t)(d & D_TABLE_MASK);
        d = ul2[0x48u];
        CHECK((d & 0x3u) == D_VALID_BLOCK, "UART is L2 block");
        CHECK((d & D_L2_BLOCK_MASK) == 0x09000000u, "UART OA exact");
        CHECK(desc_attr_ok(d, 0u, 2u), "UART device attrs");
        CHECK(rl1[2] == 0u, "unmapped GiB stays zero");
        /* Walker cross-checks. */
        d = test_walk(0x40000000u, &kind);
        CHECK(kind == 2 && (d & D_L2_BLOCK_MASK) == 0x40000000u,
              "walk RAM base");
        d = test_walk(0x47FFFFFFu, &kind);
        CHECK(kind == 2 && (d & D_L2_BLOCK_MASK) == 0x47E00000u,
              "walk RAM tail");
        d = test_walk(0x09000000u, &kind);
        CHECK(kind == 2 && (d & D_L2_BLOCK_MASK) == 0x09000000u,
              "walk UART");
        (void)d;
        test_walk(0xC0000000u, &kind);
        CHECK(kind == 0, "walk unmapped GiB -> fault");
        test_walk(0x0u, &kind);
        CHECK(kind == 0, "walk VA 0 -> fault");
    }

    /* §4: the 1 GiB block path. */
    {
        kido_mmu_map_entry_t g1[] = { { 0u, 0x40000000u,
                                       KIDO_MMU_ATTR_NORMAL } };
        CHECK(kido_mmu_build(g1, 1u) == KIDO_OK, "1GiB build ok");
        d = l1[0];
        CHECK((d & 0x3u) == D_VALID_BLOCK, "L1[0] is 1GiB block");
        CHECK((d & D_L1_BLOCK_MASK) == 0u, "1GiB block OA exact");
        CHECK(desc_attr_ok(d, 1u, 3u), "1GiB block normal attrs");
        CHECK(kido_mmu_pages_used() == 1u, "1GiB block: L1 only");
        d = test_walk(0x20000000u, &kind);
        CHECK(kind == 1, "walk inside 1GiB block");
        (void)d;
    }

    /* §5: the L3 4 KiB page path. */
    {
        kido_mmu_map_entry_t p4[] = { { 0x5000u, 0x1000u,
                                       KIDO_MMU_ATTR_NORMAL } };
        const uint64_t *l2;
        const uint64_t *l3;
        CHECK(kido_mmu_build(p4, 1u) == KIDO_OK, "4KiB build ok");
        CHECK((l1[0] & 0x3u) == D_VALID_TABLE, "L1[0] table for page");
        l2 = (const uint64_t *)(uintptr_t)(l1[0] & D_TABLE_MASK);
        CHECK((l2[0] & 0x3u) == D_VALID_TABLE, "L2[0] table for page");
        l3 = (const uint64_t *)(uintptr_t)(l2[0] & D_TABLE_MASK);
        d = l3[5];
        CHECK((d & 0x3u) == D_VALID_TABLE, "L3[5] is page desc");
        CHECK((d & D_TABLE_MASK) == 0x5000u, "page OA exact");
        CHECK(desc_attr_ok(d, 1u, 3u), "page normal attrs");
        CHECK(kido_mmu_pages_used() == 3u, "page: L1+L2+L3");
        d = test_walk(0x5000u, &kind);
        CHECK(kind == 3 && (d & D_TABLE_MASK) == 0x5000u,
              "walk 4KiB page");
        (void)d;
    }

    /* §6: table exhaustion is NO_MEMORY, loud. 8 single pages in 8
     * GiBs need 1 + 16 pages; the 8th fails. */
    {
        kido_mmu_map_entry_t many[8];
        kido_mmu_map_entry_t seven[7];
        for (i = 0u; i < 8u; i++) {
            many[i].base = (uint64_t)i * 0x40000000u;
            many[i].size = 0x1000u;
            many[i].attr = KIDO_MMU_ATTR_NORMAL;
            if (i < 7u)
                seven[i] = many[i];
        }
        CHECK(kido_mmu_build(seven, 7u) == KIDO_OK,
              "7 scattered pages fit (15 pages)");
        CHECK(kido_mmu_build(many, 8u) == KIDO_ERR_NO_MEMORY,
              "8th scattered page -> NO_MEMORY loud");
    }

    /* §7: rebuild is idempotent. */
    {
        kido_mmu_map_entry_t cmap[] = {
            { 0x40000000u, 0x8000000u, KIDO_MMU_ATTR_NORMAL },
            { 0x09000000u, 0x200000u,  KIDO_MMU_ATTR_DEVICE }
        };
        uint64_t before;
        CHECK(kido_mmu_build(cmap, 2u) == KIDO_OK, "rebuild ok");
        before = l1[1];
        CHECK(kido_mmu_build(cmap, 2u) == KIDO_OK, "rebuild again ok");
        CHECK(kido_mmu_pages_used() == 3u, "rebuild: same page count");
        CHECK(l1[1] == before, "rebuild: identical L1[1]");
    }

    /* §8: the enable double — sequence order + values. */
    {
        const kido_mmu_hosted_trace_t *tr;
        kido_mmu_hosted_trace_reset();
        {
            kido_mmu_map_entry_t cmap[] = {
                { 0x40000000u, 0x8000000u, KIDO_MMU_ATTR_NORMAL }
            };
            CHECK(kido_mmu_build(cmap, 1u) == KIDO_OK,
                  "build before enable");
        }
        CHECK(kido_mmu_enable() == KIDO_OK, "enable ok");
        tr = kido_mmu_hosted_trace();
        CHECK(tr->nsteps == 5u, "5 steps recorded");
        CHECK(tr->order[0] == KIDO_MMU_STEP_TLBI &&
              tr->order[1] == KIDO_MMU_STEP_TTBR0 &&
              tr->order[2] == KIDO_MMU_STEP_TCR &&
              tr->order[3] == KIDO_MMU_STEP_MAIR &&
              tr->order[4] == KIDO_MMU_STEP_SCTLR,
              "sequence: TLBI -> TTBR0 -> TCR -> MAIR -> SCTLR");
        CHECK(tr->ttbr0 == (uint64_t)(uintptr_t)kido_mmu_l1(),
              "TTBR0 = L1 root");
        CHECK(tr->tcr == 0x200993519ull, "TCR value exact");
        CHECK(tr->mair == 0xFF00ull, "MAIR value exact");
        CHECK(tr->sctlr_new == (tr->sctlr_old | 0x1005u),
              "SCTLR sets M|C|I only");
    }

    printf("[test] kido-mmu: %d checks, %d failures\n", s_checks,
           s_failures);
    return s_failures == 0 ? 0 : 1;
}
#endif /* KIDO_MMU_SELFTEST */
