Files
pplus-web/src/core/hardware.ts
T
alexm e092cb029c
Build, test, deploy / site (push) Failing after 15m13s
Initial commit
2026-11-12 22:24:02 -05:00

280 lines
18 KiB
TypeScript
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.
// 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);
}