/*
 * kido-psci.h — Kido ARM Power State Coordination Interface (PSCI)
 * conduit, public interface.
 *
 * The tree has drivers for the timer, the GIC, the UART, the
 * mailbox, the MMU — and no way to turn anything off, reset
 * the machine, or wake a second CPU. PSCI is that missing
 * piece: the firmware call layer (ARM DEN0022) by which an
 * EL1 kernel asks the secure monitor to suspend, power down,
 * or power up CPUs, and to shut down or reset the system.
 * Kido is UP today (the scheduler is single-CPU by law), so
 * CPU_ON is a conduit, not an SMP claim: it is how a future
 * second CPU would ever start, and how CPU_OFF is undone.
 *
 * CONDUIT: SMC only, SMC32/SMC64 IDs per DEN0022 (SMCCC).
 * The call is `smc #0` with the function ID in x0, arguments
 * in x1-x3, the result back in x0. HVC is the hypervisor
 * conduit (EL2, no EL3) and is a named future for a
 * hosted-Kido caller — Kido runs EL1 under a monitor, so
 * SMC is the conduit here. A call made with no monitor
 * present faults at the SMC itself; the driver cannot
 * detect that, which is why init is a caller-gated call
 * and is NOT wired into the boot path (Gate item).
 *
 * FUNCTION IDs (DEN0022, PSCI 0.2 core + 1.0 FEATURES):
 *   PSCI_VERSION   0x84000000  (major<<16 | minor)
 *   CPU_SUSPEND    0xC4000001  (SMC64: power_state, entry, ctx)
 *   CPU_OFF        0x84000002  (no arguments)
 *   CPU_ON         0xC4000003  (SMC64: affinity, entry, ctx)
 *   AFFINITY_INFO  0xC4000004  (SMC64: affinity, lowest level)
 *   SYSTEM_OFF     0x84000008  (no arguments)
 *   SYSTEM_RESET   0x84000009  (no arguments)
 *   PSCI_FEATURES  0x8400000A  (PSCI 1.0 only, gated on version)
 * MIGRATE and its family are NOT offered: they exist for a
 * uniprocessor Trusted OS to move its context, and Kido has
 * no Trusted OS to migrate. The FEATURES probe can still be
 * asked about any ID, including MIGRATE's, and the firmware
 * answers for itself.
 *
 * RETURN CODES (DEN0022, signed, in x0):
 *   0 SUCCESS, -1 NOT_SUPPORTED, -2 INVALID_PARAMETERS,
 *   -3 DENIED, -4 ALREADY_ON, -5 ON_PENDING,
 *   -6 INTERNAL_FAILURE, -7 NOT_PRESENT, -8 DISABLED,
 *   -9 INVALID_ADDRESS.
 * AFFINITY_INFO is the exception: 0 = ON, 1 = OFF,
 * 2 = ON_PENDING are STATES, not errors, and come back
 * through the out-pointer. FEATURES returns a bitfield on
 * success (bit 0 = the queried function is implemented in
 * the SMC64 form, when such a form exists).
 *
 * HONESTY LAW:
 *  - No new header code (N8toriousAi's call, sched-D1 precedent):
 *    NOT_SUPPORTED maps to KIDO_ERR_STUB_REACHED (the
 *    firmware does not implement the function — the exact
 *    meaning of the existing code); every other negative
 *    maps to KIDO_ERR_EARLY_ENV. AFFINITY_INFO states are
 *    not errors at all.
 *  - Version-gated: init() calls PSCI_VERSION and records
 *    it. Below PSCI 0.2 (major 0, minor < 2) init refuses
 *    with EARLY_ENV — a pre-0.2 monitor is not a PSCI
 *    monitor this driver can speak to. PSCI_FEATURES
 *    refuses with STUB_REACHED below PSCI 1.0, by spec
 *    (FEATURES does not exist before 1.0).
 *  - Never-returning calls never pretend to return:
 *    SYSTEM_OFF and SYSTEM_RESET return only on firmware
 *    error. On success the machine stops or resets and
 *    this function does not come back. CPU_OFF likewise
 *    never returns on success (the CPU is off; only a
 *    CPU_ON from another CPU brings it back). The HOSTED
 *    double is the exception by necessity: it records the
 *    call and returns OK, because the host must not halt.
 *    The divergence is stated here, not hidden.
 *  - CPU_SUSPEND's power_state is passed through opaque:
 *    its encoding is platform firmware data (affinity
 *    levels, State-ID, standby/powerdown type bit), and
 *    Kido does not invent a platform's power states.
 *    The caller owns the value; the driver owns the call.
 *  - Affinity values are passed through opaque for the
 *    same reason: the driver does not parse MPIDR. The
 *    caller (DTB/MPIDR reader, future) owns the format.
 *  - WRITTEN, NOT ASSEMBLED, NEVER EXECUTED (toolchain
 *    absent, 15th data point — see the deliberation
 *    record). The bare-metal `smc` strings are text, not
 *    machine code, until the toolchain returns. QEMU
 *    virt is the expected first proof target (it
 *    emulates PSCI for secondary bring-up and for
 *    system off/reset); that proof is queued, not
 *    claimed.
 *  - No bootable kernel is finalized without N8toriousAi;
 *    first boot is his to witness.
 *
 * FUTURES (named, not built): HVC conduit for a hosted-Kido
 * caller; SYSTEM_RESET2 / CPU_FREEZE / SYSTEM_SUSPEND
 * (PSCI 1.1, optional, firmware-gated); SMP bring-up
 * policy on top of CPU_ON (a second CPU's entry stub and
 * stack are a scheduler/Gate item, not this conduit);
 * QEMU virt PSCI proof (VERSION + CPU_ON record +
 * SYSTEM_OFF exit); boot-path gating of init().
 *
 * Draft status: DRAFT (2026-10-27, session 32).
 *
 * TESTING: gcc -std=c11 -Wall -Wextra -Werror -DKIDO_HOSTED_TEST
 *        -DKIDO_PSCI_SELFTEST kido-psci.c -o psci-selftest
 */
