Home /Modules/cpu/TIMING.md

TIMING.md

lib/cpu/TIMING.md · 156 line(s) · markdown

lib/cpu — Voltages, Variable Clocks, and Expert Timings

This document covers the timing/voltage/expertise layer added on top of the hardware stack in CPU.md. The point of this layer is a single thesis:

A compiled .sleela program should carry the stated operating point it was built for, so a compiler or VM operates those declared timings — the actual voltages, the dialed clocks, the expert bus/CPU/I/O/RAM timings — rather than assuming the quality of the hardware as a confidence about how CPUs operate.

Everything here is nameful and quality-first: every timing path carries a signal name and a human reason, every voltage rail is named, and nothing is dialed to a speed its budgets and its settled voltage do not honor.

The classes

ClassRole
SLVoltageRailOne named, adjustable supply rail with actual voltages in millivolts — nominal, operator offset, hard floor/ceiling, load-line droop, and the settled effectiveMv() every timing is proven against.
SLTimingOne named, careful timing budget (ps): setup, hold, propagation, jitter, guardband, checked against a period. The atom all expert timings are built from. Reports slack and the max frequency it honors.
SLBusTimingA bus's variable clock speed (floor/ceiling you dial between) plus three named budgets — address, data-strobe (the carefully-named one), control. Rides a rail: settled voltage caps the trustworthy clock.
SLCpuTimingExpert CPU timings: variable core clock + Vcore rail + per-stage pipeline budgets (fetch/decode/execute/writeback). The critical stage sets the honest max clock.
SLIOTimingExpert timings for control of I/O: variable link clock + Vio rail + named handshake / turnaround / recovery budgets + clock-domain-crossing synchronizer latency.
SLRamTimingExpert timings for RAM: variable data rate + Vddq rail + CL/tRCD/tRP/tRAS/tRC/command-rate as cycles, with real-nanosecond access latency derived.
SLTimingClassThe expertise tier as a Class Object — Novice / Basic / Advanced / Expert — carrying the brand/medium and the policy (guardband, headroom, clock headroom, whether expert knobs/rails may be changed).
SLTimingProfileThe one object that gathers all rails + all expert timings under one SLTimingClass, dials them to the tier, checks honored(), and seals an SLTimingManifest.
SLTimingManifestThe compact, serializable record a compiled .sleela image carries — tier, dialed clocks, settled voltages, RAM primaries, honored flag, worst slack. Read back by the VM/loader so declared timings are honored.

Actual voltages, as adjustable settings

SLVoltageRail models the real electrical operating point in millivolts:

SLVoltageRail vcore = new SLVoltageRail();
vcore.configure("Vcore", 1200, 950, 1450);  // nominal / floor / ceiling (mV)
vcore.setLoadLine(500);                      // 0.5 mOhm load line (micro-ohms)
vcore.setLoad(60000);                        // 60 A draw (milliamps)
vcore.adjust(-30);                           // undervolt 30 mV (clamped to window)
int settled = vcore.effectiveMv();           // nominal + offset - droop

The settled voltage is what every timing budget on that rail is checked against. A locked rail clamps any adjustment back inside [floor, ceiling], so a dialed point is always electrically safe; unlock() (Expert tier only) lifts the cap for bench work.

Variable clock speeds for buses (careful and nameful)

A bus is not assumed to run at a frequency — its clock is dialed between a floor and a ceiling, and the ceiling is additionally capped by what the settled rail voltage supports:

SLBusTiming mem = new SLBusTiming();
mem.configure("MemBus", 400, 2400, 64, 2);   // floor/ceiling MHz, 64-bit, DDR
mem.attachRail(vsoc, 1);                      // 1 mV of settled Vsoc per MHz
mem.setDataPath(90, 25, 18, 10);              // the carefully-named data strobe
int actual = mem.setClock(2133);              // clamped into range AND voltage
boolean ok = mem.honored();                   // all three lanes + rail together

The data-strobe path ("data-strobe", "payload must settle inside the data eye on every transfer edge") is given its own name and reason because, per the thesis, timing issues for buses must be careful and nameful. worstSlackPs() names how close to the edge the bus runs.

Expert timings: CPU, I/O, RAM

Expertise tiers as Class Objects

Novice / Basic / Advanced / Expert are objects, not flags. A tier is its policy:

SLTimingClass t = new SLTimingClass();
t.expert("ACME DDR5 B-die");          // brand/medium label
boolean mayTune = t.allowsKnob();     // Expert: true; Novice/Basic: false
int dial = t.dialableMHz(5000);       // Expert takes the ceiling; Novice backs off 30%
TierGuardbandRail headroomClock headroomExpert knobsRails unlockable
Novice120 ps120 mV30 % below ceilingread-onlyno
Basic80 ps80 mV20 %read-onlyno
Advanced50 ps40 mV10 %writableno
Expert20 ps10 mV0 % (edge)writableyes

A safer tier runs the rails a little higher (more margin) and the clocks lower; Expert runs lean and fast. All four tiers are internally honored out of the box.

The whole profile → a manifest a .sleela file carries

SLTimingProfile p = new SLTimingProfile();
p.configure(SLTimingClass.TIER_ADVANCED, "ACME SoC rev C");
p.dialCore(1500);          // tier-governed: refused above the honest ceiling
p.adjustVcore(-20);        // undervolt; raising needs Advanced+
boolean ok = p.honored();  // every expert timing on every rail, together
SLTimingManifest man = p.toManifest();   // flatten to the embeddable record

Operating declared timings instead of assuming hardware quality

The compiler stamps the sealed manifest into every program it emits, and the VM adopts it — so the engine honors what the image states:

SLCompilerDriver driver = new SLCompilerDriver();
driver.configure(isa);
driver.useTimingProfile(p);                       // stamp the operating point
SLProgram prog = driver.compileFile("app.sleela", "app");
// prog.hasTiming() == true; prog.timingHonored() reflects the sealed check

SLSleelaVM vm = new SLSleelaVM(); vm.configure(4096, 1024, 256);
vm.adoptProgramTiming(prog);                      // operate the DECLARED point
int coreMHz = vm.declaredCoreMHz();               // 0 if the image stated none

SLProgram grows an optional SLTimingManifest; SLTimingManifest.writeHeader / readHeader serialize it as a 17-word header (magic 5213) ahead of the instruction stream, so any consumer can tell "this image carries a stated profile" from "this image expects me to assume one" — and never fabricates a clock or voltage it was not told.

End to end via SLMachine

SLMachine m = new SLMachine();
m.powerOnAndRun(4, 32, 3200, 8);
SLTimingProfile prof = m.selectTiming(SLTimingClass.TIER_EXPERT, "SleelaWorks SL-Core-X");
SLProgram app = m.compileWithTiming("app.sleela", 0, "app");  // carries the manifest
boolean honored = m.timingHonored();

Fidelity note

Like the rest of lib/cpu, this is a clear behavioral model: millivolt and picosecond integer arithmetic that captures the real structure — settled voltage gating clock speed, critical-path-limited frequency, DRAM primaries deriving real latency, clock-domain-crossing cost, and an expertise policy that governs how far any of it may be pushed — at a level that stays readable as SLeeLa source.