/*
 * kido-call.c — Kido cross-CPU function mailbox.
 *
 * See kido-call.h for the state machine, the poster law,
 * the poll-first law, and the stated divergences. This
 * file is shared portable C on top of kido-sync's public
 * API. No MMIO, no asm, no scheduler, no ipi, no GIC.
 * Pthreads live in the TEST TU ONLY (the barrier
 * precedent): the module compiles clean without -pthread.
 *
 * LOCK ORDER LAW (deliberation, P2): the slot lock is
 * always taken before the stats lock, never the reverse.
 * The stats lock is held only across one counter
 * increment — no function calls inside it — so its
 * holder always progresses (no dead-holder trap). The
 * slot lock is never held across a function body
 * (deliberation C3): poll() claims, unlocks, runs,
 * relocks, stores.
 *
 * TESTING: gcc -std=c11 -Wall -Wextra -Werror -pthread
 *        -DKIDO_HOSTED_TEST -DKIDO_CALL_SELFTEST
 *        kido-call.c kido-sync.c -o call-selftest
 */
#include "kido-call.h"

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

/* Poster sentinel: no poster. Only ever stored beside
 * EMPTY; the stranger check runs only on non-EMPTY
 * slots, so the sentinel never meets a real CPU id. */
#define KIDO_CALL_POSTER_NONE ((uint32_t)~0u)

/* One slot: the target CPU's mailbox cell. The lock
 * guards every field except state reads by the
 * diagnostic snapshot (snapshot law: one read). */
typedef struct kido_call_slot {
    kido_spinlock_t  lock;
    kido_call_state_t state;
    uint32_t         poster;
    kido_call_fn_t   fn;
    void            *arg;
    kido_status_t    result;
} kido_call_slot_t;

static uint32_t        g_magic;
static kido_call_slot_t g_slots[KIDO_CALL_MAX_CPUS];
static kido_call_stats_t g_stats;
static kido_spinlock_t g_stats_lock;

static int kido_call_ready(void)
{
    return g_magic == KIDO_CALL_MAGIC;
}

kido_status_t kido_call_init(void)
{
    uint32_t i;
    kido_status_t st;

    /* Refusal precedes any touch (barrier in-flight
     * precedent): a busy slot keeps the whole table. */
    for (i = 0u; i < KIDO_CALL_MAX_CPUS; i++) {
        if (g_slots[i].state != KIDO_CALL_EMPTY) {
            return KIDO_ERR_EARLY_ENV;
        }
    }
    st = kido_spin_init(&g_stats_lock);
    if (st != KIDO_OK) {
        return st;
    }
    for (i = 0u; i < KIDO_CALL_MAX_CPUS; i++) {
        st = kido_spin_init(&g_slots[i].lock);
        if (st != KIDO_OK) {
            return st;
        }
        g_slots[i].state = KIDO_CALL_EMPTY;
        g_slots[i].poster = KIDO_CALL_POSTER_NONE;
        g_slots[i].fn = NULL;
        g_slots[i].arg = NULL;
        g_slots[i].result = KIDO_OK;
    }
    g_stats.posted = 0u;
    g_stats.busy = 0u;
    g_stats.completed = 0u;
    g_stats.reaped = 0u;
    g_stats.stranger = 0u;
    g_magic = KIDO_CALL_MAGIC;
    return KIDO_OK;
}

kido_status_t kido_call_post(uint32_t source_cpu, uint32_t target_cpu,
                             kido_call_fn_t fn, void *arg,
                             uint32_t *accepted)
{
    kido_call_slot_t *slot;
    kido_status_t st;

    if (!kido_call_ready()) {
        return KIDO_ERR_EARLY_ENV;
    }
    if (fn == NULL || accepted == NULL) {
        return KIDO_ERR_EARLY_ENV;
    }
    if (source_cpu >= KIDO_CALL_MAX_CPUS ||
        target_cpu >= KIDO_CALL_MAX_CPUS) {
        return KIDO_ERR_EARLY_ENV;
    }
    slot = &g_slots[target_cpu];
    st = kido_spin_lock(&slot->lock);
    if (st != KIDO_OK) {
        return st;
    }
    if (slot->state != KIDO_CALL_EMPTY) {
        /* The door, not an error: busy is counted, the
         * waiting call is untouched. */
        (void)kido_spin_lock(&g_stats_lock);
        g_stats.busy++;
        (void)kido_spin_unlock(&g_stats_lock);
        (void)kido_spin_unlock(&slot->lock);
        *accepted = 0u;
        return KIDO_OK;
    }
    slot->fn = fn;
    slot->arg = arg;
    slot->poster = source_cpu;
    slot->state = KIDO_CALL_POSTED;
    (void)kido_spin_lock(&g_stats_lock);
    g_stats.posted++;
    (void)kido_spin_unlock(&g_stats_lock);
    (void)kido_spin_unlock(&slot->lock);
    *accepted = 1u;
    return KIDO_OK;
}

