/*
 * kido-cache.c — Kido cache maintenance leaf.
 *
 * See kido-cache.h for the point law, the two-line-sizes
 * law, the alignment law, the barrier law, and the stated
 * divergences. This file is the real logic in two backends:
 * ARM64 maintenance instructions (WRITTEN, NOT ASSEMBLED,
 * NEVER EXECUTED — toolchain absent, 22nd data point),
 * and a hosted path over the injector's CTR fields that
 * records every op into the trace log (the mmu enable
 * double's precedent). The guard and alignment logic is
 * shared across both backends: one static helper validates
 * and rounds a range, so the two paths can never drift.
 * Each op is its own loop — a single loop with a
 * runtime-selected maintenance instruction is not
 * expressible in inline asm, and a function pointer in
 * a cache primitive would be a second invention.
 *
 * TESTING: gcc -std=c11 -Wall -Wextra -Werror -DKIDO_HOSTED_TEST
 *        -DKIDO_CACHE_SELFTEST kido-cache.c -o cache-selftest
 */
#include "kido-cache.h"

#ifdef KIDO_CACHE_SELFTEST
#ifndef KIDO_HOSTED_TEST
#error "KIDO_CACHE_SELFTEST needs KIDO_HOSTED_TEST."
#endif
#include <stdio.h>
#endif /* KIDO_CACHE_SELFTEST */

/* ------------------------------------------------------------------ */
/* Line sizes. ARM64: CTR_EL0 fields. The hosted path decodes the    */
/* injector's fields with the identical formula, so the formula is    */
/* tested even though the register is not.                            */
/* ------------------------------------------------------------------ */
#ifdef KIDO_HOSTED_TEST
static uint32_t kido_cache_host_dminline = 4u; /* 64 bytes */
static uint32_t kido_cache_host_iminline = 4u; /* 64 bytes */

kido_status_t kido_cache_test_set_dminline(uint32_t field)
{
    kido_cache_host_dminline = field & 0xfu;
    return KIDO_OK;
}

kido_status_t kido_cache_test_set_iminline(uint32_t field)
{
    kido_cache_host_iminline = field & 0xfu;
    return KIDO_OK;
}

static uint64_t kido_cache_ctr_dminline(void)
{
    return (uint64_t)kido_cache_host_dminline;
}

static uint64_t kido_cache_ctr_iminline(void)
{
    return (uint64_t)kido_cache_host_iminline;
}
#else /* bare metal */
static uint64_t kido_cache_ctr_dminline(void)
{
    uint64_t ctr = 0u;
    __asm__ volatile("mrs %0, ctr_el0" : "=r"(ctr));
    return (ctr >> 16) & 0xfu;
}

static uint64_t kido_cache_ctr_iminline(void)
{
    uint64_t ctr = 0u;
    __asm__ volatile("mrs %0, ctr_el0" : "=r"(ctr));
    return ctr & 0xfu;
}
#endif /* KIDO_HOSTED_TEST */

/* Line bytes = 4 << field. Field 0 -> 4 bytes: the safe
 * over-maintenance direction, never refused (C2). The
 * shift cannot overflow: field <= 15, so size <= 128 KiB. */
static uint64_t kido_cache_line_bytes(uint64_t field)
{
    return 4u << field;
}

kido_status_t kido_cache_dline_size(uint64_t *out)
{
    if (out == (uint64_t *)0)
        return KIDO_ERR_EARLY_ENV;
    *out = kido_cache_line_bytes(kido_cache_ctr_dminline());
    return KIDO_OK;
}

kido_status_t kido_cache_iline_size(uint64_t *out)
{
    if (out == (uint64_t *)0)
        return KIDO_ERR_EARLY_ENV;
    *out = kido_cache_line_bytes(kido_cache_ctr_iminline());
    return KIDO_OK;
}

