# 2026-10-26 — kido-timer design: the ARM Generic Timer driver (builder crew)

**Piece:** the ARM Generic Timer driver (`kido-timer.h` +
`kido-timer.c`). One solid piece: the EL1 physical timer as a
drivable device — read the count, read the frequency, arm a
one-shot compare, poll the signaled state, disarm. It turns the
HAL's timer probe (session 2: CNTPCT/CNTFRQ reads, nothing more)
into a timer the kernel can actually set, and it gives the
session-27/28 interrupt chain (GIC + vector table) its first
real interrupt source: the physical timer's PPI 30.

**Why this piece now:** session 28's remains are all blocked or
fenced. The vec QEMU proof and the SPI delivery proof need the
toolchain (absent a 12th time this session — see Proof posture);
the vec/MM U/HAL wirings are Gate items (untouched); the destroy
bare-metal proof has its own design (session 22, not swallowed
here); D1 KIDO_ERR_NO_TASKS is N8toriousAi's call; the BUBO peer is
Phase 4. The session-22 precedent applies: when the queued proof
cannot run, the session drafts the next module the tree can
actually carry. The timer is that module — every rule comes from
the ARM generic-timer architecture, it is host-testable through
a double like the GIC/PL011/mbox drivers, and it touches zero
existing files (the session-24/25/26 fence pattern).

**Sources verified this session (not from memory alone):**
- ARM Architecture Reference Manual, generic timer register
  summary: CNTFRQ_EL0 (frequency, set by firmware), CNTPCT_EL0
  (64-bit count), CNTP_CTL_EL0 (ENABLE bit 0, IMASK bit 1,
  ISTATUS bit 2 read-only), CNTP_CVAL_EL0 (64-bit compare),
  CNTP_TVAL_EL0 (32-bit signed view: CVAL minus count).
  The EL1 physical timer's registers carry the `_EL0` suffix
  by architecture — there is no CNTP_CTL_EL1 — and the HAL
  already reads CNTPCT_EL0/CNTFRQ_EL0 from EL1 on the same
  basis (session 2).
- ARM GIC architecture PPI assignment: the non-secure EL1
  physical timer is PPI 30 (virtual timer 27, secure
  physical 29, hypervisor timer 26). PPI 30 is the ID the
  future GIC wiring enables and the future vector proof
  delivers; PPI targets and config are architecturally
  fixed, which is why the GIC driver already refuses
  set_target/set_config for PPIs (session 27).
- QEMU virt generic-timer frequency, 62.5 MHz, named in
  writeups of the virt machine — named here as an
  expectation for the future QEMU proof, never asserted
  by the module (C7).

## Positions

- **P1 EL1 physical timer, not virtual:** the driver programs
  CNTP_* (physical). Kido runs at EL1 on bare metal; the
  virtual timer (CNTV_*) is a guest's timer under a
  hypervisor, and Kido is not a guest. The virtual timer
  is a named future for a hosted-Kido caller, not a flag
  on this driver.
- **P2 CVAL-only arming:** arm writes CNTP_CVAL_EL0 =
  now + ticks and sets CTL ENABLE. TVAL is never written:
  a TVAL write is defined as CVAL := count + TVAL, so
  offering both would be two spellings of one register
  with different overflow behavior (TVAL is 32-bit
  signed). One arming path, one truth, auditable.
- **P3 Frequency is read, never written:** init reads
  CNTFRQ_EL0 and records it. The module never writes
  CNTFRQ: the firmware programmed it, and a kernel that
  rewrites its own time base mid-boot would corrupt every
  conversion the HAL already published. A zero frequency
  is not a default — it is KIDO_ERR_NO_TIMER (C5).
- **P4 Poll and IRQ are both real:** `pending()` reports
  the signaled state (ENABLE and not IMASK and condition
  met), which is the cooperative kernel's poll path today;
  the IRQ identity (PPI 30) is declared for the GIC/vec
  wiring tomorrow. Neither path pretends the other exists:
  the driver does not enable the GIC, and the GIC does
  not arm the timer. The seam is the IRQ number.
- **P5 Reuse the existing NO_TIMER code:** kido-boot.h
  already defines KIDO_ERR_NO_TIMER (3), used by the HAL
  adapt path for exactly "no usable timer." Init maps a
  zero frequency to it. Every other failure maps to
  KIDO_ERR_EARLY_ENV (not initialized, NULL out, wrap,
  zero/sub-tick arm) — no new header code is invented,
  per the sched-D1 precedent.
- **P6 Hosted double, guarded test setters:** the hosted
  build runs the same functions against scripted
  registers (frequency, advancing count, CTL, CVAL) with
  the ISTATUS semantics of C6. Test setters live behind
  KIDO_TIMER_SELFTEST (the PL011 lesson: unguarded
  test-only helpers break a plain `-c` build under
  -Werror).

## Challenges

- **C1 — HAL probe vs driver ownership:** the HAL already
  reads CNTPCT/CNTFRQ. Does the driver double-own the
  timer? No: reads are idempotent and ownerless. The HAL
  keeps its probe (the boot adapt path needs timer_hz
  before any driver init); the driver owns ARMING (CTL /
  CVAL writes) and the signaled-state read. Nothing is
  moved, nothing is duplicated as state — the frequency
  is read from the register by both, never cached across
  the seam except inside the driver's own init.