kido_status_t kido_call_poll(uint32_t cpu)
{
    kido_call_slot_t *slot;
    kido_call_fn_t fn;
    void *arg;
    kido_status_t result;
    kido_status_t st;

    if (!kido_call_ready()) {
        return KIDO_ERR_EARLY_ENV;
    }
    if (cpu >= KIDO_CALL_MAX_CPUS) {
        return KIDO_ERR_EARLY_ENV;
    }
    slot = &g_slots[cpu];
    st = kido_spin_lock(&slot->lock);
    if (st != KIDO_OK) {
        return st;
    }
    if (slot->state != KIDO_CALL_POSTED) {
        /* EMPTY, RUNNING, or DONE: nothing to claim. */
        (void)kido_spin_unlock(&slot->lock);
        return KIDO_OK;
    }
    /* Claim under the lock, then RUN OUTSIDE it
     * (deliberation C3). */
    fn = slot->fn;
    arg = slot->arg;
    slot->state = KIDO_CALL_RUNNING;
    (void)kido_spin_unlock(&slot->lock);
    result = fn(arg);
    st = kido_spin_lock(&slot->lock);
    if (st != KIDO_OK) {
        /* The claim is lost, not the result: the slot
         * stays RUNNING rather than reporting a DONE
         * that was never stored. A lock failure here is
         * a broken lock, and it is propagated loud. */
        return st;
    }
    slot->result = result;
    slot->state = KIDO_CALL_DONE;
    (void)kido_spin_lock(&g_stats_lock);
    g_stats.completed++;
    (void)kido_spin_unlock(&g_stats_lock);
    (void)kido_spin_unlock(&slot->lock);
    return KIDO_OK;
}

kido_status_t kido_call_reap(uint32_t source_cpu, uint32_t target_cpu,
                             uint32_t *done, kido_status_t *result)
{
    kido_call_slot_t *slot;
    kido_status_t st;

    if (!kido_call_ready()) {
        return KIDO_ERR_EARLY_ENV;
    }
    if (done == NULL || result == NULL) {
        return KIDO_ERR_EARLY_ENV;
    }
    if (source_cpu >= KIDO_CALL_MAX_CPUS ||
        target_cpu >= KIDO_CALL_MAX_CPUS) {
        return KIDO_ERR_EARLY_ENV;
    }
    slot = &g_slots[target_cpu];
    st = kido_spin_lock(&slot->lock);
    if (st != KIDO_OK) {
        return st;
    }
    if (slot->state != KIDO_CALL_EMPTY &&
        slot->poster != source_cpu) {
        /* Stranger refusal (poster law): the slot is
         * untouched, the attempt is counted. */
        (void)kido_spin_lock(&g_stats_lock);
        g_stats.stranger++;
        (void)kido_spin_unlock(&g_stats_lock);
        (void)kido_spin_unlock(&slot->lock);
        return KIDO_ERR_EARLY_ENV;
    }
    if (slot->state != KIDO_CALL_DONE) {
        /* POSTED, RUNNING, or EMPTY: nothing to reap. */
        (void)kido_spin_unlock(&slot->lock);
        *done = 0u;
        return KIDO_OK;
    }
    *result = slot->result;
    slot->state = KIDO_CALL_EMPTY;
    slot->poster = KIDO_CALL_POSTER_NONE;
    slot->fn = NULL;
    slot->arg = NULL;
    slot->result = KIDO_OK;
    (void)kido_spin_lock(&g_stats_lock);
    g_stats.reaped++;
    (void)kido_spin_unlock(&g_stats_lock);
    (void)kido_spin_unlock(&slot->lock);
    *done = 1u;
    return KIDO_OK;
}

