/*
 * kido-mpidr.h — Kido CPU-identity leaf: MPIDR_EL1 decode.
 *
 * Session 33 brought secondary CPUs up (kido-smp), 34 gave
 * them a lock (kido-sync), 35 gave them a rendezvous
 * (kido-barrier), 36 gave them a signal (kido-ipi), 37 gave
 * them a work carrier (kido-call). Three of those modules
 * refused, in writing, to parse MPIDR: smp keeps affinities
 * opaque, ipi C3 refused to parse it for the source CPU,
 * call C8 refused to parse it for the poster. Each refusal
 * was right — none of those jobs needed a decoder — and
 * each named the parse as a future. This leaf is that
 * future: a decoder any Gate consumer can call, instead of
 * a parse invented inside a proven file.
 *
 * FIELD LAW (Arm A-profile register reference, MPIDR_EL1):
 *   Aff0 bits [7:0], Aff1 [15:8], Aff2 [23:16], MT bit [24],
 *   RES0 [29:25], U bit [30], RES1 bit [31], Aff3 [39:32],
 *   RES0 [63:40]. Read-only at EL1 and above. The Aff tuple
 *   (Aff3, Aff2, Aff1, Aff0) must be unique within the
 *   system. MT=1: PEs with different Aff0 and equal higher
 *   levels are very interdependent (a multithreading hint,
 *   not proof multithreading is implemented). U=1: a
 *   uniprocessor system, as distinct from PE 0 of a
 *   multiprocessor system. In a uniprocessor system Arm
 *   recommends all Aff fields read 0 — a recommendation,
 *   not a law this decoder enforces.
 *
 * NO LINEAR INDEX (deliberation C2 — the decision this
 * module turns on): the Aff tuple is hierarchical; its
 * only architectural guarantee is uniqueness of the whole
 * tuple. There is deliberately no kido_mpidr_index().
 * QEMU virt -smp N happens to report Aff0 = the CPU
 * number, and that platform accident is exactly why the
 * refusal matters: on a multi-cluster system Aff0 repeats
 * across clusters, and Aff0-as-index would alias two PEs
 * into one slot. The smp slot is assigned by bring_up and
 * recorded in the smp table; slot-from-affinity is a table
 * lookup, a Gate policy, never arithmetic in this leaf.
 *
 * SAME-CPU LAW (deliberation C3): same_cpu() compares
 * Aff3..Aff0 only. MT and U are not identity: MT is a
 * performance hint about Aff0 siblings, U describes the
 * system shape, neither changes which PE a tuple names.
 * No "same cluster" or "same package" helper is offered:
 * what Aff2/Aff1 mean physically is IMPLEMENTATION
 * DEFINED, and naming a grouping the architecture does
 * not define would be the C2 invention one level up.
 *
 * RESERVED-BIT LAW (deliberation C4): the decoder masks
 * only the defined fields. Bit 31 is RES1, so real
 * hardware always returns it set; bits [63:40] and
 * [29:25] are RES0. No function interprets a reserved
 * bit, and no function refuses a value for having one
 * set or clear. The raw value is carried whole in the
 * struct so a future reader sees exactly what the
 * register returned.
 *
 * EL LAW (deliberation C5): call only at EL1 or above.
 * MPIDR_EL1 from EL0 is UNDEFINED/trapping; the entry
 * shim guarantees EL1 before any C runs. Stated, not
 * enforced — there is no cheap EL query that is not
 * itself another register read with the same problem.
 *
 * HONESTY LAW:
 *  - No new header code (sched-D1 precedent): NULL guards
 *    refuse EARLY_ENV; any 64-bit input decodes (the
 *    fields are bit slices, and no firmware value makes
 *    slicing undefined).
 *  - Zero existing files touched. kido-sync keeps its raw
 *    MPIDR owner (deliberation D2); this leaf does not
 *    replace it. No wiring into smp, sync, ipi, call, or
 *    the boot path — consumers are Gate items.
 *  - WRITTEN, NOT ASSEMBLED, NEVER EXECUTED on bare metal
 *    (toolchain absent, 21st data point). The ARM64 read
 *    is one MRS in sync's already-carried spelling; what
 *    awaits a tooled VM is the disassembly check that the
 *    MRS is present, plus a QEMU virt -smp 2 run showing
 *    two distinct Aff tuples. The hosted proof pins the
 *    decode, not delivery across silicon.
 *  - No bootable kernel is finalized without N8toriousAi;
 *    first boot is his to witness.
 *
 * FUTURES (named, not built): Gate consumers — a scheduler
 * that places work by affinity, a CALL handler that knows
 * its own slot, a Gate wiring binding a CPU to its
 * mailbox; a QEMU virt -smp 2 Aff-tuple proof.
 *
 * Draft status: DRAFT (2026-10-30, session 38).
 *
 * TESTING: gcc -std=c11 -Wall -Wextra -Werror -DKIDO_HOSTED_TEST
 *        -DKIDO_MPIDR_SELFTEST kido-mpidr.c -o mpidr-selftest
 */
#ifndef KIDO_MPIDR_H
#define KIDO_MPIDR_H

#include "kido-boot.h"

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

#include <stdint.h>

/* Decoded MPIDR_EL1. raw is carried whole (reserved-bit law);
 * the fields are the masked defined slices. mt/u are 0/1. */
typedef struct kido_mpidr {
    uint64_t raw;
    uint8_t  aff0;
    uint8_t  aff1;
    uint8_t  aff2;
    uint8_t  aff3;
    uint32_t mt;
    uint32_t u;
} kido_mpidr_t;

/* Read this PE's MPIDR_EL1 and decode it. ARM64: one MRS.
 * Hosted: the injector's value (default 0, the sync
 * precedent). NULL out refuses EARLY_ENV. Never fails
 * otherwise: a register read cannot fail at EL1. */
kido_status_t kido_mpidr_read(kido_mpidr_t *out);

/* Pure decode of any raw value — including a recorded
 * affinity from the smp table, which is how a future
 * consumer answers "which PE was that?" about another
 * CPU without reading its own register. read() calls
 * this on the value it obtained, so the two paths can
 * never drift. NULL out refuses EARLY_ENV. */
kido_status_t kido_mpidr_decode(uint64_t raw, kido_mpidr_t *out);

/* Identity: all four Aff levels equal. MT and U are not
 * identity (same-CPU law). NULL inputs refuse EARLY_ENV;
 * *same is untouched on refusal. */
kido_status_t kido_mpidr_same_cpu(const kido_mpidr_t *a,
                                   const kido_mpidr_t *b,
                                   uint32_t *same);

#ifdef KIDO_HOSTED_TEST
/* Hosted-only injector (the sync precedent): the value
 * read() returns on the host, where no MPIDR_EL1 exists.
 * Never refuses; the register value is input, not a
 * claim to validate (reserved-bit law). */
kido_status_t kido_mpidr_test_set_raw(uint64_t raw);
#endif /* KIDO_HOSTED_TEST */

#ifdef KIDO_MPIDR_SELFTEST
#ifndef KIDO_HOSTED_TEST
#error "KIDO_MPIDR_SELFTEST needs KIDO_HOSTED_TEST."
#endif
int kido_mpidr_selftest_main(void);
#endif /* KIDO_MPIDR_SELFTEST */

#endif /* KIDO_MPIDR_H */
