169 lines
10 KiB
TeX
169 lines
10 KiB
TeX
%% SCRAP: architecture/PHYSICS_SIGNAL_MAP
|
|
%% SOURCE: docs/working/architecture/PHYSICS_SIGNAL_MAP.adoc
|
|
%% STATUS: WORKING
|
|
%% FITS: dev-guide/app-physics, cookbook/app-physics
|
|
%% EDITORIAL: lifted — prose rewritten to press voice
|
|
|
|
\section{Physics Signal Inventory}
|
|
|
|
This inventory enumerates the telemetry the physics-driven scheduler can sense
|
|
today, drawn from two sources: the L4Re microkernel (through the StarshipOS loader
|
|
stack) and the in-process StarForth VM. It defines the input stage of the
|
|
scheduler. The guiding metaphor is an operational amplifier: the positive input
|
|
ties to real host signals, the negative input ties to VM-internal counters, and a
|
|
Bayesian inference loop stabilizes the gain. The metaphor is a modeling device for
|
|
the control architecture, not a literal circuit.
|
|
|
|
\subsection{L4Re and Microkernel Signals}
|
|
|
|
\paragraph{Kernel Interface Page (KIP).} The KIP exposes a high-resolution monotonic
|
|
clock (\texttt{l4\_kip\_clock\_ns()}) for timing when no RTC is present, a kernel
|
|
build fingerprint for correlating inference data with kernel revisions, the
|
|
scheduling granularity (an upper bound on how fine-grained the physics scheduler can
|
|
react), physical memory descriptors (how much RAM can be earmarked for in-RAM
|
|
inference buffers), and platform/SMP information. SMP availability doubles as a noise
|
|
hook: work can be scheduled on sibling cores to inject controlled jitter and keep the
|
|
model honest.
|
|
|
|
\paragraph{Scheduler object.} \texttt{l4\_scheduler\_info()} reports the online CPU
|
|
bitmap and maximum CPU count, bounding how many physics loops run in parallel.
|
|
\texttt{l4\_sched\_param\_t} (priority and quantum) records the loader's configured
|
|
timeslice as a prior per VM. The scheduler-class flags reveal whether fixed-priority
|
|
or weighted-fair-queue scheduling is active, which shapes how aggressively words may
|
|
be heated or cooled. \texttt{l4\_sched\_cpu\_set()} pins the main or physics worker
|
|
thread to a core subset during experiments.
|
|
|
|
\paragraph{Loader and environment capabilities.} The loader script
|
|
(\texttt{quark.lua}) wires named capabilities the runtime can tap: \texttt{vbus\_storage}
|
|
for block-device enumeration and driver statistics (queue depth, error counts);
|
|
\texttt{ahci\_chan} for completion-interrupt rates and per-port error registers;
|
|
\texttt{rtc\_ns} for wall-clock sync; \texttt{cons\_mux} for console input cadence as
|
|
a proxy for interactive heat; \texttt{L4.Env.log} for scheduler and hardware warnings
|
|
that should bias temperature decay; and \texttt{L4.Env.vesa} for framebuffer
|
|
refresh/blit latency.
|
|
|
|
\paragraph{Further kernel APIs.} \texttt{l4\_thread\_control()} and
|
|
\texttt{l4\_thread\_ex\_regs()} expose per-thread UTCB pointers and instruction
|
|
pointers for correlating VM stalls with kernel scheduling; \texttt{l4\_ipc\_error()}
|
|
surfaces IPC failure codes that could feed entropy penalties for fault-prone words;
|
|
and virtual IRQ devices can be counted to derive environmental noise injected into the
|
|
VM.
|
|
|
|
\subsection{StarForth VM Signals}
|
|
|
|
\paragraph{Core runtime state.} \texttt{DictEntry.entropy} is the per-word execution
|
|
counter, the baseline for macro temperature. \texttt{DictEntry.physics} holds the
|
|
tunable knobs (temperature, last-active timestamp, mass). The data and return stack
|
|
pointers (\texttt{VM.dsp}, \texttt{VM.rsp}) report stack depth, whose steep excursions
|
|
imply turbulent execution and feed variance estimates. Mode and state fields reveal
|
|
interpret-versus-compile state and the currently executing word. The \texttt{error}
|
|
and \texttt{halted} flags are binary fault signals that spike entropy decay when they
|
|
flip. Log volume and severity mix are themselves telemetry: heavy warnings can cool
|
|
risky words.
|
|
|
|
\paragraph{Profiler and instrumentation.} \texttt{WordProfile} supplies per-word total
|
|
time, call count, and min/avg/max latency --- a direct feed for \texttt{avg\_latency\_ns}
|
|
and Bayesian likelihoods. \texttt{MemoryProfile} supplies read/write counts and bytes
|
|
as a mass-energy proxy for memory-thrashing words. The profiler counters (VM cycles,
|
|
dictionary lookups, stack ops, allocations) seed default temperatures and heat
|
|
capacities. \texttt{profiler\_word\_count()} stays available even without detailed
|
|
profiling, and \texttt{vm\_debug\_dump\_state()} provides a structured post-mortem the
|
|
Bayesian tool can parse to reset priors after a crash.
|
|
|
|
\paragraph{Block and storage subsystem.} Block-subsystem globals report working-set
|
|
size, dirty-block counts, and block-allocation-map churn. \texttt{blkio\_info()}
|
|
exposes device geometry and the read-only bit, informing whether a cooling word should
|
|
migrate to RAM or disk tiers. \texttt{blkio\_read}/\texttt{write} return codes give
|
|
immediate error feedback. Cache slots track hit/miss rate and write-back frequency to
|
|
infer subsystem momentum.
|
|
|
|
\subsection{Op-Amp Signal Flow}
|
|
|
|
The signal flow follows the amplifier metaphor in five stages:
|
|
|
|
\begin{enumerate}
|
|
\item \textbf{Positive input (microkernel)} --- real-world noise: CPU availability,
|
|
I/O latency, RTC drift, IRQ storms.
|
|
\item \textbf{Negative input (VM)} --- internal state: entropy, latency, stack
|
|
tension, storage dirty set.
|
|
\item \textbf{Amplifier} --- the Bayesian inference loop adjusts priors and updates
|
|
word physics.
|
|
\item \textbf{Output} --- updated \texttt{DictPhysics} structs and scheduler hints
|
|
that modulate execution order and block placement.
|
|
\item \textbf{Feedback} --- the observation window width is adjusted by variance (a
|
|
gauge study) and the cycle repeats.
|
|
\end{enumerate}
|
|
|
|
\subsection{Messaging and IPC Considerations}
|
|
|
|
The pub/sub backbone is shared-memory-first: a ring buffer with sequence counters
|
|
inside a dedicated analytics heap (10~MiB by default). Producers write events, flip a
|
|
counter, and continue, with no blocking semantics inside the VM. On L4Re, where IPC is
|
|
synchronous, IPC serves only as a notification channel --- a publisher pokes a
|
|
notification thread that drains the ring and forwards to subscribers; virtual IRQs
|
|
offer an alternative non-blocking wakeup. On Linux the same API is backed by condition
|
|
variables or eventfd behind a common shim, keeping the VM path identical across
|
|
platforms. All state stays resident in a fixed-size analytics heap with no dynamic
|
|
expansion. That heap is separate from the 5~MiB VM arena (\texttt{VM\_MEMORY\_SIZE}),
|
|
so the dictionary, stacks, and block-subsystem budgets remain untouched.
|
|
|
|
\subsection{Host Snapshot Shim and Analytics Heap}
|
|
|
|
Phase~1 ships a concrete implementation. \texttt{physics\_runtime\_init()} reserves the
|
|
analytics heap (10~MiB default) whose layout the HOLA contract documents, publishing
|
|
the header and region descriptors HOLA consumes. \texttt{physics\_host\_snapshot()}
|
|
abstracts POSIX and L4Re scheduler probes and feeds ring-buffer events on channel
|
|
\texttt{0x00000002} via \texttt{physics\_analytics\_publish\_event()}. The heap header,
|
|
event records, and mailbox schema live in \texttt{include/physics\_runtime.h}; the
|
|
runtime lives in \texttt{src/physics\_runtime.c}. The interface is deliberately
|
|
ABI-stable so governance tooling can mirror it without pulling in C sources. On the
|
|
POSIX path, Phase~1 additionally captures Linux PSI values mapped into
|
|
\texttt{psi\_*\_avg\{10,60,300\}\_milli}, \texttt{/proc/stat} total and idle jiffies,
|
|
and cgroup~v2 CPU and memory usage where available; flag bits advertise which sources
|
|
were populated.
|
|
|
|
\subsection{Conventions and Constraints}
|
|
|
|
Several conventions govern the inference loop. The observation window combines a
|
|
time-based heartbeat with event-count triggers: events act as ``excitement'' that
|
|
boosts entropy, while publish and decay operations cool at roughly half that rate
|
|
(tunable). All computation uses 64-bit fixed-point integers. Physics snapshots can
|
|
optionally be persisted into FORTH block storage and reloaded during \texttt{(INIT)}
|
|
to simulate a warm boot or replay a training sequence. Descriptor inheritance flows
|
|
from module, vocabulary, and VM defaults down to individual words, so sensible priors
|
|
seed at multiple levels; every tier exposes the same attribute schema --- temperature,
|
|
latency, mass, state flags, ACL hints, pub/sub mask, and pinned flag. VM-level rollups
|
|
mirror per-word metrics and define operating bands (\texttt{COLD}, \texttt{WARM},
|
|
\texttt{HOT}, \texttt{CRITICAL}) that governance and the scheduler shim can respond to.
|
|
Isabelle captures the formal state machine, invariants, and IPC-handshake proofs;
|
|
HOLA defines the shared-memory layout and control protocol consumed by both the VM
|
|
and external analyzers.
|
|
|
|
A primitive seed table (\texttt{physics\_metadata\_apply\_seed()}) installs initial
|
|
priors for high-impact primitives --- control flow, I/O, block subsystem, save-system
|
|
--- so temperature and latency estimates do not start at absolute zero; governance
|
|
tooling can extend or override the table once the Bayesian loop is in place.
|
|
|
|
\subsection{Immediate Research Tasks}
|
|
|
|
\begin{enumerate}
|
|
\item Prototype a thin KIP/scheduler shim exposing the listed signals to userland C
|
|
with no filesystem: on L4Re via \texttt{l4re\_kip()}, on POSIX via a stub that
|
|
feeds monotonic time and scheduler defaults.
|
|
\item Inventory the IO-server (vbus) protocol to pull queue-depth and error counters
|
|
for AHCI, NVMe, and virtio backends.
|
|
\item Define the shared-memory layout between the VM and the Bayesian analyzer,
|
|
defaulting to a 10~MiB heap (header, $\sim$6~MiB event ring, $\sim$3~MiB
|
|
summary/scratch, padding), honoring the platform split between POSIX and L4Re
|
|
messaging.
|
|
\item Extend the profiler to snapshot \texttt{MemoryProfile} deltas without enabling
|
|
full verbose mode, keeping overhead low.
|
|
\item Derive initial priors for key primitives (control, I/O, block) from handcrafted
|
|
knowledge plus the loader's priority and quantum configuration.
|
|
\end{enumerate}
|
|
|
|
%% TODO(bob): The source "Morning Pickup Notes" list ends with an unresolved item
|
|
%% ("Something else I can't recall") and a reminder to generate formal docs for the
|
|
%% Governance Repository. Confirm what the missing item was before this scrap is
|
|
%% promoted to a finished chapter.
|