// 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 }; } 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 }> { 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(['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>>(); function usesOf(hw: any): Map> { const hit = firstUse.get(hw); if (hit) return hit; const mem = hw.memory(); const L: number = mem.hierarchy.line; const lines = new Map>(); 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(); 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 { const out = new Map(); 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); }