/*
 * kido-sync.c — Kido SMP spinlock.
 *
 * See kido-sync.h for the owner law, the IRQ law, the
 * dead-holder law, and the stated divergences. This file
 * is the real logic in two backends: ARM64 LDAXR/STLXR
 * inline asm (WRITTEN, NOT ASSEMBLED, NEVER EXECUTED —
 * toolchain absent, 17th data point), and a hosted path
 * over GCC __atomic builtins (real atomics, proving the
 * state machine exactly). The public functions are shared
 * across both backends; only the word manipulation differs.
 *
 * TESTING: gcc -std=c11 -Wall -Wextra -Werror -DKIDO_HOSTED_TEST
 *        -DKIDO_SYNC_SELFTEST kido-sync.c -o sync-selftest
 */
#include "kido-sync.h"

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

/* ------------------------------------------------------------------ */
/* CPU identity. ARM64: MPIDR_EL1 raw, never parsed (the smp/psci    */
/* opaque-affinity law). Hosted: the injector's value.                */
/* ------------------------------------------------------------------ */
#ifdef KIDO_HOSTED_TEST
static uint64_t kido_sync_host_cpu = 0u;

static uint64_t kido_sync_cpu_id(void)
{
    return kido_sync_host_cpu;
}

kido_status_t kido_sync_test_set_cpu_id(uint64_t cpu_id)
{
    if (cpu_id == KIDO_SYNC_OWNER_FREE)
        return KIDO_ERR_EARLY_ENV; /* the free sentinel is not a CPU */
    kido_sync_host_cpu = cpu_id;
    return KIDO_OK;
}
#else /* bare metal */
static uint64_t kido_sync_cpu_id(void)
{
    uint64_t id = 0u;
    __asm__ volatile("mrs %[id], mpidr_el1" : [id] "=r" (id));
    return id;
}
#endif /* KIDO_HOSTED_TEST */

/* ------------------------------------------------------------------ */
/* Word manipulation: one exclusive attempt, the spinning take,       */
/* and the release store. ARM64 asm first, hosted atomics second.     */
/* ------------------------------------------------------------------ */
#if defined(__aarch64__) && !defined(KIDO_HOSTED_TEST)
/* Single LDAXR/STLXR attempt. Returns 1 on take, 0 otherwise.
 * On the observed-held path the monitor is cleared with
 * CLREX before returning (a failed STLXR already clears
 * it; CLREX there is harmless). */
static int kido_sync_exclusive_try(volatile uint32_t *word)
{
    uint32_t loaded = 0u;
    uint32_t status = 0u;
    const uint32_t one = 1u;
    __asm__ volatile(
        "ldaxr %w[loaded], [%[ptr]]\n\t"
        "cbnz %w[loaded], 1f\n\t"
        "stlxr %w[status], %w[one], [%[ptr]]\n\t"
        "cbz %w[status], 2f\n\t"
        "1: clrex\n\t"
        "2:\n\t"
        : [loaded] "=&r" (loaded), [status] "=&r" (status)
        : [ptr] "r" (word), [one] "r" (one)
        : "memory");
    return (loaded == 0u && status == 0u) ? 1 : 0;
}

/* Spinning take. SEVL primes the first iteration so a lock
 * freed before we arrive never makes us sleep. WFE sits
 * ONLY on the observed-held branch (deliberation C5): a
 * failed STLXR retries the LDAXR immediately, never
 * through WFE, or a spurious failure with a free lock
 * and no future SEV could sleep forever. */
static void kido_sync_exclusive_lock(volatile uint32_t *word)
{
    uint32_t loaded = 0u;
    uint32_t status = 0u;
    const uint32_t one = 1u;
    __asm__ volatile(
        "sevl\n\t"
        "1: wfe\n\t"
        "2: ldaxr %w[loaded], [%[ptr]]\n\t"
        "   cbnz %w[loaded], 1b\n\t"
        "   stlxr %w[status], %w[one], [%[ptr]]\n\t"
        "   cbnz %w[status], 2b\n\t"
        : [loaded] "=&r" (loaded), [status] "=&r" (status)
        : [ptr] "r" (word), [one] "r" (one)
        : "memory");
}

/* Release: STLR (release store of zero) + SEV to wake
 * WFE sleepers. The caller's owner-clear precedes this
 * call and is ordered before it by STLR's release
 * semantics (plus the "memory" clobber against compiler
 * reordering). */
static void kido_sync_exclusive_unlock(volatile uint32_t *word)
{
    const uint32_t zero = 0u;
    __asm__ volatile(
        "stlr %w[zero], [%[ptr]]\n\t"
        "sev\n\t"
        : /* no outputs */
        : [ptr] "r" (word), [zero] "r" (zero)
        : "memory");
}
#else /* hosted atomics: real exclusion, state-machine proof */
static int kido_sync_exclusive_try(volatile uint32_t *word)
{
    uint32_t expected = 0u;
    return __atomic_compare_exchange_n(word, &expected, 1u, 0,
                                       __ATOMIC_ACQUIRE,
                                       __ATOMIC_RELAXED) ? 1 : 0;
}