#ifndef KIDO_PSCI_H
#define KIDO_PSCI_H

#include "kido-boot.h"

#if !defined(__aarch64__) && !defined(KIDO_HOSTED_TEST)
#error "kido-psci: refusing to compile for unknown arch. PSCI lives in per-arch files; define KIDO_HOSTED_TEST for the hosted draft harness."
#endif

/* PSCI function IDs (DEN0022). SMC64 forms where the call
 * carries a 64-bit argument (entry point, affinity). */
#define KIDO_PSCI_VERSION      0x84000000u
#define KIDO_PSCI_CPU_SUSPEND  0xC4000001u
#define KIDO_PSCI_CPU_OFF      0x84000002u
#define KIDO_PSCI_CPU_ON       0xC4000003u
#define KIDO_PSCI_AFFINITY_INFO 0xC4000004u
#define KIDO_PSCI_SYSTEM_OFF   0x84000008u
#define KIDO_PSCI_SYSTEM_RESET 0x84000009u
#define KIDO_PSCI_FEATURES     0x8400000Au

/* PSCI return codes (signed, DEN0022). */
#define KIDO_PSCI_SUCCESS             0
#define KIDO_PSCI_NOT_SUPPORTED      (-1)
#define KIDO_PSCI_INVALID_PARAMETERS (-2)
#define KIDO_PSCI_DENIED             (-3)
#define KIDO_PSCI_ALREADY_ON         (-4)
#define KIDO_PSCI_ON_PENDING         (-5)
#define KIDO_PSCI_INTERNAL_FAILURE   (-6)
#define KIDO_PSCI_NOT_PRESENT        (-7)
#define KIDO_PSCI_DISABLED            (-8)
#define KIDO_PSCI_INVALID_ADDRESS    (-9)

/* AFFINITY_INFO states (not errors): */
#define KIDO_PSCI_AFFINITY_ON         0u
#define KIDO_PSCI_AFFINITY_OFF        1u
#define KIDO_PSCI_AFFINITY_ON_PENDING 2u