kido_status_t kido_call_state(uint32_t target_cpu,
                              kido_call_state_t *state)
{
    if (!kido_call_ready()) {
        return KIDO_ERR_EARLY_ENV;
    }
    if (state == NULL || target_cpu >= KIDO_CALL_MAX_CPUS) {
        return KIDO_ERR_EARLY_ENV;
    }
    /* One read, no lock: a diagnostic snapshot, never a
     * synchronization point (snapshot law). */
    *state = g_slots[target_cpu].state;
    return KIDO_OK;
}

kido_status_t kido_call_stats(kido_call_stats_t *out)
{
    kido_status_t st;

    if (!kido_call_ready()) {
        return KIDO_ERR_EARLY_ENV;
    }
    if (out == NULL) {
        return KIDO_ERR_EARLY_ENV;
    }
    st = kido_spin_lock(&g_stats_lock);
    if (st != KIDO_OK) {
        return st;
    }
    *out = g_stats;
    (void)kido_spin_unlock(&g_stats_lock);
    return KIDO_OK;
}

#ifdef KIDO_CALL_SELFTEST
/* ------------------------------------------------------------------ */
/* Self-test. pthreads live here only (barrier precedent).            */
/* ------------------------------------------------------------------ */
static int g_checks;
static int g_failures;

#define CALL_CHECK(cond) do { \
    g_checks++; \
    if (!(cond)) { \
        g_failures++; \
        printf("CALL FAIL line %d: %s\n", __LINE__, #cond); \
    } \
} while (0)

static int g_add_value;
static int g_add_calls;
static pthread_t g_poller_tid;
static pthread_t g_fn_tid;

static kido_status_t call_add_fn(void *arg)
{
    (void)arg;
    g_add_value += 10;
    g_add_calls++;
    return KIDO_OK;
}

static kido_status_t call_err_fn(void *arg)
{
    (void)arg;
    return KIDO_ERR_EARLY_ENV;
}

static kido_status_t call_mark_fn(void *arg)
{
    (void)arg;
    g_fn_tid = pthread_self();
    return KIDO_OK;
}

static void *call_poller_thread(void *arg)
{
    uint32_t cpu = *(uint32_t *)arg;
    g_poller_tid = pthread_self();
    (void)kido_call_poll(cpu);
    return NULL;
}