static void kido_sync_exclusive_lock(volatile uint32_t *word)
{
    uint32_t expected = 0u;
    while (!__atomic_compare_exchange_n(word, &expected, 1u, 0,
                                        __ATOMIC_ACQUIRE,
                                        __ATOMIC_RELAXED))
        expected = 0u; /* compare_exchange rewrites it on failure */
}

static void kido_sync_exclusive_unlock(volatile uint32_t *word)
{
    __atomic_store_n(word, 0u, __ATOMIC_RELEASE);
}
#endif /* backend */

/* A lock is usable only after init() stamped its magic.
 * Zeroed BSS reads magic 0, which refuses — an
 * uninitialized lock fails loud, never silently. */
static int kido_sync_valid(const kido_spinlock_t *lock)
{
    return lock != NULL && lock->magic == KIDO_SYNC_MAGIC;
}

kido_status_t kido_spin_init(kido_spinlock_t *lock)
{
    if (lock == NULL)
        return KIDO_ERR_EARLY_ENV;
    /* A properly initialized HELD lock must never be
     * silently freed under its holder (deliberation C7).
     * An uninitialized lock (bad magic) is construction
     * material, not a live lock: init claims it. */
    if (lock->magic == KIDO_SYNC_MAGIC && lock->word != 0u)
        return KIDO_ERR_EARLY_ENV;
    /* init() is a construction-time call, not a concurrent
     * one: the caller initializes before sharing the lock.
     * Plain stores are correct here by that contract. */
    lock->word = 0u;
    lock->owner = KIDO_SYNC_OWNER_FREE;
    lock->magic = KIDO_SYNC_MAGIC;
    return KIDO_OK;
}

kido_status_t kido_spin_lock(kido_spinlock_t *lock)
{
    if (!kido_sync_valid(lock))
        return KIDO_ERR_EARLY_ENV;
    kido_sync_exclusive_lock(&lock->word);
    /* Only the holder writes owner, and the acquire
     * orders this write after the take. */
    lock->owner = kido_sync_cpu_id();
    return KIDO_OK;
}

kido_status_t kido_spin_try_lock(kido_spinlock_t *lock,
                                  uint32_t *acquired)
{
    int took = 0;
    if (!kido_sync_valid(lock))
        return KIDO_ERR_EARLY_ENV;
    if (acquired == NULL)
        return KIDO_ERR_EARLY_ENV;
    took = kido_sync_exclusive_try(&lock->word);
    if (took)
        lock->owner = kido_sync_cpu_id();
    *acquired = took ? 1u : 0u;
    return KIDO_OK;
}

kido_status_t kido_spin_unlock(kido_spinlock_t *lock)
{
    if (!kido_sync_valid(lock))
        return KIDO_ERR_EARLY_ENV;
    if (lock->word == 0u)
        return KIDO_ERR_EARLY_ENV; /* unlocking a free lock */
    if (lock->owner != kido_sync_cpu_id())
        return KIDO_ERR_EARLY_ENV; /* stranger's unlock: refused, held */
    /* Clear owner BEFORE the release store: STLR's release
     * semantics order the clear before the unlock lands. */
    lock->owner = KIDO_SYNC_OWNER_FREE;
    kido_sync_exclusive_unlock(&lock->word);
    return KIDO_OK;
}

kido_status_t kido_spin_is_locked(kido_spinlock_t *lock,
                                   uint32_t *locked)
{
    if (!kido_sync_valid(lock))
        return KIDO_ERR_EARLY_ENV;
    if (locked == NULL)
        return KIDO_ERR_EARLY_ENV;
    /* Snapshot law: one plain read, no synchronization
     * claim. Another CPU may move the lock next instant. */
    *locked = (lock->word != 0u) ? 1u : 0u;
    return KIDO_OK;
}

#ifdef KIDO_SYNC_SELFTEST
#define SYNC_CHECK(cond) do { \
    kido_sync_checks++; \
    if (!(cond)) { \
        kido_sync_failures++; \
        printf("[FAIL] line %d: %s\n", __LINE__, #cond); \
    } \
} while (0)

static int kido_sync_checks = 0;
static int kido_sync_failures = 0;

