/*
 * kido-timer.h — Kido ARM Generic Timer driver, public interface.
 *
 * The EL1 physical timer (CNTP_*): the kernel's own time base and
 * its first real interrupt source. The HAL (session 2) already
 * probes this timer — CNTPCT_EL0/CNTFRQ_EL0 reads — but a probe
 * cannot arm anything. This driver owns arming: CTL/CVAL writes,
 * one-shot compares, and the signaled-state read. It does NOT
 * touch the GIC (the caller enables PPI 30 there) and it does
 * NOT touch the vector table (the caller installs it) — those
 * wirings are Gate items, stated here so nobody claims
 * "timer interrupts work" from this driver alone.
 *
 * REGISTERS (ARM Architecture Reference Manual, generic timer):
 *   CNTFRQ_EL0  — counter frequency, set by firmware, read-only
 *                 here (the module never writes it).
 *   CNTPCT_EL0  — 64-bit physical count, read-only.
 *   CNTP_CTL_EL0 — ENABLE bit 0, IMASK bit 1, ISTATUS bit 2
 *                 (read-only: the timer condition, count >= CVAL).
 *   CNTP_CVAL_EL0 — 64-bit compare value; the timer signals
 *                 when the count reaches it.
 *   CNTP_TVAL_EL0 — 32-bit signed view (CVAL minus count);
 *                 documented, never written (see CVAL-only law).
 * The EL1 physical timer's registers carry the `_EL0` suffix by
 * architecture — there is no CNTP_CTL_EL1 — and they are
 * accessible from EL1, as the HAL already relies on.
 *
 * INTERRUPT IDENTITY: the non-secure EL1 physical timer is PPI
 * 30 (virtual 27, secure physical 29, hypervisor 26). PPI
 * targets and trigger config are architecturally fixed, which
 * is why the GIC driver refuses set_target/set_config for
 * PPIs — the future wiring is GIC enable(30) + register a
 * handler + this driver's arm, nothing more.
 *
 * HONESTY LAW:
 *  - Physical timer only, one-shot only. The generic timer
 *    has no periodic mode; a periodic tick is re-arm in the
 *    caller's handler, not a driver feature.
 *  - CVAL-only arming: arm_ticks writes CVAL = now + ticks.
 *    TVAL is never written (two spellings of one register,
 *    different overflow behavior, and TVAL's 32-bit window
 *    caps a one-shot at ~68 s at 62.5 MHz).
 *  - Frequency is read, never written. CNTFRQ == 0 at init
 *    is KIDO_ERR_NO_TIMER (the existing code, already used
 *    by the HAL adapt path for exactly this meaning).
 *  - Zero and sub-tick arms are refused (EARLY_ENV), never
 *    rounded to "fire immediately": CVAL == now is a race
 *    with the advancing count, not a request.
 *  - Wrap is refused (EARLY_ENV), never wrapped: now + ticks
 *    uses the `sum < now` idiom, and arm_us checks the
 *    multiply before dividing.
 *  - pending() reports the SIGNAL (ENABLE and not IMASK
 *    and condition met), not the raw ISTATUS bit: a masked
 *    or disabled timer never reports pending, even with
 *    the condition met.
 *  - No new header code (N8toriousAi's call, sched-D1 precedent):
 *    NO_TIMER for a missing time base, EARLY_ENV for
 *    everything else.
 *  - ASSEMBLED AND PROVEN ON QEMU 2026-10-27 (session 31):
 *    the PPI-30 delivery proof ran — vec install -> GIC
 *    enable(30) -> arm_us(200000) -> exactly one timer IRQ
 *    taken through the committed vec table -> handler
 *    disarm -> clean eret return (T1:1 in the transcript,
 *    deliberations/2026-10-27-qemu-irq-proof.log). The
 *    hosted double still pins the register image; the
 *    scheduler-tick policy (re-arm in the handler) remains
 *    a Gate item, not something this proof ran.
 *  - No bootable kernel is finalized without N8toriousAi; first
 *    boot is his to witness.
 *
 * FUTURES (named, not built): virtual-timer driver for a
 * hosted-Kido caller; scheduler-tick policy (re-arm in the
 * handler); QEMU PPI-30 delivery proof; SPI delivery proof
 * (UART RX IRQ 33).
 *
 * Draft status: DRAFT (2026-10-26, session 29).
 *
 * TESTING: gcc -std=c11 -Wall -Wextra -Werror -DKIDO_HOSTED_TEST
 *        -DKIDO_TIMER_SELFTEST kido-timer.c -o timer-selftest
 */
