Files
LithosAnanke/kernel/include/starkernel/timer.h
T
Claude 00be537503 feat(v4, kernel): ONE adaptive heartbeat -- it paces itself on the Stadium's resident heat; every VM ticks on it, in lockstep
Captain Bob, 2026-11-17: "The adaptive heartbeat is its own thing ... It has its own independent RWOT and slope
provider. Only one output from the entire stadium is used as a load measurement for heart rate pacing. ... ONE
AS IN THE NUMBER 1 heartbeat (the adaptive one) runs the entire system." Ruled one at a time: the kernel's
heartbeat; resident heat its one input; held in POST; the Stadium charged as before today
(docs/v4.0.0/plans/2026-11-17-one-adaptive-heartbeat.md, its first version kept as superseded).

- kernel/src/heartbeat.c, timer.h: heartbeat_pace_from(load) -- its own window of samples, its own slope
  provider (v4's inference arithmetic) every HEARTBEAT_PACE_EVERY samples, Loop #7 setting its own period
  (not stable 20% faster, stable 25% slower, 1/4..4x the 10 ms base). No source (v3's path): nothing runs.
- kernel/src/vm/stadium.c: stadium_resident_heat_total(), read only -- the one output it paces by.
- v4/system/mesh.c, mesh.h: the owner's clock read at every fabric step; each tick delivered, one by one, to
  every node present -- its heartbeat cycle run, active, idle or blocked alike. The tick by execution, the
  nodes' own Loop #7 and the heartrate callback are gone.
- kernel/src/v4/sk_v4.c: the clock gives the heartbeat's bottom half its turn; 0 until POST has ended.
- Tests first, each seen to fail (does not build): kernel/tests/test_heartbeat.c (11 checks),
  test_stadium_node.c (16), test_mesh_boot.c's lockstep checks. Seven Phase 7 checks that assumed the tick by
  execution now drive the test's heartbeat (ruled). POST 990/990 with v3's heat cases as written;
  mesh-boot 103, -on 112, -noop 100, san-mesh-boot 103, every v4 program at both widths, every kernel host
  test: 0 failures. The full `sanitize` target not run (it outlasts the foreground limit).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017RzZgrf7V7Zk2iczBXDRbm
2026-11-17 20:55:14 +00:00

243 lines
9.7 KiB
C
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/*
StarForth — Steady-State Virtual Machine Runtime
Copyright (c) 2023–2025 Robert A. James
All rights reserved.
This file is part of the StarForth project.
Licensed under the Starship License, Version 1.0 (SL-1.0) (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at:
https://github.com/star.4th@proton.me/StarForth/LICENSE.txt
This software is provided "AS IS", WITHOUT WARRANTY OF ANY KIND,
express or implied, including but not limited to the warranties of
merchantability, fitness for a particular purpose, and noninfringement.
See the License for the specific language governing permissions and
limitations under the License.
StarForth — Steady-State Virtual Machine Runtime
Copyright (c) 2023–2025 Robert A. James
All rights reserved.
This file is part of the StarForth project.
Licensed under the Starship License, Version 1.0 (SL-1.0) (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at:
https://github.com/star.4th@proton.me/StarForth/LICENSE.txt
This software is provided "AS IS", WITHOUT WARRANTY OF ANY KIND,
express or implied, including but not limited to the warranties of
merchantability, fitness for a particular purpose, and noninfringement.
See the License for the specific language governing permissions and
limitations under the License.
*/
/**
* timer.h - Timer and Heartbeat Interface
*
* M5 Time Model:
* - TIME-TICKS (Q64.0): Monotonic heartbeat counter, never decreases
* - TIME-TRUST (Q48.16): Continuous confidence metric [0.0, 1.0]
* - No discrete modes (NONE/REL/ABS are legacy, being phased out)
* - Trust is a measurement, never gates execution
*/
#ifndef STARKERNEL_TIMER_H
#define STARKERNEL_TIMER_H
#include <stdint.h>
#include "uefi.h"
#include "q48_16.h"
/* ============================================================================
* M5 Time Model (New)
* ============================================================================ */
/* TIME-TRUST: Continuous confidence metric in Q48.16 format */
typedef q48_16_t time_trust_t;
/* Rolling window size for timestamp variance computation */
#define TIME_WINDOW_SIZE 64
/* TIME-TRUST thresholds in Q48.16 (for diagnostics, NOT for gating) */
#define TIME_TRUST_HIGH Q48_ONE /* 1.0 = full confidence */
#define TIME_TRUST_LOW (Q48_ONE >> 2) /* 0.25 = low confidence */
/*
* Rolling window of timestamp deltas for variance computation.
* Each entry is (actual_tsc_delta - expected_tsc_delta) in TSC ticks.
*/
typedef struct time_window {
int64_t deltas[TIME_WINDOW_SIZE]; /* Signed: can be early or late */
uint32_t pos; /* Current write position */
uint32_t count; /* Number of valid samples (up to SIZE) */
} TimeWindow;
/*
* M5 Heartbeat State: Holds all time-related metrics.
* Updated every heartbeat tick by the ISR.
*/
typedef struct time_trust_state {
/* Core counters */
volatile uint64_t ticks; /* TIME-TICKS: monotonic heartbeat count --
* written directly in ISR context
* (heartbeat_tick(), all three archs) and
* read directly by mainline
* (heartbeat_ticks()); genuinely
* concurrent, unlike every other field in
* this struct (FABRIC-0.md item 4.5a/4.5b,
* 2026-08-11). */
uint64_t last_tsc; /* TSC at last heartbeat */
uint64_t expected_delta; /* Expected TSC ticks per heartbeat */
/* Rolling window for variance */
TimeWindow window;
/* Derived metrics (Q48.16) */
q48_16_t variance; /* Variance of deltas */
q48_16_t trust; /* TIME-TRUST: derived from variance */
/* Statistics */
uint64_t total_samples; /* Lifetime sample count */
} TimeTrustState;
/* ============================================================================
* Legacy M4 Interface (To Be Phased Out)
* ============================================================================ */
/*
* Timer trust levels (LEGACY - discrete modes violate M5 spec):
* - NONE: no usable time base
* - RELATIVE: monotonic-ish, not for claims
* - ABSOLUTE: invariant + calibrated
*/
typedef enum timer_trust_level {
TIMER_TRUST_NONE = 0,
TIMER_TRUST_RELATIVE = 1,
TIMER_TRUST_ABSOLUTE = 2
} timer_trust_level_t;
/*
* Timer calibration record for logging / DoE traceability.
* Keep it minimal and serial-friendly.
*/
typedef struct timer_calibration_record {
uint64_t hpet_hz; /* HPET frequency derived from period_fs (if available) */
uint64_t tsc_hz_mean; /* Locked TSC Hz (final) */
uint64_t pit_hz_mean; /* PIT-based estimate (if used) */
uint64_t cv_hpet_ppm; /* HPET window CV in ppm (bare metal convergence) */
uint64_t cv_pit_ppm; /* PIT window CV in ppm (bare metal convergence) */
uint64_t diff_ppm; /* HPET vs PIT mean diff in ppm (bare metal convergence) */
uint32_t windows_used; /* number of windows consumed to converge */
uint8_t converged; /* 1 if converged/locked, 0 otherwise */
uint8_t vm_mode; /* 1 if hypervisor policy path used */
uint8_t trust; /* timer_trust_level_t (NONE/RELATIVE/ABSOLUTE) */
uint8_t reserved[1];
} timer_calibration_record_t;
/* Legacy API (still works, wraps M5 internals) */
int timer_init(BootInfo *boot_info);
uint64_t timer_tsc_hz(void);
uint64_t timer_now_ns(void);
int timer_check_drift_now(void);
const timer_calibration_record_t *timer_calibration_record(void);
/* ============================================================================
* M5 Heartbeat API (New)
* ============================================================================ */
/*
* Initialize the heartbeat subsystem.
* Called after timer_init(), before enabling APIC timer.
*/
void heartbeat_init(uint64_t tsc_hz, uint64_t tick_hz);
/**
* Top half. Called directly from each architecture's ISR (punch-list item
* 0.8) -- one call site per architecture, unchanged from before this item.
* Does exactly three things: reads the raw counter via
* @c heartbeat_read_counter(), increments TIME-TICKS, and latches the
* sample for @c heartbeat_service() to pick up. No window math, no
* variance, no loops -- this must stay cheap enough for interrupt context.
*/
void heartbeat_tick(void);
/**
* Bottom half (punch-list item 0.8). Services one pending sample if
* @c heartbeat_tick() has latched one since the last call: computes the
* inter-tick deviation, updates the rolling window, and (architecture
* permitting -- see @c heartbeat.c) recomputes variance and TIME-TRUST.
* Never runs in interrupt context. Call from the mainline, as frequently
* as convenient -- a stale/skipped service call degrades the window's
* fidelity but affects nothing else, since TIME-TRUST is diagnostic only
* and never gates execution.
*/
void heartbeat_service(void);
/**
* Read the raw hardware counter this architecture's heartbeat is paced
* against -- the same clock @c timer_now_ns() and calibration already use
* internally (rdtsc on amd64, the `time` CSR on riscv64, CNTPCT_EL0 on
* aarch64), not a separate/different source. Implemented once per
* architecture in that architecture's timer.c; consumed only by
* @c heartbeat_tick() in the shared heartbeat.c.
*/
uint64_t heartbeat_read_counter(void);
/* ---- The one adaptive heartbeat paces itself (StarForth v4; Captain Bob, 2026-11-17: "It has its own independent
* RWOT and slope provider. Only one output from the entire stadium is used as a load measurement for heart rate
* pacing"; docs/v4.0.0/plans/2026-11-17-one-adaptive-heartbeat.md). Given a load source -- the Stadium's resident
* heat, on v4 -- every serviced tick samples it into the heartbeat's own rolling window; every
* HEARTBEAT_PACE_EVERY samples its own slope provider (v4's inference arithmetic) runs on that window, and Loop
* #7's rule sets the period: not stable, 20% faster; stable, 25% slower; within a quarter to four times the base.
* The source is only read. With none (v3's path) nothing of this runs and the period is left to its setter. */
#ifndef HEARTBEAT_PACE_EVERY
#define HEARTBEAT_PACE_EVERY 1000u /* samples between runs: Kconfig.heartbeat's inference frequency */
#endif
#define HEARTBEAT_PACE_WINDOW 1024u /* the heartbeat's own rolling window, in samples */
typedef uint64_t (*heartbeat_load_fn)(void);
void heartbeat_pace_from(heartbeat_load_fn load); /* 0: no source, no pacing */
uint64_t heartbeat_pace_samples(void);
uint64_t heartbeat_pace_runs(void);
/**
* Get current TIME-TICKS (monotonic heartbeat count).
*/
uint64_t heartbeat_ticks(void);
/**
* Get current TIME-TRUST (Q48.16 confidence metric).
*/
time_trust_t heartbeat_trust(void);
/**
* Get pointer to full heartbeat state (for diagnostics).
*/
const TimeTrustState *heartbeat_state(void);
/**
* Set the adaptive re-arm period, in nanoseconds (punch-list item 0.8,
* FABRIC-0.md §26). Called from the mainline execution path only (Loop #7's
* site in vm_runtime.c) -- never from interrupt context. Clamped to
* [1/4x, 4x] of the kernel's base period internally; a caller need not
* pre-clamp.
*/
void heartbeat_set_adaptive_period_ns(uint64_t ns);
/**
* Read the period the next hardware re-arm should use. Called from
* interrupt context by each architecture's re-arm function in place of a
* fixed constant.
*/
uint64_t heartbeat_next_period_ns(void);
#endif /* STARKERNEL_TIMER_H */