/* Initialize the conduit: call PSCI_VERSION, record it.
 * EARLY_ENV before any version call can succeed, or when
 * the monitor reports below PSCI 0.2. Re-init is allowed
 * and re-probes. No register is touched on a NULL-free
 * path (there are no arguments); the only failure is the
 * version itself. */
kido_status_t kido_psci_init(void);

/* Recorded PSCI version (major<<16 | minor), from init.
 * EARLY_ENV before init or on a NULL out-pointer. */
kido_status_t kido_psci_version(uint32_t *out);

/* FEATURES probe (PSCI 1.0+): bitfield for the queried
 * function ID, through out. STUB_REACHED below PSCI 1.0
 * (the function does not exist there) or when the firmware
 * answers NOT_SUPPORTED for the queried ID. EARLY_ENV
 * before init or on a NULL out-pointer. */
kido_status_t kido_psci_features(uint32_t fid, uint32_t *out);

/* Power up a CPU: affinity (opaque, caller format),
 * entry point (physical address, 64-bit), context ID.
 * ALREADY_ON / ON_PENDING / NOT_PRESENT / INVALID_ADDRESS
 * and every other firmware refusal map to EARLY_ENV (the
 * no-new-codes law); NOT_SUPPORTED maps to STUB_REACHED.
 * EARLY_ENV before init. Success means the target CPU is
 * starting at entry — this call itself returns normally. */
kido_status_t kido_psci_cpu_on(uint64_t affinity, uint64_t entry,
                                uint64_t context_id);

/* Power down the CALLING CPU. Never returns on success:
 * the CPU is off until another CPU issues CPU_ON for it.
 * Returns only on firmware error (mapped as above).
 * EARLY_ENV before init. */
kido_status_t kido_psci_cpu_off(void);

/* Suspend the calling CPU: power_state opaque (platform
 * firmware encoding, caller-owned), entry point resumed
 * on wakeup, context ID. Returns on wakeup with OK, or
 * on firmware error (mapped as above). EARLY_ENV before
 * init. */
kido_status_t kido_psci_cpu_suspend(uint32_t power_state,
                                     uint64_t entry,
                                     uint64_t context_id);

/* Affinity state of a CPU: 0 ON, 1 OFF, 2 ON_PENDING
 * through out. A NOT_PRESENT affinity (no such CPU)
 * maps to EARLY_ENV. EARLY_ENV before init or on a NULL
 * out-pointer. */
kido_status_t kido_psci_affinity_info(uint64_t affinity,
                                       uint32_t lowest_level,
                                       uint32_t *out);

/* Shut the system down. Never returns on success (the
 * machine stops); returns only on firmware error.
 * EARLY_ENV before init. Hosted double records and
 * returns OK (stated divergence — the host must not
 * halt). */
kido_status_t kido_psci_system_off(void);

/* Reset the system. Never returns on success (the
 * machine resets); returns only on firmware error.
 * EARLY_ENV before init. Hosted double records and
 * returns OK (same stated divergence). */
kido_status_t kido_psci_system_reset(void);

#ifdef KIDO_PSCI_SELFTEST
#ifndef KIDO_HOSTED_TEST
#error "KIDO_PSCI_SELFTEST needs KIDO_HOSTED_TEST."
#endif
/* Hosted-double setters (test only, guarded — the PL011
 * lesson: unguarded test helpers break a plain -c build).
 * The double's affinity table is a stand-in (values 0..3),
 * NOT MPIDR format — real MPIDRs come from the caller. */
void kido_psci_test_set_version(uint32_t version);
void kido_psci_test_set_cpu_state(uint64_t affinity, uint32_t state);
void kido_psci_test_get_records(uint32_t *off_called,
                                uint32_t *reset_called,
                                uint32_t *suspend_count);
int kido_psci_selftest_main(void);
#endif /* KIDO_PSCI_SELFTEST */

#endif /* KIDO_PSCI_H */
