/*
 * rng.h — Unified entropy entry point for StarKernel
 *
 * The single place any kernel consumer (keygen, identity mint, drive_uuid,
 * certificate serials, ...) asks for entropy. All entropy flows through
 * rng_get_bytes() and never touches a backend directly.
 *
 * The set of active backends is determined at rng_init() time by probing,
 * in order, until one (or more) come up:
 *   - v2.0.0 (QEMU): virtio-rng is the sole backend — there is no virtio-rng
 *     on real hardware, but QEMU exposes it uniformly on all three arches
 *     (amd64/aarch64/riscv64), and the paravirtualized device sidesteps the
 *     per-ISA gap where no single CPU RNG covers all three models (amd64 has
 *     RDRAND, riscv64 has Zkr, but QEMU's aarch64 CPU models expose neither —
 *     see virtio_rng.h / vm_uuid.h for the identical finding).
 *   - v2.5.0 (real hardware): real per-arch backends are inserted here without
 *     touching the call path — amd64 RDRAND, riscv64 Zkr (RNDR), aarch64
 *     peripheral RNG — each handled by a case in rng_init() and rng_get_bytes()
 *     (grid §G.4). On QEMU all three arches stay on virtio-rng; nothing changes.
 *
 * Probe-and-refuse-loudly contract (§G.2): if no backend comes up at
 * rng_init(), the kernel prints a loud boot-time message. A later
 * rng_get_bytes() call with no backend returns -1 (RNG_ERR_NO_BACKEND) rather
 * than ever silently degrading to a deterministic throwaway — the exact failure
 * Phases A/G call out as unacceptable. Callers (e.g. capsule_mint_identity)
 * must surface that refusal as an explicit no-entropy error, never proceed with
 * a deterministic seed.
 *
 * Important ordering: rng_init() must run before any rng_get_bytes()/mint call
 * (it already does in kernel_main phase 8, ahead of Zuse boot attach, which is
 * the only mint path in v2.0.0). rng_get_bytes() with rng_init() never
 * successful returns RNG_ERR_NO_BACKEND, never blocks.
 */

#ifndef STARKERNEL_RNG_H
#define STARKERNEL_RNG_H

#include <stddef.h>
#include <stdint.h>

/* Return codes (negative = failure). */
#define RNG_ERR_NO_BACKEND (-1) /* rng_init() found no working entropy source */

/*
 * rng_init — probe and bring up the entropy backends. Returns 0 if at least
 * one backend is active (rng_get_bytes() will succeed), nonzero otherwise.
 * Prints a loud boot-time message when no backend comes up. Call once, early.
 */
int rng_init(void);

/*
 * rng_ready — 1 if at least one backend is active, 0 otherwise.
 */
int rng_ready(void);

/*
 * rng_get_bytes — fill buf with n bytes of real entropy, blocking until all
 * n bytes are obtained.
 *
 * Returns  0 on success (buf fully filled).
 * Returns RNG_ERR_NO_BACKEND (-1) if no backend is active.
 */
int rng_get_bytes(uint8_t *buf, size_t n);

#endif /* STARKERNEL_RNG_H */