/* ------------------------------------------------------------------ */
/* Shared range validation + rounding. Returns the first line and    */
/* the line count, or EARLY_ENV. Rounding: base down, end up.        */
/* The end computation is wrap-guarded twice: addr+len first, then   */
/* the round-up (end + line - 1 can wrap even when addr+len did     */
/* not, when the range ends exactly at the top of the address        */
/* space).                                                            */
/* ------------------------------------------------------------------ */
static kido_status_t kido_cache_round_range(uintptr_t addr, uint64_t len,
                                             uint64_t line,
                                             uintptr_t *first_out,
                                             uint64_t *lines_out)
{
    uint64_t end;
    uint64_t rounded_end;

    if (addr == 0u || len == 0u)
        return KIDO_ERR_EARLY_ENV;
    if ((uint64_t)addr + len < (uint64_t)addr)
        return KIDO_ERR_EARLY_ENV;
    end = (uint64_t)addr + len;
    if (end + line - 1u < end)
        return KIDO_ERR_EARLY_ENV;
    rounded_end = (end + line - 1u) & ~(line - 1u);
    *first_out = addr & ~(uintptr_t)(line - 1u);
    *lines_out = (rounded_end - (uint64_t)*first_out) / line;
    return KIDO_OK;
}

/* ------------------------------------------------------------------ */
/* Hosted trace log (mmu enable double's precedent). The double      */
/* records the walk it would have performed: kind, first line,       */
/* line count, barrier sequence. It does NOT perform cache effects   */
/* — a host has no cache lines to move, and pretending otherwise    */
/* would be the exact lie this scaffold refuses. Counts, alignment,  */
/* and barrier order are the proof.                                  */
/* ------------------------------------------------------------------ */
#ifdef KIDO_HOSTED_TEST
#define KIDO_CACHE_TRACE_CAP 16u

static kido_cache_trace_t kido_cache_trace_log[KIDO_CACHE_TRACE_CAP];
static uint64_t kido_cache_trace_n = 0u;

static void kido_cache_record(uint32_t kind, uintptr_t first,
                              uint64_t lines, uint32_t dsb,
                              uint32_t isb)
{
    if (kido_cache_trace_n < KIDO_CACHE_TRACE_CAP) {
        kido_cache_trace_log[kido_cache_trace_n].kind = kind;
        kido_cache_trace_log[kido_cache_trace_n].first = first;
        kido_cache_trace_log[kido_cache_trace_n].lines = lines;
        kido_cache_trace_log[kido_cache_trace_n].dsb_after = dsb;
        kido_cache_trace_log[kido_cache_trace_n].isb_after = isb;
        kido_cache_trace_n++;
    }
    /* Past capacity: dropped, never wrapped — a wrapped
     * log would lie about order (header law). */
}

kido_status_t kido_cache_test_trace_reset(void)
{
    kido_cache_trace_n = 0u;
    return KIDO_OK;
}

kido_status_t kido_cache_test_trace_count(uint64_t *out)
{
    if (out == (uint64_t *)0)
        return KIDO_ERR_EARLY_ENV;
    *out = kido_cache_trace_n;
    return KIDO_OK;
}

kido_status_t kido_cache_test_trace_at(uint64_t idx,
                                        kido_cache_trace_t *out)
{
    if (out == (kido_cache_trace_t *)0)
        return KIDO_ERR_EARLY_ENV;
    if (idx >= kido_cache_trace_n)
        return KIDO_ERR_EARLY_ENV;
    *out = kido_cache_trace_log[idx];
    return KIDO_OK;
}
#endif /* KIDO_HOSTED_TEST */

/* ------------------------------------------------------------------ */
/* Range ops. Each is: round the range (shared), walk the lines      */
/* with its own instruction (ARM64) or record the walk (hosted),     */
/* then the barrier the law promises.                                */
/* ------------------------------------------------------------------ */
kido_status_t kido_cache_clean_range(uintptr_t addr, uint64_t len)
{
    uint64_t line;
    uintptr_t first = 0u;
    uint64_t lines = 0u;
    kido_status_t st;

    st = kido_cache_dline_size(&line);
    if (st != KIDO_OK)
        return st;
    st = kido_cache_round_range(addr, len, line, &first, &lines);
    if (st != KIDO_OK)
        return st;
#ifdef KIDO_HOSTED_TEST
    kido_cache_record(0u, first, lines, 1u, 0u);
#else
    {
        uint64_t i;
        for (i = 0u; i < lines; i++) {
            uintptr_t p = first + i * line;
            __asm__ volatile("dc cvac, %0" :: "r"(p) : "memory");
        }
        __asm__ volatile("dsb sy" ::: "memory");
    }
#endif
    return KIDO_OK;
}

