Initial commit
Build, test, deploy / site (push) Failing after 15m13s

This commit is contained in:
alexm committed 2026-11-12 22:24:02 -05:00
commit e092cb029c
252 files changed
+35037

No files matched your search

+279
View File
@@ -0,0 +1,279 @@
// SPDX-FileCopyrightText: 2026 Scientific Computing Studio, LLC
// SPDX-License-Identifier: Apache-2.0
/**
* The Hardware area's machine board, without the DOM (restructure plan, Stage 15). The views themselves are the
* course's (`src/engines/asm86/views.js` and `hwviews.js`), mounted by `src/ui/hw/board.ts`; this module decides
* what they are given: which views a preset shows and with what options, and the frame each one draws. Everything
* here runs under `node --test`, so the board's data steps are tested without a browser.
*/
import { REGS } from '#core/engines/asm86/interp.js';
/* ---------- the machine (core/machine.ts) ---------- */
export { MACHINE_PRESETS, parseMachine, machineName, machineSpec, machineLabel, type MachineChoice } from '#core/common/machine.js';
import { parseMachine, type MachineChoice } from '#core/common/machine.js';
/* ---------- the board ---------- */
/**
* Everything the Hardware area's board can show, one card each. Course views are mounted by name with options
* (`course`); the others are the app's own: the run setup, the output, the problems, the compiler, the Run view,
* the counters, and the cache-line view. `needs` is the pane whose run a view reads: the machine views read the
* x86-64 pane's run, the Run view and the compiler the Mojo pane's; a card whose pane is not open says so.
*/
export type BoardViewId =
| 'registers' | 'flags' | 'address' | 'memory' | 'stack' | 'explain' | 'dataflow' | 'bits' | 'branches' | 'vectors'
| 'lines' | 'cache' | 'hierarchy' | 'paging'
| 'pipeline' | 'uops' | 'timeline' | 'bottleneck' | 'core' | 'machine' | 'encoding' | 'code'
| 'setup' | 'output' | 'problems' | 'compiler' | 'run' | 'counters';
export interface BoardViewDef {
id: BoardViewId;
label: string;
group: string;
/** What it shows, in a line (the add menu, the card's tooltip). */
blurb: string;
needs: 'asm' | 'mojo' | 'any';
/** Takes the board's whole width unless the student narrows it. */
wide: boolean;
/** A course view: its name in views.js / hwviews.js and its options for a run. */
course?: { name: string; options?: (trace: any, machine: MachineChoice) => Record<string, unknown> };
}
export const BOARD_GROUPS = ['Program', 'Registers and memory', 'Memory system', 'Time', 'The chip'] as const;
export const BOARD_VIEWS: BoardViewDef[] = [
{ id: 'setup', label: 'Setup', group: 'Program', needs: 'any', wide: false, blurb: 'The run setup: registers, memory and input for x86-64; the build and input for Mojo; the machine.' },
{ id: 'output', label: 'Output', group: 'Program', needs: 'any', wide: false, blurb: 'What the run has printed so far.' },
{ id: 'problems', label: 'Problems', group: 'Program', needs: 'any', wide: false, blurb: 'Every message on the open pane, with its one-click fixes.' },
{ id: 'compiler', label: 'Compiler', group: 'Program', needs: 'mojo', wide: true, blurb: 'The real Mojo compiler on godbolt: its messages, the output, and the listing, with Open in Hardware for a function.' },
{ id: 'run', label: 'Run', group: 'Program', needs: 'mojo', wide: true, blurb: 'The Mojo run top to bottom, with the variables you follow and their lifetimes.' },
{ id: 'code', label: 'Machine code listing', group: 'Program', needs: 'asm', wide: false, blurb: 'Every instruction with its address and bytes, the one about to run marked.', course: { name: 'code', options: () => ({ addresses: true, bytes: true, heat: true }) } },
{ id: 'explain', label: 'What it did', group: 'Registers and memory', needs: 'asm', wide: false, blurb: 'The last instruction in words: what it read, computed and wrote.', course: { name: 'explain' } },
{ id: 'registers', label: 'Registers', group: 'Registers and memory', needs: 'asm', wide: true, blurb: 'A card per register the program touches, with the value before and every narrower name it uses.', course: { name: 'registers', options: (trace) => ({ widths: subRegisterWidths(trace.program) }) } },
{ id: 'flags', label: 'Flags', group: 'Registers and memory', needs: 'asm', wide: false, blurb: 'ZF, SF, CF, OF, PF, with the ones the last instruction set and read.', course: { name: 'flags' } },
{ id: 'address', label: 'Address arithmetic', group: 'Registers and memory', needs: 'asm', wide: false, blurb: 'base + index × scale + displacement, part by part.', course: { name: 'address' } },
{ id: 'memory', label: 'Memory', group: 'Registers and memory', needs: 'asm', wide: true, blurb: 'Each memory region byte by byte, the load (blue) or store (purple) highlighted.', course: { name: 'memory' } },
{ id: 'stack', label: 'Stack', group: 'Registers and memory', needs: 'asm', wide: false, blurb: 'Eight-byte slots with rsp and rbp marked, and what put each there.', course: { name: 'stack' } },
{ id: 'dataflow', label: 'Data flow', group: 'Registers and memory', needs: 'asm', wide: false, blurb: 'Where the last instruction\'s values came from and went.', course: { name: 'dataflow' } },
{ id: 'bits', label: 'Inside the ALU', group: 'Registers and memory', needs: 'asm', wide: true, blurb: 'The arithmetic unit at bit level for the last instruction.', course: { name: 'bits' } },
{ id: 'branches', label: 'Branches', group: 'Registers and memory', needs: 'asm', wide: false, blurb: 'Each branch: taken or not, and whether the predictor guessed right.', course: { name: 'branches' } },
{ id: 'vectors', label: 'Vector registers', group: 'Registers and memory', needs: 'asm', wide: true, blurb: 'The xmm registers lane by lane.', course: { name: 'vectors' } },
{ id: 'lines', label: 'Cache lines', group: 'Memory system', needs: 'asm', wide: true, blurb: 'The cache line each load and store touched, and how many of its bytes the program uses.' },
{ id: 'cache', label: 'L1d cache', group: 'Memory system', needs: 'asm', wide: true, blurb: 'The L1 data cache as sets and ways: a hit green, a miss red, the evicted line named.', course: { name: 'cache', options: () => ({ level: 'L1d' }) } },
{ id: 'hierarchy', label: 'Memory hierarchy', group: 'Memory system', needs: 'asm', wide: false, blurb: 'L1, L2, L3 and memory: the path each access took, and running totals.', course: { name: 'hierarchy' } },
{ id: 'paging', label: 'Virtual memory', group: 'Memory system', needs: 'asm', wide: true, blurb: 'The page walk and the TLB, with virtual memory on.', course: { name: 'paging' } },
{ id: 'pipeline', label: 'Five-stage pipeline', group: 'Time', needs: 'asm', wide: true, blurb: 'Cycle by cycle: stalls amber, wrong-path fetches red.', course: { name: 'pipeline' } },
{ id: 'uops', label: 'Micro-ops and ports', group: 'Time', needs: 'asm', wide: false, blurb: 'The micro-ops the last instruction became, and the ports each can run on.', course: { name: 'uops' } },
{ id: 'timeline', label: 'Out-of-order timeline', group: 'Time', needs: 'asm', wide: true, blurb: 'When each instruction entered the core, ran and retired.', course: { name: 'timeline' } },
{ id: 'bottleneck', label: 'What limits the speed', group: 'Time', needs: 'asm', wide: false, blurb: 'The dependency chain, the busiest ports and the front end, against the time taken.', course: { name: 'bottleneck' } },
{ id: 'counters', label: 'Counters', group: 'Time', needs: 'asm', wide: false, blurb: 'The run as the model machine counts it, in the style of perf stat, and what each Mojo line cost on it.' },
{ id: 'machine', label: 'The whole core', group: 'The chip', needs: 'asm', wide: true, blurb: 'From the branch predictor to memory, the parts the last instruction used lit up.', course: { name: 'machine' } },
{ id: 'core', label: 'Inside the out-of-order core', group: 'The chip', needs: 'asm', wide: true, blurb: 'The reorder buffer, the ports, and which physical register each name points at.', course: { name: 'core' } },
{ id: 'encoding', label: 'Instruction encoding', group: 'The chip', needs: 'asm', wide: false, blurb: 'The bytes of the last instruction, broken into prefix, REX, opcode, ModRM, SIB, displacement and immediate.', course: { name: 'encoding' } },
];
export const boardView = (id: string): BoardViewDef | undefined => BOARD_VIEWS.find((v) => v.id === id);
/** One card on the board: which view, and its width when the student changed it. */
export interface BoardItem { id: BoardViewId; wide?: boolean }
export interface BoardPreset { id: string; label: string; blurb: string; items: BoardItem[] }
const items = (...ids: BoardViewId[]): BoardItem[] => ids.map((id) => ({ id }));
/** Arrangements that make sense to see at once; the student can change any of them. */
export const BOARD_PRESETS: BoardPreset[] = [
{ id: 'regs', label: 'Registers and memory', blurb: 'What each instruction does: the registers it writes, the flags, the address it computes, the bytes of memory it reads or writes, the stack.', items: items('registers', 'flags', 'address', 'memory', 'stack', 'output', 'setup') },
{ id: 'caches', label: 'Caches', blurb: 'What memory costs on the model machine: the cache line each access touches and how much of it is used, the L1 data cache, the hierarchy.', items: items('lines', 'cache', 'hierarchy', 'memory', 'output') },
{ id: 'pipeline', label: 'Pipeline', blurb: 'Time: the five-stage pipeline, the micro-ops and ports, what limits the speed, the out-of-order timeline.', items: items('pipeline', 'uops', 'bottleneck', 'timeline') },
// The listing and the encoding of the instruction it marks sit side by side; the out-of-order core, whose table
// grows and shrinks with what is in flight, goes last so that nothing below it moves while stepping.
{ id: 'chip', label: 'Whole chip', blurb: 'The whole core with the parts each instruction uses lit up, the machine code beside the encoding of the instruction it marks, and inside the out-of-order core.', items: items('machine', 'code', 'encoding', 'core') },
{ id: 'mojo', label: 'Mojo and the compiler', blurb: 'The Mojo side: the run with its variables and lifetimes, the real compiler\'s answer and listing, the output.', items: items('run', 'compiler', 'output', 'problems') },
];
export const boardPreset = (id: string | undefined | null): BoardPreset => BOARD_PRESETS.find((p) => p.id === id) ?? BOARD_PRESETS[0];
/** A saved arrangement, cleaned: known views only, each once, at most 24. */
export function normalizeBoard(x: unknown): BoardItem[] | undefined {
if (!Array.isArray(x)) return undefined;
const out: BoardItem[] = [];
for (const it of x) {
const id = typeof it === 'string' ? it : it && typeof it === 'object' ? (it as any).id : null;
if (typeof id !== 'string' || !boardView(id) || out.some((o) => o.id === id)) continue;
const wide = it && typeof it === 'object' && typeof (it as any).wide === 'boolean' ? (it as any).wide : undefined;
out.push(wide === undefined ? { id: id as BoardViewId } : { id: id as BoardViewId, wide });
if (out.length >= 24) break;
}
return out;
}
/** Whether a card is drawn at the board's whole width. */
export const isWide = (it: BoardItem): boolean => it.wide ?? boardView(it.id)!.wide;
/** The preset an arrangement is, or null when the student has made it their own. */
export function presetOf(list: BoardItem[]): string | null {
const same = (a: BoardItem[], b: BoardItem[]) => a.length === b.length && a.every((x, i) => x.id === b[i].id && isWide(x) === isWide(b[i]));
return BOARD_PRESETS.find((p) => same(p.items, list))?.id ?? null;
}
/** The arrangement with the card at `from` moved to position `to` (drag and drop, or the move buttons). */
export function moveItem(list: BoardItem[], from: number, to: number): BoardItem[] {
if (from < 0 || from >= list.length) return list.slice();
const out = list.slice();
const [it] = out.splice(from, 1);
out.splice(Math.max(0, Math.min(to, out.length)), 0, it);
return out;
}
export function addItem(list: BoardItem[], id: BoardViewId, at = list.length): BoardItem[] {
if (!boardView(id) || list.some((x) => x.id === id)) return list.slice();
const out = list.slice();
out.splice(Math.max(0, Math.min(at, out.length)), 0, { id });
return out;
}
export const removeItem = (list: BoardItem[], id: BoardViewId): BoardItem[] => list.filter((x) => x.id !== id);
export const toggleWide = (list: BoardItem[], id: BoardViewId): BoardItem[] => list.map((x) => (x.id === id ? { id, wide: !isWide(x) } : x));
/** The course views a set of cards mounts, with their options for this run (the board's data step). Paging only with virtual memory on. */
export function courseViews(list: BoardItem[], trace: any, machine: MachineChoice): Array<{ id: BoardViewId; name: string; options: Record<string, unknown> }> {
return list.flatMap((it) => {
const v = boardView(it.id)!;
if (!v.course) return [];
if (v.id === 'paging' && !machine.paging) return [];
return [{ id: v.id, name: v.course.name, options: v.course.options ? v.course.options(trace, machine) : {} }];
});
}
/**
* The 64-bit registers the program also uses under a narrower name (`eax`, `al`, `r8b`): their card shows every
* width, so `mov al, …` visibly changes only the low byte of `rax`. `rax` always does, since it holds the answer.
*/
export function subRegisterWidths(program: any): string[] {
const out = new Set<string>(['rax']);
for (const ins of program?.instrs ?? []) {
for (const o of ins.operands ?? []) {
const names = o.kind === 'reg' ? [o.name] : o.kind === 'mem' ? [o.base, o.index] : [];
for (const n of names) {
const r = n && (REGS as any)[n];
if (r && !r.vector && r.base !== n) out.add(r.base);
}
}
}
return [...out];
}
/** A frame is everything a course view needs to draw one moment (the same shape as `frameAt` in views.js). */
export interface BoardFrame { t: number; trace: any; state: any; last: any; next: any }
export function boardFrame(trace: any, t: number): BoardFrame {
const clamped = Math.max(0, Math.min(Math.floor(Number(t) || 0), trace.count));
const state = trace.states[clamped];
const last = clamped > 0 ? trace.steps[clamped - 1] : null;
const next = state.pc < trace.program.instrs.length && !state.halted ? trace.program.instrs[state.pc] : null;
return { t: clamped, trace, state, last, next };
}
/* ---------- cache lines ---------- */
/** One cache line touched by one memory access of the step that just ran. */
export interface LineTouch {
kind: 'read' | 'write';
/** The access: its address as the program wrote it, the physical address the caches saw (the same without virtual memory), and its size in bytes. */
vaddr: number;
addr: number;
size: number;
/** The line: its address and size, and the bytes of it this access covered, as offsets [from, to). */
lineAddr: number;
lineSize: number;
from: number;
to: number;
/** Where the line was found: L1d (a hit), L2, L3, or memory. */
level: string;
hit: boolean;
/** Bytes of this line the program has used so far (this access included), and in the whole run, as sorted offsets. */
usedSoFar: number[];
usedInRun: number[];
/** What put the access there when it was not an instruction's own operand: a push, a call's return address, the kernel. */
stack: string | null;
kernel: boolean;
}
/** For each line, the step at which each of its bytes was first used. Computed once per hardware model. */
const firstUse = new WeakMap<object, Map<number, Map<number, number>>>();
function usesOf(hw: any): Map<number, Map<number, number>> {
const hit = firstUse.get(hw);
if (hit) return hit;
const mem = hw.memory();
const L: number = mem.hierarchy.line;
const lines = new Map<number, Map<number, number>>();
mem.steps.forEach((rec: any, k: number) => {
for (const r of rec.data) {
for (let b = r.addr; b < r.addr + Math.max(1, r.size); b++) {
const lineAddr = Math.floor(b / L) * L;
let m = lines.get(lineAddr);
if (!m) { m = new Map(); lines.set(lineAddr, m); }
if (!m.has(b - lineAddr)) m.set(b - lineAddr, k);
}
}
});
firstUse.set(hw, lines);
return lines;
}
/**
* The cache lines the step that just ran (step t-1) touched with its loads and stores: which line, which bytes of
* it, where it was found, and how many of its bytes the program uses so far and in the whole run. A program that
* reads one byte of each 64-byte line moves 64 bytes for every one it uses; this is where that shows.
*/
export function lineTouches(hw: any, t: number): LineTouch[] {
const mem = hw.memory();
const k = Math.floor(Number(t) || 0) - 1;
if (k < 0 || k >= mem.steps.length) return [];
const L: number = mem.hierarchy.line;
const uses = usesOf(hw);
const out: LineTouch[] = [];
for (const r of mem.steps[k].data) {
for (const line of r.lines) {
const m = uses.get(line.lineAddr) ?? new Map<number, number>();
const soFar = [...m].filter(([, at]) => at <= k).map(([off]) => off).sort((a, b) => a - b);
out.push({
kind: r.kind === 'write' ? 'write' : 'read', vaddr: r.vaddr ?? r.addr, addr: r.addr, size: r.size,
lineAddr: line.lineAddr, lineSize: L,
from: Math.max(r.addr, line.lineAddr) - line.lineAddr,
to: Math.min(r.addr + Math.max(1, r.size), line.lineAddr + L) - line.lineAddr,
level: line.level, hit: !!line.trail[0]?.hit,
usedSoFar: soFar, usedInRun: [...m.keys()].sort((a, b) => a - b),
stack: r.stack ?? null, kernel: !!r.kernel,
});
}
}
return out;
}
/* ---------- Mojo beside x86-64 ---------- */
/**
* The line table of x86-64 sent from the Compiler view: `forSimulator` (mojo/att.ts) ends every instruction that
* came from a line of the Mojo program with `; mojo line N`, from godbolt's own line table. Map: x86-64 line (1-based)
* to Mojo line. Empty for x86-64 written by hand, which no Mojo line produced.
*/
export function asmMojoLines(asm: string): Map<number, number> {
const out = new Map<number, number>();
String(asm ?? '').split('\n').forEach((text, i) => {
const m = /;\s*mojo line (\d+)\s*$/.exec(text);
if (m) out.set(i + 1, Number(m[1]));
});
return out;
}
/** The lines of the other pane that match `line` of pane `from`, through that table (sorted; empty when nothing matches). */
export function relateAsmMojo(asm: string, from: 'asm' | 'mojo', line: number): number[] {
const table = asmMojoLines(asm);
if (from === 'asm') { const m = table.get(line); return m == null ? [] : [m]; }
return [...table].filter(([, m]) => m === line).map(([a]) => a).sort((a, b) => a - b);
}