#ifndef KIDO_TIMER_H
#define KIDO_TIMER_H

#include "kido-boot.h"

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

/* Interrupt identity: non-secure EL1 physical timer PPI. */
#define KIDO_TIMER_PPI_PHYS 30u

/* Initialize the driver: read CNTFRQ, record it, disarm the
 * timer (CTL = 0 — a safe initial state, no surprise IRQ).
 * Re-init is allowed and re-disarms. Returns NO_TIMER when
 * the firmware left CNTFRQ at 0 (no usable time base).
 * No register is touched when an argument check fails first
 * (there are no arguments; the only failure is NO_TIMER). */
kido_status_t kido_timer_init(void);

/* Frequency in Hz, from CNTFRQ at init time. EARLY_ENV before
 * init or on a NULL out-pointer. */
kido_status_t kido_timer_hz(uint32_t *out);

/* Current count (CNTPCT_EL0). EARLY_ENV before init or on a
 * NULL out-pointer. */
kido_status_t kido_timer_now(uint64_t *out);

/* Arm a one-shot compare ticks in the future: CVAL = now +
 * ticks, CTL ENABLE set, IMASK clear. EARLY_ENV before init,
 * on ticks == 0, or on wrap (now + ticks < now). Re-arm
 * replaces the previous CVAL; the old compare is gone, not
 * queued. */
kido_status_t kido_timer_arm_ticks(uint64_t ticks);

/* Arm a one-shot compare microseconds in the future: ticks =
 * us * hz / 1000000, truncated toward zero. EARLY_ENV before
 * init, on multiply overflow, or when the truncation reaches
 * 0 ticks (a sub-tick request is refused, not rounded). */
kido_status_t kido_timer_arm_us(uint64_t us);

/* Disarm: CTL = 0. The pending signal deasserts with it.
 * EARLY_ENV before init. Idempotent. */
kido_status_t kido_timer_disarm(void);

/* Mask / unmask the IRQ without disarming: IMASK set / clear,
 * CVAL and ENABLE untouched. A masked timer keeps its compare
 * and signals the moment it is unmasked if the count has
 * passed CVAL. EARLY_ENV before init. */
kido_status_t kido_timer_mask(void);
kido_status_t kido_timer_unmask(void);

/* Signaled state: 1 when the timer would signal an interrupt
 * right now (ENABLE and not IMASK and count >= CVAL), else 0.
 * This is the cooperative kernel's poll path. EARLY_ENV before
 * init or on a NULL out-pointer. */
kido_status_t kido_timer_pending(uint8_t *out);

#ifdef KIDO_TIMER_SELFTEST
#ifndef KIDO_HOSTED_TEST
#error "KIDO_TIMER_SELFTEST needs KIDO_HOSTED_TEST."
#endif
/* Hosted-double setters (test only, guarded — the PL011
 * lesson: unguarded test helpers break a plain -c build). */
void kido_timer_test_set_freq(uint32_t hz);
void kido_timer_test_set_count(uint64_t count);
void kido_timer_test_get_regs(uint32_t *ctl, uint64_t *cval);
int kido_timer_selftest_main(void);
#endif /* KIDO_TIMER_SELFTEST */

#endif /* KIDO_TIMER_H */