int kido_sync_selftest_main(void)
{
    kido_spinlock_t lock;
    kido_spinlock_t raw; /* never init()ed: magic garbage path */
    uint32_t acq = 99u;
    uint32_t locked = 99u;

    /* §1: NULL + uninitialized guards — every call refuses. */
    SYNC_CHECK(kido_spin_init(NULL) == KIDO_ERR_EARLY_ENV);
    SYNC_CHECK(kido_spin_lock(NULL) == KIDO_ERR_EARLY_ENV);
    SYNC_CHECK(kido_spin_try_lock(NULL, &acq) == KIDO_ERR_EARLY_ENV);
    SYNC_CHECK(kido_spin_unlock(NULL) == KIDO_ERR_EARLY_ENV);
    SYNC_CHECK(kido_spin_is_locked(NULL, &locked) == KIDO_ERR_EARLY_ENV);
    raw.word = 0u;
    raw.magic = 0u; /* zeroed BSS shape: not initialized */
    raw.owner = KIDO_SYNC_OWNER_FREE;
    SYNC_CHECK(kido_spin_lock(&raw) == KIDO_ERR_EARLY_ENV);
    SYNC_CHECK(kido_spin_try_lock(&raw, &acq) == KIDO_ERR_EARLY_ENV);
    SYNC_CHECK(kido_spin_unlock(&raw) == KIDO_ERR_EARLY_ENV);
    SYNC_CHECK(kido_spin_is_locked(&raw, &locked) == KIDO_ERR_EARLY_ENV);
    SYNC_CHECK(acq == 99u); /* refused try_lock leaves out untouched */
    SYNC_CHECK(locked == 99u);

    /* §2: init stamps the lock free; NULL out-pointers refuse. */
    SYNC_CHECK(kido_spin_init(&lock) == KIDO_OK);
    SYNC_CHECK(lock.word == 0u);
    SYNC_CHECK(lock.magic == KIDO_SYNC_MAGIC);
    SYNC_CHECK(lock.owner == KIDO_SYNC_OWNER_FREE);
    SYNC_CHECK(kido_spin_try_lock(&lock, NULL) == KIDO_ERR_EARLY_ENV);
    SYNC_CHECK(kido_spin_is_locked(&lock, NULL) == KIDO_ERR_EARLY_ENV);
    SYNC_CHECK(kido_spin_is_locked(&lock, &locked) == KIDO_OK &&
               locked == 0u);

    /* §3: take, contend, snapshot — contention is a fact,
     * not a failure (deliberation C1). */
    SYNC_CHECK(kido_spin_lock(&lock) == KIDO_OK);
    SYNC_CHECK(lock.word == 1u);
    SYNC_CHECK(lock.owner == 0u); /* hosted CPU id defaults to 0 */
    SYNC_CHECK(kido_spin_is_locked(&lock, &locked) == KIDO_OK &&
               locked == 1u);
    SYNC_CHECK(kido_spin_try_lock(&lock, &acq) == KIDO_OK &&
               acq == 0u); /* contended: OK + acquired 0 */
    SYNC_CHECK(lock.word == 1u); /* contention leaves it held */
    SYNC_CHECK(lock.owner == 0u);
    SYNC_CHECK(kido_spin_init(&lock) == KIDO_ERR_EARLY_ENV);
    SYNC_CHECK(lock.word == 1u); /* refused init leaves it held */

    /* §4: stranger unlock refuses, lock untouched; owner
     * unlock frees. The injector plays the second CPU. */
    SYNC_CHECK(kido_sync_test_set_cpu_id(KIDO_SYNC_OWNER_FREE) ==
               KIDO_ERR_EARLY_ENV); /* free sentinel is not a CPU */
    SYNC_CHECK(kido_sync_test_set_cpu_id(1u) == KIDO_OK);
    SYNC_CHECK(kido_spin_unlock(&lock) == KIDO_ERR_EARLY_ENV);
    SYNC_CHECK(lock.word == 1u);
    SYNC_CHECK(lock.owner == 0u);
    SYNC_CHECK(kido_sync_test_set_cpu_id(0u) == KIDO_OK);
    SYNC_CHECK(kido_spin_unlock(&lock) == KIDO_OK);
    SYNC_CHECK(lock.word == 0u);
    SYNC_CHECK(lock.owner == KIDO_SYNC_OWNER_FREE);
    SYNC_CHECK(kido_spin_is_locked(&lock, &locked) == KIDO_OK &&
               locked == 0u);

    /* §5: unlock of a free lock refuses; try_lock takes
     * and records the taking CPU. */
    SYNC_CHECK(kido_spin_unlock(&lock) == KIDO_ERR_EARLY_ENV);
    SYNC_CHECK(kido_sync_test_set_cpu_id(7u) == KIDO_OK);
    SYNC_CHECK(kido_spin_try_lock(&lock, &acq) == KIDO_OK &&
               acq == 1u);
    SYNC_CHECK(lock.owner == 7u);
    SYNC_CHECK(kido_spin_unlock(&lock) == KIDO_OK);
    SYNC_CHECK(kido_sync_test_set_cpu_id(0u) == KIDO_OK);

    /* §6: re-init on a free, previously used lock succeeds
     * and resets owner; the lock is usable again. */
    SYNC_CHECK(kido_spin_init(&lock) == KIDO_OK);
    SYNC_CHECK(lock.word == 0u);
    SYNC_CHECK(lock.owner == KIDO_SYNC_OWNER_FREE);
    SYNC_CHECK(kido_spin_lock(&lock) == KIDO_OK);
    SYNC_CHECK(lock.owner == 0u);
    SYNC_CHECK(kido_spin_unlock(&lock) == KIDO_OK);

    printf("[kido-sync] %d checks, %d failures\n",
           kido_sync_checks, kido_sync_failures);
    return kido_sync_failures;
}

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