kido_status_t kido_cache_invalidate_range(uintptr_t addr, uint64_t len)
{
    uint64_t line;
    uintptr_t first = 0u;
    uint64_t lines = 0u;
    kido_status_t st;

    st = kido_cache_dline_size(&line);
    if (st != KIDO_OK)
        return st;
    /* The C3 refusal: an unaligned invalidate would
     * discard a neighbor's dirty line the caller never
     * named. Both addr and len must be line multiples;
     * the round_range call below then cannot move them. */
    if ((addr & (uintptr_t)(line - 1u)) != 0u ||
        (len & (line - 1u)) != 0u)
        return KIDO_ERR_EARLY_ENV;
    st = kido_cache_round_range(addr, len, line, &first, &lines);
    if (st != KIDO_OK)
        return st;
#ifdef KIDO_HOSTED_TEST
    kido_cache_record(1u, first, lines, 1u, 0u);
#else
    {
        uint64_t i;
        for (i = 0u; i < lines; i++) {
            uintptr_t p = first + i * line;
            __asm__ volatile("dc ivac, %0" :: "r"(p) : "memory");
        }
        __asm__ volatile("dsb sy" ::: "memory");
    }
#endif
    return KIDO_OK;
}

kido_status_t kido_cache_clean_invalidate_range(uintptr_t addr,
                                                 uint64_t len)
{
    uint64_t line;
    uintptr_t first = 0u;
    uint64_t lines = 0u;
    kido_status_t st;

    st = kido_cache_dline_size(&line);
    if (st != KIDO_OK)
        return st;
    st = kido_cache_round_range(addr, len, line, &first, &lines);
    if (st != KIDO_OK)
        return st;
#ifdef KIDO_HOSTED_TEST
    kido_cache_record(2u, first, lines, 1u, 0u);
#else
    {
        uint64_t i;
        for (i = 0u; i < lines; i++) {
            uintptr_t p = first + i * line;
            __asm__ volatile("dc civac, %0" :: "r"(p) : "memory");
        }
        __asm__ volatile("dsb sy" ::: "memory");
    }
#endif
    return KIDO_OK;
}

kido_status_t kido_cache_sync_icache_range(uintptr_t addr, uint64_t len)
{
    uint64_t dline;
    uint64_t iline;
    uintptr_t dfirst = 0u;
    uint64_t dlines = 0u;
    uintptr_t ifirst = 0u;
    uint64_t ilines = 0u;
    kido_status_t st;

    /* Two walks, two line sizes (C2): the CVAU walk
     * steps by D, the IVAU walk by I. The order is the
     * API: CVAU, DSB, IVAU, DSB, ISB — unreorderable
     * because it lives inside one function (P4). */
    st = kido_cache_dline_size(&dline);
    if (st != KIDO_OK)
        return st;
    st = kido_cache_iline_size(&iline);
    if (st != KIDO_OK)
        return st;
    st = kido_cache_round_range(addr, len, dline, &dfirst, &dlines);
    if (st != KIDO_OK)
        return st;
    st = kido_cache_round_range(addr, len, iline, &ifirst, &ilines);
    if (st != KIDO_OK)
        return st;
#ifdef KIDO_HOSTED_TEST
    kido_cache_record(3u, dfirst, dlines, 1u, 0u);
    kido_cache_record(4u, ifirst, ilines, 1u, 1u);
#else
    {
        uint64_t i;
        for (i = 0u; i < dlines; i++) {
            uintptr_t p = dfirst + i * dline;
            __asm__ volatile("dc cvau, %0" :: "r"(p) : "memory");
        }
        __asm__ volatile("dsb sy" ::: "memory");
        for (i = 0u; i < ilines; i++) {
            uintptr_t p = ifirst + i * iline;
            __asm__ volatile("ic ivau, %0" :: "r"(p) : "memory");
        }
        __asm__ volatile("dsb sy" ::: "memory");
        __asm__ volatile("isb" ::: "memory");
    }
#endif
    return KIDO_OK;
}

