Files
pplus-web/tests/hardware.test.mjs
T
alexm ce45d30cc7
Build, test, deploy / site (push) Failing after 1m37s
feat: cleanup with respect to core
2026-10-06 10:30:36 -04:00

210 lines
12 KiB
JavaScript

// 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 } 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 });
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');
});