/* SPDX-License-Identifier: LicenseRef-Starship-1.0
 * Copyright (c) 2023-2026 Robert A. James
 */
/* stadium_ops.h -- a v4 node's opcodes as Stadium patrons (#189; plan
 * 2026-11-13-engine-step4-phase1, Task 3).
 *
 * Captain Bob, 2026-11-12: "Add HEAT-OP. If it's a huge performance hit, we'll revert it" -- "Both":
 * the registers (v4/include/v4/node.h) and the Stadium feed; 2026-11-13: "Per heartbeat tick".
 * docs/v4.0.0/V3-PARITY.md 1c's reading -- "a VM's word patrons become its 32 opcode patrons" -- held
 * since 1h left the opcodes unwired "for now"; this wires them, beside the word patrons, not instead.
 *
 * A node's 32 opcodes are patrons of its quota, behaviour COOL, each made resident on its first
 * retirement as a word is on its first dispatch (stadium_words.c). At a charge, an opcode's
 * retirements since the last charge are charged as that many of the word layer's dispatches -- the
 * same quantum (STADIUM_WORD_HEAT_QUANTUM), the same floor left in the reservoir (a third); when
 * they want more than there is, what there is is shared in proportion to the retirements, not taken
 * by whichever opcode is charged first -- and a resident one first cools by the ticks since, as a
 * word does
 * (STADIUM_WORD_COOL_RATE_Q48). The kernel charges at its heartbeat's service points (sk_v4.c):
 * where the node's host waits, and after each line. Conservation is the Stadium's: what is pulled is
 * the node's own share.
 */
#ifndef STARKERNEL_VM_STADIUM_OPS_H
#define STARKERNEL_VM_STADIUM_OPS_H

#ifdef __STARKERNEL__

#include <stdint.h>
#include "starkernel/vm_uuid.h"

#define STADIUM_OPS_COUNT 32u                          /* the F18 opcodes, 0 .. 31 */
#define STADIUM_OPS_IDENTITY 0x4F50000000000000ULL     /* "OP" in a patron's identity, | the opcode */

/* The per-quota tables; after stadium_boot_init_for(). Not re-entrant. */
void stadium_ops_init(void);

/* Charge the node `vm_id`'s opcodes: `counts` are its 32 running retirement counts (v4_heat.op),
 * `tick` the heartbeat's count now. Nothing for a key with no quota. */
void stadium_ops_charge(VMUuid vm_id, const uint64_t counts[STADIUM_OPS_COUNT], uint64_t tick);

/* A node is gone: its opcode counts are forgotten, so a node that later has its quota's slot starts
 * from none (#189). Before stadium_return_quota(), while the key still has its slot. */
void stadium_ops_forget(VMUuid vm_id);

/* An opcode patron's heat now (Q48.16), or 0: not resident, or no quota. */
uint64_t stadium_ops_heat(VMUuid vm_id, unsigned op);

/* "Stadium opcodes: N resident, hottest opcode K" -- one line, at most 63 characters. */
void stadium_ops_print_boot_diagnostics(VMUuid vm_id);

#endif /* __STARKERNEL__ */
#endif