kido_status_t kido_cache_icache_invalidate_all(void)
{
#ifdef KIDO_HOSTED_TEST
    kido_cache_record(5u, 0u, 0u, 1u, 1u);
#else
    __asm__ volatile("ic iallu" ::: "memory");
    __asm__ volatile("dsb sy" ::: "memory");
    __asm__ volatile("isb" ::: "memory");
#endif
    return KIDO_OK;
}

#ifdef KIDO_CACHE_SELFTEST
static int kido_cache_checks = 0;
static int kido_cache_failures = 0;

#define CACHE_CHECK(cond) do { \
    kido_cache_checks++; \
    if (!(cond)) { \
        kido_cache_failures++; \
        printf("[kido-cache] FAIL line %d: %s\n", __LINE__, #cond); \
    } \
} while (0)

int kido_cache_selftest_main(void)
{
    uint64_t size = 0u;
    uint64_t count = 99u;
    kido_cache_trace_t t;

    /* §1: NULL guards refuse, out-pointers untouched. */
    CACHE_CHECK(kido_cache_dline_size((uint64_t *)0) ==
                KIDO_ERR_EARLY_ENV);
    CACHE_CHECK(kido_cache_iline_size((uint64_t *)0) ==
                KIDO_ERR_EARLY_ENV);
    CACHE_CHECK(kido_cache_test_trace_count((uint64_t *)0) ==
                KIDO_ERR_EARLY_ENV);
    CACHE_CHECK(kido_cache_test_trace_at(0u, (kido_cache_trace_t *)0) ==
                KIDO_ERR_EARLY_ENV);
    CACHE_CHECK(kido_cache_test_trace_at(0u, &t) ==
                KIDO_ERR_EARLY_ENV);

    /* §2: line-size formula — 4 << field, both fields
     * independent. Defaults are 64/64. */
    CACHE_CHECK(kido_cache_dline_size(&size) == KIDO_OK && size == 64u);
    CACHE_CHECK(kido_cache_iline_size(&size) == KIDO_OK && size == 64u);
    CACHE_CHECK(kido_cache_test_set_dminline(6u) == KIDO_OK);
    CACHE_CHECK(kido_cache_dline_size(&size) == KIDO_OK && size == 256u);
    CACHE_CHECK(kido_cache_iline_size(&size) == KIDO_OK && size == 64u);
    CACHE_CHECK(kido_cache_test_set_iminline(5u) == KIDO_OK);
    CACHE_CHECK(kido_cache_iline_size(&size) == KIDO_OK && size == 128u);
    CACHE_CHECK(kido_cache_test_set_dminline(0u) == KIDO_OK);
    CACHE_CHECK(kido_cache_dline_size(&size) == KIDO_OK && size == 4u);
    /* Restore the defaults the later sections assume. */
    CACHE_CHECK(kido_cache_test_set_dminline(4u) == KIDO_OK);
    CACHE_CHECK(kido_cache_test_set_iminline(4u) == KIDO_OK);

    /* §3: range guards refuse loud, and record nothing. */
    CACHE_CHECK(kido_cache_test_trace_reset() == KIDO_OK);
    CACHE_CHECK(kido_cache_clean_range(0u, 64u) ==
                KIDO_ERR_EARLY_ENV);
    CACHE_CHECK(kido_cache_clean_range(0x1000u, 0u) ==
                KIDO_ERR_EARLY_ENV);
    CACHE_CHECK(kido_cache_clean_range((uintptr_t)~0ull, 64u) ==
                KIDO_ERR_EARLY_ENV);
    CACHE_CHECK(kido_cache_invalidate_range(0x1000u, 0u) ==
                KIDO_ERR_EARLY_ENV);
    CACHE_CHECK(kido_cache_test_trace_count(&count) == KIDO_OK &&
                count == 0u);

    /* §4: clean_range rounds out to whole lines (64-byte
     * lines): unaligned start down, unaligned end up. */
    CACHE_CHECK(kido_cache_test_trace_reset() == KIDO_OK);
    CACHE_CHECK(kido_cache_clean_range(0x1004u, 1u) == KIDO_OK);
    CACHE_CHECK(kido_cache_test_trace_count(&count) == KIDO_OK &&
                count == 1u);
    CACHE_CHECK(kido_cache_test_trace_at(0u, &t) == KIDO_OK &&
                t.kind == 0u && t.first == 0x1000u && t.lines == 1u &&
                t.dsb_after == 1u && t.isb_after == 0u);
    CACHE_CHECK(kido_cache_test_trace_reset() == KIDO_OK);
    CACHE_CHECK(kido_cache_clean_range(0x1000u, 65u) == KIDO_OK);
    CACHE_CHECK(kido_cache_test_trace_at(0u, &t) == KIDO_OK &&
                t.first == 0x1000u && t.lines == 2u);
    CACHE_CHECK(kido_cache_test_trace_reset() == KIDO_OK);
    CACHE_CHECK(kido_cache_clean_range(0x1040u, 64u) == KIDO_OK);
    CACHE_CHECK(kido_cache_test_trace_at(0u, &t) == KIDO_OK &&
                t.first == 0x1040u && t.lines == 1u);
    CACHE_CHECK(kido_cache_test_trace_reset() == KIDO_OK);
    CACHE_CHECK(kido_cache_clean_range(0x103cu, 4u) == KIDO_OK);
    CACHE_CHECK(kido_cache_test_trace_at(0u, &t) == KIDO_OK &&
                t.first == 0x1000u && t.lines == 1u);

    /* §5: invalidate_range — the C3 refusal. Aligned
     * passes; unaligned addr or len refuses and records
     * nothing; the refusal precedes any walk. */
    CACHE_CHECK(kido_cache_test_trace_reset() == KIDO_OK);
    CACHE_CHECK(kido_cache_invalidate_range(0x2000u, 128u) == KIDO_OK);
    CACHE_CHECK(kido_cache_test_trace_at(0u, &t) == KIDO_OK &&
                t.kind == 1u && t.first == 0x2000u && t.lines == 2u &&
                t.dsb_after == 1u);
    CACHE_CHECK(kido_cache_test_trace_reset() == KIDO_OK);
    CACHE_CHECK(kido_cache_invalidate_range(0x2004u, 64u) ==
                KIDO_ERR_EARLY_ENV);
    CACHE_CHECK(kido_cache_invalidate_range(0x2000u, 65u) ==
                KIDO_ERR_EARLY_ENV);
    CACHE_CHECK(kido_cache_invalidate_range(0x2000u, 0u) ==
                KIDO_ERR_EARLY_ENV);
    CACHE_CHECK(kido_cache_test_trace_count(&count) == KIDO_OK &&
                count == 0u);

    /* §6: clean_invalidate_range rounds like clean (no
     * C3 refusal — CIVAC writes back before it drops). */
    CACHE_CHECK(kido_cache_test_trace_reset() == KIDO_OK);
    CACHE_CHECK(kido_cache_clean_invalidate_range(0x3004u, 1u) ==
                KIDO_OK);
    CACHE_CHECK(kido_cache_test_trace_at(0u, &t) == KIDO_OK &&
                t.kind == 2u && t.first == 0x3000u && t.lines == 1u &&
                t.dsb_after == 1u && t.isb_after == 0u);

    /* §7: sync_icache_range records TWO walks, in
     * order, with DIFFERENT line sizes proving C2:
     * D=64, I=32 over [0x4000, 0x4100): CVAU 4 lines,
     * IVAU 8 lines, second entry carrying the ISB. */
    CACHE_CHECK(kido_cache_test_set_iminline(3u) == KIDO_OK);
    CACHE_CHECK(kido_cache_test_trace_reset() == KIDO_OK);
    CACHE_CHECK(kido_cache_sync_icache_range(0x4000u, 256u) == KIDO_OK);
    CACHE_CHECK(kido_cache_test_trace_count(&count) == KIDO_OK &&
                count == 2u);
    CACHE_CHECK(kido_cache_test_trace_at(0u, &t) == KIDO_OK &&
                t.kind == 3u && t.first == 0x4000u && t.lines == 4u &&
                t.dsb_after == 1u && t.isb_after == 0u);
    CACHE_CHECK(kido_cache_test_trace_at(1u, &t) == KIDO_OK &&
                t.kind == 4u && t.first == 0x4000u && t.lines == 8u &&
                t.dsb_after == 1u && t.isb_after == 1u);
    /* Same range, same sizes: an unaligned start rounds
     * both walks to the same first line, counts differ
     * only by line size. */
    CACHE_CHECK(kido_cache_test_trace_reset() == KIDO_OK);
    CACHE_CHECK(kido_cache_sync_icache_range(0x4004u, 33u) == KIDO_OK);
    CACHE_CHECK(kido_cache_test_trace_at(0u, &t) == KIDO_OK &&
                t.kind == 3u && t.lines == 1u);
    CACHE_CHECK(kido_cache_test_trace_at(1u, &t) == KIDO_OK &&
                t.kind == 4u && t.lines == 2u);
    CACHE_CHECK(kido_cache_test_set_iminline(4u) == KIDO_OK);
    /* Guards still refuse before either walk records. */
    CACHE_CHECK(kido_cache_test_trace_reset() == KIDO_OK);
    CACHE_CHECK(kido_cache_sync_icache_range(0u, 64u) ==
                KIDO_ERR_EARLY_ENV);
    CACHE_CHECK(kido_cache_test_trace_count(&count) == KIDO_OK &&
                count == 0u);

    /* §8: icache_invalidate_all records one entry, DSB
     * and ISB both set, and cannot fail. */
    CACHE_CHECK(kido_cache_test_trace_reset() == KIDO_OK);
    CACHE_CHECK(kido_cache_icache_invalidate_all() == KIDO_OK);
    CACHE_CHECK(kido_cache_test_trace_count(&count) == KIDO_OK &&
                count == 1u);
    CACHE_CHECK(kido_cache_test_trace_at(0u, &t) == KIDO_OK &&
                t.kind == 5u && t.lines == 0u &&
                t.dsb_after == 1u && t.isb_after == 1u);

    /* §9: trace log capacity and reset — reset clears,
     * out-of-range reads refuse, and the log holds
     * sequential entries in order. */
    CACHE_CHECK(kido_cache_test_trace_reset() == KIDO_OK);
    CACHE_CHECK(kido_cache_test_trace_count(&count) == KIDO_OK &&
                count == 0u);
    CACHE_CHECK(kido_cache_clean_range(0x5000u, 64u) == KIDO_OK);
    CACHE_CHECK(kido_cache_clean_range(0x6000u, 64u) == KIDO_OK);
    CACHE_CHECK(kido_cache_test_trace_count(&count) == KIDO_OK &&
                count == 2u);
    CACHE_CHECK(kido_cache_test_trace_at(0u, &t) == KIDO_OK &&
                t.first == 0x5000u);
    CACHE_CHECK(kido_cache_test_trace_at(1u, &t) == KIDO_OK &&
                t.first == 0x6000u);
    CACHE_CHECK(kido_cache_test_trace_at(2u, &t) ==
                KIDO_ERR_EARLY_ENV);
    CACHE_CHECK(kido_cache_test_trace_reset() == KIDO_OK);
    CACHE_CHECK(kido_cache_test_trace_count(&count) == KIDO_OK &&
                count == 0u);

    printf("[kido-cache] %d checks, %d failures\n",
           kido_cache_checks, kido_cache_failures);
    return kido_cache_failures;
}

int main(void)
{
    return kido_cache_selftest_main() != 0;
}
#endif /* KIDO_CACHE_SELFTEST */
