// SPDX-FileCopyrightText: 2026 Scientific Computing Studio, LLC // SPDX-License-Identifier: Apache-2.0 // Stage 15: the Hardware area's machine board. The course's views draw it (src/engines/asm86/views.js and // hwviews.js) and need a DOM, so they are checked by hand; what they are given is decided DOM-free in // core/hardware.ts and is tested here, for every problem that has assembly: which views each preset mounts and with // what options, and the frame each one draws at every step. import test from 'node:test'; import assert from 'node:assert/strict'; import { themeBodyClass } from '../dist/ui/theme.js'; import { BOARD_PRESETS, BOARD_VIEWS, BOARD_GROUPS, MACHINE_PRESETS, boardPreset, boardView, boardFrame, subRegisterWidths, normalizeBoard, presetOf, moveItem, addItem, removeItem, toggleWide, isWide, courseViews, parseMachine, machineName, machineSpec, machineLabel, lineTouches, asmMojoLines, relateAsmMojo } from '../dist/core/hardware.js'; import { stageOccupancy, STAGES } from '../core/dist/engines/asm86/pipeline.js'; import { coreAt } from '../core/dist/engines/asm86/ooo.js'; import { decompose } from '../core/dist/engines/asm86/uops.js'; import fs from 'node:fs'; import { stripHeader, buildListing } from '../core/scripts/mojo/listings.mjs'; import { forSimulator, simulatorSetup } from '../core/dist/mojo/att.js'; import { listingFunctions, mojoBuildArgs } from '../core/dist/services/godbolt.js'; import { hardwareFor, resolveMachine } from '../core/dist/engines/asm86/machine.js'; import { viewNames } from '../core/dist/engines/asm86/views.js'; import { PROBLEMS, stateForProblem } from '../dist/core/catalog.js'; import { Session } from '../dist/core/session.js'; import { normalize, emptyState } from '../dist/core/state.js'; import { SERVICES } from '../core/dist/services/index.js'; globalThis.localStorage = { getItem() { return null; }, setItem() { }, removeItem() { } }; /** Every catalog problem with an x86-64 pane, run as the Hardware area runs it. */ const WITH_ASM = PROBLEMS.filter((p) => (p.sources?.asm ?? '').trim()); const traceOf = (p, machine) => { const st = stateForProblem(p); if (machine) st.machine = machine; st.lang = 'asm'; const s = new Session(st, { area: 'hw', storageId: null }); const tr = s.trace(); assert.ok(tr && tr.lang === 'asm', `${p.id}: the x86-64 pane runs`); return { session: s, tr, raw: tr.raw.trace }; }; test('the body class follows what the page shows: the setting, the system, or a host page that forces one', () => { assert.equal(themeBodyClass('light', true), 'quarto-light', 'a light app on a dark system draws light widgets'); assert.equal(themeBodyClass('dark', false), 'quarto-dark'); assert.equal(themeBodyClass('system', true), 'quarto-dark'); assert.equal(themeBodyClass('system', false), 'quarto-light'); for (const setting of ['light', 'dark', 'system']) for (const sys of [true, false]) { assert.equal(themeBodyClass(setting, sys, 'dark'), 'quarto-dark', 'an embed\'s ?theme= (or the host\'s switch) wins'); assert.equal(themeBodyClass(setting, sys, 'light'), 'quarto-light'); } }); test('every card the board offers is a course view or one of the app\'s own, in a group, and every preset is made of them', () => { const known = new Set(viewNames()); const APP = new Set(['setup', 'output', 'problems', 'compiler', 'run', 'counters', 'lines']); assert.ok(WITH_ASM.length >= 10, 'the problems with assembly are found'); assert.equal(new Set(BOARD_VIEWS.map((v) => v.id)).size, BOARD_VIEWS.length, 'each card once'); for (const v of BOARD_VIEWS) { assert.ok(BOARD_GROUPS.includes(v.group), `${v.id}: a group of the add menu`); assert.ok(v.label && v.blurb, `${v.id}: a label and a line saying what it shows`); if (v.course) assert.ok(known.has(v.course.name), `${v.id} mounts "${v.course.name}", which views.js does not have`); else assert.ok(APP.has(v.id), `${v.id}: drawn by the app`); } for (const preset of BOARD_PRESETS) { assert.ok(preset.items.length >= 3 && preset.items.every((it) => boardView(it.id)), `${preset.id}: cards that exist`); assert.equal(presetOf(preset.items), preset.id, 'a preset is recognized as itself'); for (const p of WITH_ASM) { const { raw } = traceOf(p); for (const machine of ['teaching', 'teaching+paging']) for (const c of courseViews(preset.items, raw, parseMachine(machine))) { assert.ok(known.has(c.name)); assert.equal(typeof c.options, 'object', `${preset.id}/${c.id}: options for ${p.id}`); } } } assert.equal(boardPreset(undefined).id, 'regs', 'the board opens on registers and memory'); assert.equal(boardPreset('nonsense').id, 'regs'); assert.ok(BOARD_PRESETS.some((p) => p.items.some((it) => it.id === 'run')), 'a preset for the Mojo side'); }); test('the student\'s own arrangement: move, add, remove, widen, and what a saved one may hold', () => { const regs = boardPreset('regs').items; const moved = moveItem(regs, regs.length - 1, 0); assert.equal(moved[0].id, regs[regs.length - 1].id); assert.equal(moved.length, regs.length); assert.equal(presetOf(moved), null, 'a changed arrangement is the student\'s own'); assert.deepEqual(moveItem(moved, 0, regs.length - 1).map((x) => x.id), regs.map((x) => x.id), 'and moves back'); assert.deepEqual(moveItem(regs, 9, 0), regs, 'a move from nowhere changes nothing'); const added = addItem(regs, 'pipeline', 0); assert.equal(added[0].id, 'pipeline'); assert.deepEqual(addItem(added, 'pipeline'), added, 'a card is on the board once'); assert.deepEqual(addItem(regs, 'warp-drive'), regs, 'an unknown card is not added'); assert.ok(!removeItem(added, 'pipeline').some((x) => x.id === 'pipeline')); const flags = regs.find((x) => x.id === 'flags'); assert.equal(isWide(toggleWide(regs, 'flags').find((x) => x.id === 'flags')), !isWide(flags)); assert.deepEqual(normalizeBoard([{ id: 'flags', wide: true }, 'memory', { id: 'flags' }, { id: 'nope' }, 7, null]), [{ id: 'flags', wide: true }, { id: 'memory' }], 'known cards, each once, widths kept'); assert.equal(normalizeBoard('regs'), undefined); assert.equal(normalizeBoard(Array.from({ length: 40 }, () => 'flags')).length, 1); assert.ok(normalizeBoard(BOARD_VIEWS.map((v) => v.id)).length <= 24, 'at most 24 cards'); // virtual memory's card mounts only with virtual memory on const { raw } = traceOf(PROBLEMS.find((x) => x.id === 'asm-two-pointers')); assert.deepEqual(courseViews([{ id: 'paging' }], raw, parseMachine('teaching')), []); assert.equal(courseViews([{ id: 'paging' }], raw, parseMachine('teaching+paging')).length, 1); }); test('the frame at every step is the one the course views expect, for every problem with assembly', () => { for (const p of WITH_ASM) { const { raw } = traceOf(p); for (let t = -1; t <= raw.count + 1; t++) { const f = boardFrame(raw, t); const tt = Math.max(0, Math.min(t, raw.count)); assert.equal(f.t, tt); assert.equal(f.state, raw.states[tt]); assert.equal(f.last, tt ? raw.steps[tt - 1] : null, `${p.id}: the step that just ran`); if (f.next) assert.equal(f.next, raw.program.instrs[f.state.pc]); } } }); test('the register cards show every width the program uses', () => { const asm = SERVICES.asm.parse(' mov eax, 7\n mov cl, byte ptr [rdi]\n add r8d, 1\n mov rbx, rsi\n ret'); assert.ok(asm.ok); assert.deepEqual(new Set(subRegisterWidths(asm.program)), new Set(['rax', 'rcx', 'r8']), 'rbx and rsi are only used whole'); const widths = PROBLEMS.find((p) => p.id === 'asm-register-widths'); assert.ok(widths, 'the register-widths problem exists'); const { raw } = traceOf(widths); assert.ok(subRegisterWidths(raw.program).length > 1, 'its registers show their narrower names'); }); test('the arrangement is part of the area\'s layout and normalizes', () => { const st = emptyState(); st.layout = { hw: { board: [{ id: 'cache', wide: false }, 'flags'], dock: 0.5 } }; assert.deepEqual(normalize(JSON.parse(JSON.stringify(st))).layout.hw.board, [{ id: 'cache', wide: false }, { id: 'flags' }]); st.layout = { hw: { board: 'warp-drive' } }; assert.equal(normalize(JSON.parse(JSON.stringify(st))).layout.hw.board, undefined); const s = new Session(emptyState(), { area: 'hw', storageId: null }); s.setLayout({ board: [{ id: 'counters' }] }); assert.deepEqual(s.layout().board, [{ id: 'counters' }]); }); test('each load and store shows the line it touched and how much of the line the program uses', () => { let touched = 0, missed = 0, partial = 0; for (const p of WITH_ASM) for (const machine of ['teaching', 'realistic', 'teaching+paging']) { const { raw } = traceOf(p, machine); const hw = hardwareFor(raw); const L = hw.memory().hierarchy.line; assert.deepEqual(lineTouches(hw, 0), [], 'nothing has run at step 0'); for (let t = 1; t <= raw.count; t++) { const step = raw.steps[t - 1]; const xs = lineTouches(hw, t); if (!machine.includes('paging')) { // without virtual memory the caches see the program's own addresses: every access of the step is there const want = step.accesses.reduce((n, a) => n + (Math.floor((a.addr + Math.max(1, a.size) - 1) / L) - Math.floor(a.addr / L) + 1), 0); assert.equal(xs.length, want, `${p.id} step ${t}: one entry per line per access`); } for (const x of xs) { touched++; if (!x.hit) missed++; assert.equal(x.lineSize, L); assert.equal(x.lineAddr % L, 0); assert.ok(x.from >= 0 && x.from < x.to && x.to <= L, `${p.id} step ${t}: the bytes are inside the line`); assert.equal(x.hit, x.level === 'L1d', 'a hit is a line found in L1d'); for (let b = x.from; b < x.to; b++) assert.ok(x.usedSoFar.includes(b), 'the bytes used now count as used'); assert.ok(x.usedSoFar.every((b) => x.usedInRun.includes(b)), 'used so far is part of used in the run'); assert.ok(x.usedInRun.length <= L); if (x.usedInRun.length < L) partial++; if (!machine.includes('paging')) assert.equal(x.vaddr, x.addr); } } } assert.ok(touched > 50, 'the problems load and store'); assert.ok(missed > 0, 'the teaching machine misses on small data'); assert.ok(partial > 0, 'some lines are only partly used, which is what the view is for'); }); test('virtual memory: the line is the physical one, and the access keeps the address the program wrote', () => { const p = PROBLEMS.find((x) => x.id === 'asm-two-pointers'); const { raw } = traceOf(p, 'teaching+paging'); const hw = hardwareFor(raw); const all = []; for (let t = 1; t <= raw.count; t++) all.push(...lineTouches(hw, t).map((x) => ({ x, step: raw.steps[t - 1] }))); assert.ok(all.length); for (const { x, step } of all) assert.ok(step.accesses.some((a) => x.vaddr >= a.addr && x.vaddr < a.addr + Math.max(1, a.size)), 'the virtual address is one the instruction used'); assert.ok(all.some(({ x }) => x.vaddr !== x.addr), 'and at least one is translated to another physical address'); }); test('Mojo beside x86-64: the line table the compiler left in the pane links each instruction to its Mojo line', () => { const asm = 'add: ; add(Int, Int)\n mov rax, rdi ; mojo line 2\n add rax, rsi ; mojo line 2\n ret\n call add ; mojo line 6'; assert.deepEqual([...asmMojoLines(asm)], [[2, 2], [3, 2], [5, 6]]); assert.deepEqual(relateAsmMojo(asm, 'asm', 3), [2]); assert.deepEqual(relateAsmMojo(asm, 'asm', 4), [], 'an instruction the compiler added belongs to no line'); assert.deepEqual(relateAsmMojo(asm, 'mojo', 2), [2, 3]); assert.deepEqual(relateAsmMojo(asm, 'mojo', 9), []); assert.equal(asmMojoLines(' mov rax, 7 ; a constant\n ret').size, 0, 'hand-written x86-64 is not linked'); // a real listing, as Open in Hardware makes it from godbolt's saved answer const ROOT = new URL('..', import.meta.url).pathname; let checked = 0; for (const f of fs.readdirSync(ROOT + 'core/library/mojo/probes').filter((x) => x.endsWith('.mojo'))) { const text = fs.readFileSync(ROOT + 'core/library/mojo/probes/' + f, 'utf8'); if (!/^# mode: (asm|both)/m.test(text)) continue; const r = buildListing(text, ROOT + 'core/library/mojo/golden', { forSimulator, simulatorSetup, listingFunctions, mojoBuildArgs }); if (r.why) continue; const table = asmMojoLines(r.asm); if (!table.size) continue; checked++; const mojoLines = stripHeader(text).source.split('\n'); for (const [a, m] of table) { assert.ok(m >= 1 && m <= mojoLines.length, `${f}: x86-64 line ${a} points at Mojo line ${m}, inside the program`); assert.ok(relateAsmMojo(r.asm, 'mojo', m).includes(a), `${f}: and back`); } } assert.ok(checked >= 1, 'a committed listing carries a line table'); }); test('Open in Hardware on a compiled function: the work it makes can be shared, whatever data the function brings', async () => { // a function sent to the x86-64 pane brings the read-only data its code addresses in the setup; with the compiler's // half-megabyte table of source locations that was 2.5 MB for three of demo's functions, and the link the app // wrote for such work was one it refused to open (core writes a long block as quoted text now) const { encodeState, decodeState, LIMITS } = await import('../dist/core/state.js'); const ROOT = new URL('..', import.meta.url).pathname; const status = JSON.parse(fs.readFileSync(ROOT + 'core/library/mojo/golden/status.json', 'utf8')); const golden = JSON.parse(fs.readFileSync(`${ROOT}core/library/mojo/golden/${status.items.find((x) => x.id === 'local/demo').key}.json`, 'utf8')); const fns = listingFunctions(golden.result.asm); for (const name of ['cell', 'Grid::__init__', 'align', 'main']) { const fn = fns.find((f) => f.kind === 'user' && f.name.startsWith(name)); assert.ok(fn, `demo has no function ${name}`); const s = new Session(stateForProblem(PROBLEMS.find((p) => p.id === 'demo')), { area: 'hw', storageId: null }); const { source, data } = forSimulator(fns, fn); s.setSource('asm', source); s.setSetup(simulatorSetup(fn, data)); s.setLang('asm'); assert.ok(s.trace().count >= 1, `${name} does not step`); const size = JSON.stringify(s.state).length; assert.ok(size < LIMITS.stateBytes / 2, `${name}: a state of ${size} bytes, against the ${LIMITS.stateBytes} a link may unpack to`); const back = await decodeState(await encodeState(s.state)); assert.equal(back.setup, s.state.setup, `${name}: the setup does not come back from its own link`); assert.equal(back.sources.asm, s.state.sources.asm); } });