int kido_call_selftest_main(void)
{
    uint32_t accepted = 99u;
    uint32_t done = 99u;
    kido_status_t result = KIDO_ERR_STUB_REACHED;
    kido_call_state_t state = KIDO_CALL_DONE;
    kido_call_stats_t stats;
    pthread_t th;
    uint32_t poll_cpu = 5u;

    /* §0: pre-init refusals — every API fails loud. */
    CALL_CHECK(kido_call_post(0u, 1u, call_add_fn, NULL, &accepted)
               == KIDO_ERR_EARLY_ENV);
    CALL_CHECK(kido_call_poll(1u) == KIDO_ERR_EARLY_ENV);
    CALL_CHECK(kido_call_reap(0u, 1u, &done, &result)
               == KIDO_ERR_EARLY_ENV);
    CALL_CHECK(kido_call_state(1u, &state) == KIDO_ERR_EARLY_ENV);
    CALL_CHECK(kido_call_stats(&stats) == KIDO_ERR_EARLY_ENV);

    /* §1: init builds the world; stats start at zero. */
    CALL_CHECK(kido_call_init() == KIDO_OK);
    CALL_CHECK(kido_call_stats(&stats) == KIDO_OK);
    CALL_CHECK(stats.posted == 0u && stats.busy == 0u &&
               stats.completed == 0u && stats.reaped == 0u &&
               stats.stranger == 0u);

    /* §2: post guards — misuse is loud, never a silent drop. */
    accepted = 99u;
    CALL_CHECK(kido_call_post(0u, 1u, NULL, NULL, &accepted)
               == KIDO_ERR_EARLY_ENV);
    CALL_CHECK(accepted == 99u);
    CALL_CHECK(kido_call_post(0u, 1u, call_add_fn, NULL, NULL)
               == KIDO_ERR_EARLY_ENV);
    CALL_CHECK(kido_call_post(8u, 1u, call_add_fn, NULL, &accepted)
               == KIDO_ERR_EARLY_ENV);
    CALL_CHECK(kido_call_post(0u, 8u, call_add_fn, NULL, &accepted)
               == KIDO_ERR_EARLY_ENV);
    CALL_CHECK(kido_call_poll(8u) == KIDO_ERR_EARLY_ENV);
    CALL_CHECK(kido_call_reap(0u, 8u, &done, &result)
               == KIDO_ERR_EARLY_ENV);
    CALL_CHECK(kido_call_reap(0u, 1u, NULL, &result)
               == KIDO_ERR_EARLY_ENV);
    CALL_CHECK(kido_call_reap(0u, 1u, &done, NULL)
               == KIDO_ERR_EARLY_ENV);
    CALL_CHECK(kido_call_state(8u, &state) == KIDO_ERR_EARLY_ENV);
    CALL_CHECK(kido_call_state(1u, NULL) == KIDO_ERR_EARLY_ENV);
    CALL_CHECK(kido_call_stats(NULL) == KIDO_ERR_EARLY_ENV);

    /* §3: the lifecycle — post, reap-not-done, poll, reap. */
    g_add_value = 0;
    g_add_calls = 0;
    CALL_CHECK(kido_call_post(0u, 1u, call_add_fn, NULL, &accepted)
               == KIDO_OK && accepted == 1u);
    CALL_CHECK(kido_call_state(1u, &state) == KIDO_OK &&
               state == KIDO_CALL_POSTED);
    done = 99u;
    CALL_CHECK(kido_call_reap(0u, 1u, &done, &result) == KIDO_OK &&
               done == 0u);
    CALL_CHECK(g_add_calls == 0);
    CALL_CHECK(kido_call_poll(1u) == KIDO_OK);
    CALL_CHECK(g_add_value == 10 && g_add_calls == 1);
    CALL_CHECK(kido_call_state(1u, &state) == KIDO_OK &&
               state == KIDO_CALL_DONE);
    done = 99u;
    result = KIDO_ERR_STUB_REACHED;
    CALL_CHECK(kido_call_reap(0u, 1u, &done, &result) == KIDO_OK &&
               done == 1u && result == KIDO_OK);
    CALL_CHECK(kido_call_state(1u, &state) == KIDO_OK &&
               state == KIDO_CALL_EMPTY);
    done = 99u;
    CALL_CHECK(kido_call_reap(0u, 1u, &done, &result) == KIDO_OK &&
               done == 0u);

    /* §4: a function returning an error stores the error. */
    CALL_CHECK(kido_call_post(0u, 1u, call_err_fn, NULL, &accepted)
               == KIDO_OK && accepted == 1u);
    CALL_CHECK(kido_call_poll(1u) == KIDO_OK);
    done = 99u;
    result = KIDO_OK;
    CALL_CHECK(kido_call_reap(0u, 1u, &done, &result) == KIDO_OK &&
               done == 1u && result == KIDO_ERR_EARLY_ENV);

    /* §5: busy door — second post refused, first intact. */
    g_add_value = 0;
    g_add_calls = 0;
    CALL_CHECK(kido_call_post(0u, 2u, call_add_fn, NULL, &accepted)
               == KIDO_OK && accepted == 1u);
    CALL_CHECK(kido_call_post(0u, 2u, call_err_fn, NULL, &accepted)
               == KIDO_OK && accepted == 0u);
    CALL_CHECK(kido_call_poll(2u) == KIDO_OK);
    CALL_CHECK(g_add_value == 10 && g_add_calls == 1);
    done = 99u;
    result = KIDO_ERR_STUB_REACHED;
    CALL_CHECK(kido_call_reap(0u, 2u, &done, &result) == KIDO_OK &&
               done == 1u && result == KIDO_OK);

    /* §6: stranger reap — refused at POSTED and at DONE,
     * slot untouched both times, owner reaps clean. */
    CALL_CHECK(kido_call_post(0u, 3u, call_add_fn, NULL, &accepted)
               == KIDO_OK && accepted == 1u);
    CALL_CHECK(kido_call_reap(1u, 3u, &done, &result)
               == KIDO_ERR_EARLY_ENV);
    CALL_CHECK(kido_call_state(3u, &state) == KIDO_OK &&
               state == KIDO_CALL_POSTED);
    CALL_CHECK(kido_call_poll(3u) == KIDO_OK);
    CALL_CHECK(kido_call_reap(1u, 3u, &done, &result)
               == KIDO_ERR_EARLY_ENV);
    CALL_CHECK(kido_call_state(3u, &state) == KIDO_OK &&
               state == KIDO_CALL_DONE);
    done = 99u;
    CALL_CHECK(kido_call_reap(0u, 3u, &done, &result) == KIDO_OK &&
               done == 1u);

    /* §7: self-post is allowed, no special case. */
    CALL_CHECK(kido_call_post(2u, 2u, call_add_fn, NULL, &accepted)
               == KIDO_OK && accepted == 1u);
    CALL_CHECK(kido_call_poll(2u) == KIDO_OK);
    done = 99u;
    CALL_CHECK(kido_call_reap(2u, 2u, &done, &result) == KIDO_OK &&
               done == 1u);

    /* §8: re-init refuses over a busy slot, succeeds empty. */
    CALL_CHECK(kido_call_post(0u, 4u, call_add_fn, NULL, &accepted)
               == KIDO_OK && accepted == 1u);
    CALL_CHECK(kido_call_init() == KIDO_ERR_EARLY_ENV);
    CALL_CHECK(kido_call_state(4u, &state) == KIDO_OK &&
               state == KIDO_CALL_POSTED);
    CALL_CHECK(kido_call_poll(4u) == KIDO_OK);
    done = 99u;
    CALL_CHECK(kido_call_reap(0u, 4u, &done, &result) == KIDO_OK &&
               done == 1u);
    CALL_CHECK(kido_call_init() == KIDO_OK);
    CALL_CHECK(kido_call_stats(&stats) == KIDO_OK);
    CALL_CHECK(stats.posted == 0u && stats.busy == 0u &&
               stats.completed == 0u && stats.reaped == 0u &&
               stats.stranger == 0u);
    CALL_CHECK(kido_call_state(4u, &state) == KIDO_OK &&
               state == KIDO_CALL_EMPTY);

    /* §9: poll no-ops — EMPTY and DONE poll change nothing. */
    CALL_CHECK(kido_call_poll(6u) == KIDO_OK);
    CALL_CHECK(kido_call_post(0u, 6u, call_add_fn, NULL, &accepted)
               == KIDO_OK && accepted == 1u);
    CALL_CHECK(kido_call_poll(6u) == KIDO_OK);
    CALL_CHECK(kido_call_stats(&stats) == KIDO_OK &&
               stats.completed == 1u);
    CALL_CHECK(kido_call_poll(6u) == KIDO_OK);
    CALL_CHECK(kido_call_stats(&stats) == KIDO_OK &&
               stats.completed == 1u);
    done = 99u;
    CALL_CHECK(kido_call_reap(0u, 6u, &done, &result) == KIDO_OK &&
               done == 1u);

    /* §10: stats pinned exactly on a fresh table. */
    CALL_CHECK(kido_call_init() == KIDO_OK);
    CALL_CHECK(kido_call_post(0u, 7u, call_add_fn, NULL, &accepted)
               == KIDO_OK && accepted == 1u);
    CALL_CHECK(kido_call_post(0u, 7u, call_add_fn, NULL, &accepted)
               == KIDO_OK && accepted == 0u);
    CALL_CHECK(kido_call_reap(1u, 7u, &done, &result)
               == KIDO_ERR_EARLY_ENV);
    CALL_CHECK(kido_call_poll(7u) == KIDO_OK);
    done = 99u;
    CALL_CHECK(kido_call_reap(0u, 7u, &done, &result) == KIDO_OK &&
               done == 1u);
    CALL_CHECK(kido_call_stats(&stats) == KIDO_OK);
    CALL_CHECK(stats.posted == 1u && stats.busy == 1u &&
               stats.completed == 1u && stats.reaped == 1u &&
               stats.stranger == 1u);

    /* §11: pthread proof — the function runs on the
     * poller's thread, not the poster's. */
    CALL_CHECK(kido_call_init() == KIDO_OK);
    g_fn_tid = (pthread_t)0;
    g_poller_tid = (pthread_t)0;
    CALL_CHECK(kido_call_post(0u, 5u, call_mark_fn, NULL, &accepted)
               == KIDO_OK && accepted == 1u);
    CALL_CHECK(pthread_create(&th, NULL, call_poller_thread, &poll_cpu)
               == 0);
    CALL_CHECK(pthread_join(th, NULL) == 0);
    CALL_CHECK(!pthread_equal(g_fn_tid, (pthread_t)0));
    CALL_CHECK(pthread_equal(g_fn_tid, g_poller_tid));
    done = 99u;
    CALL_CHECK(kido_call_reap(0u, 5u, &done, &result) == KIDO_OK &&
               done == 1u && result == KIDO_OK);

    printf("kido-call self-test: %d checks, %d failures\n",
           g_checks, g_failures);
    return g_failures != 0;
}

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