- **C2 — TVAL vs CVAL:** answered by P2. TVAL's 32-bit
  signed window would also cap a one-shot at ~68 seconds
  at 62.5 MHz; CVAL's 64-bit compare has no such cap.
  TVAL stays documented, unwritten.
- **C3 — Zero and sub-tick arms:** `arm_ticks(0)` is
  refused, not rounded: CVAL == now may or may not
  already be met depending on the count's advance, so a
  zero arm is a race, not a request. `arm_us` truncates
  toward zero by integer division, and a truncation to 0
  is refused for the same reason — the caller asked for
  less than one tick, and silently firing immediately
  would be a different request than the one made.
- **C4 — Wrap:** `now + ticks` is checked with the
  `sum < now` idiom (the reloc/mem convention). A wrapped
  CVAL would fire at the wrong epoch; refusal is the
  only honest response, and the count is 64-bit, so a
  real caller never hits it before the heat death of the
  session. `arm_us` checks the multiply the same way
  (`us > UINT64_MAX / hz` refuses) before dividing.
- **C5 — Which code for which failure:** NO_TIMER only
  where it literally means "no usable timer" (CNTFRQ ==
  0 at init). Everything else is EARLY_ENV, including
  "called before init" — the driver has no environment
  yet, which is what EARLY_ENV means in this tree.
- **C6 — What pending() means:** the CTL ISTATUS bit
  reports the timer condition (count >= CVAL); the
  interrupt SIGNAL is condition AND ENABLE AND NOT
  IMASK. `pending()` reports the signal, computed as
  the three-term AND over the CTL bits it reads — so a
  disabled or masked timer never reports pending even
  with the condition met, and the hosted double models
  ISTATUS as the condition and applies the same AND.
  Reading the raw bit alone would report a masked timer
  as pending, which is the wrong answer for both the
  poll path and the future IRQ path.
- **C7 — QEMU frequency:** 62.5 MHz is expected on virt
  but never asserted: the module reads CNTFRQ wherever
  it runs, and the future QEMU proof checks the read
  value against the machine instead of baking it in.
  A Pi4 caller gets whatever its firmware programmed,
  with no constant to mistune.

## Preserved dissent

- **D1 — Drive the virtual timer instead:** overruled
  (P1). Preserved for a hosted-Kido future where EL1
  physical is owned by a hypervisor; on bare metal the
  physical timer is the kernel's own.
- **D2 — Auto-rearming periodic mode in the driver:**
  overruled. The generic timer is one-shot by hardware;
  a periodic tick is a scheduling policy (re-arm in the
  handler), and policy lives in the caller, not in a
  device driver. Preserved for the scheduler-tick module,
  if one is ever named.
- **D3 — Fold the driver into the HAL:** overruled (P4 /
  fence). The HAL is a probe table filled once at boot;
  the driver carries arming state across the kernel's
  life. Folding would also touch a Gate-approved file
  for a module whose own proof cannot run this session.
- **D4 — Write CNTFRQ at init to a known value:**
  overruled (P3). The firmware owns the time base; the
  HAL already published it. Preserved only if a board
  ever ships with CNTFRQ unprogrammed — and then the
  fix is a firmware handoff note, not a silent rewrite.

## Proof posture (honest, stated first)

- **Toolchain absent, 12th data point:** `which` finds no
  `aarch64-linux-gnu-gcc` and no `qemu-system-aarch64`
  this session (sessions 13/17/20/21/23/24/25/26/28
  pattern; session 27's "present" did not survive the VM
  cycle). So the bare-metal asm paths are WRITTEN, NOT
  ASSEMBLED, and the QEMU proof is QUEUED — the
  session-13/17 posture, not hand-waved. The hosted
  self-test below is real and runs the same functions
  against the double.
- **Queued proof gate (toolchain return):** cross-compile
  all TUs clean; assemble the timer's inline asm via a
  scratch harness (mrs/msr strings parse); QEMU virt /
  cortex-a57: install vec -> GIC init -> GIC enable(30)
  -> register a PPI-30 handler -> timer arm (short) ->
  IRQ taken through the committed vector stub -> handler
  marker -> `eret` resumes past the arm -> one IRQ, one
  clean return, zero fault entries. SPI delivery (UART
  RX IRQ 33) stays the proof after that, not this gate.

## Named next

- QEMU proof of the vec module + PPI-30 timer delivery
  through this driver (the gate above) + SPI delivery
  proof (UART RX IRQ 33): the interrupt chain's natural
  proofs, queued on the toolchain.
- Gate items (untouched): wire `kido_vec_install` into
  the boot path; wire GIC enable(30) + timer arm into
  the scheduler tick; HAL wiring (PL011 init, mailbox
  adoption); kido-mmu call-site wiring.
- Destroy bare-metal proof (design ready, session 22);
  real BUBO peer + bare-metal transport (Phase 4);
  D1 KIDO_ERR_NO_TASKS (N8toriousAi's call); PENDING #1
  cross-compile (12th data point: toolchain absent).
- First boot is N8toriousAi's to witness.
