// Test benches: a table of tests docked to a placed component. Each row sets // its inputs, gives it clock ticks if asked, and checks its outputs. The // component runs on its own (no wires to the circuit around it), from all // zeros, its state carried from row to row, so a row can test memory, a // counter, or a whole computer running until it is done. // // Pins A0, A1, … make one column A that takes a number. An input cell is a // number (12, 0x0C, 0b1100), P for a clock pulse, or empty to leave it as // it was. An output cell is the number it should show, empty for any. // Ticks: N pulses (the P inputs and the component's own clocks) before the // check; ≤N gives up to N, checking after each, until the outputs match. import { compile } from './compile' import { chipPins, type DefLookup } from './geometry' import { Simulator } from './sim' import type { Bench, BenchRow, ComponentDef } from './types' export interface BenchColumn { name: string /** Pin keys, bit 0 first. */ keys: string[] } export interface RowResult { /** True all checks hold, false one does not, null nothing to check. */ ok: boolean | null /** Outputs after the row, by column. */ got: Record /** Ticks the row ran. */ ticks: number error?: string } export interface BenchResult { rows: RowResult[] pass: number fail: number error?: string } const SETTLE = 2_000_000 /** Ticks a run gives in all, at most (a run in the editor stays short; by hand it may go longer). */ export const AUTO_TICKS = 20_000 export const HAND_TICKS = 500_000 /** Rows "every combination" makes, at most (10 input bits). */ export const MAX_COMBO_BITS = 10 const SERIES = /^(.*?)(\d+)$/ /** Pins as columns: A0…An (numbered from 0, none missing) make one column A, any other pin is its own. */ export function groupPins(pins: { key: string; label: string }[]): BenchColumn[] { const series = new Map>() for (const p of pins) { const m = SERIES.exec(p.label.trim()) if (!m || !m[1]) continue const s = series.get(m[1]) ?? new Map() s.set(Number(m[2]), p.key) series.set(m[1], s) } const whole = new Set([...series.entries()].filter(([, s]) => s.size >= 2 && [...s.keys()].every(i => i < s.size)).map(([name]) => name)) const out: BenchColumn[] = [] const done = new Set() for (const p of pins) { const m = SERIES.exec(p.label.trim()) const name = m?.[1] if (name && whole.has(name)) { if (done.has(name)) continue done.add(name) const s = series.get(name)! out.push({ name, keys: [...s.keys()].sort((a, b) => a - b).map(i => s.get(i)!) }) } else out.push({ name: p.label.trim() || p.key, keys: [p.key] }) } return out } export function benchColumns(def: ComponentDef): { ins: BenchColumn[]; outs: BenchColumn[] } { const pins = chipPins(def) return { ins: groupPins(pins.inputs), outs: groupPins(pins.outputs) } } /** A cell as a number, P (inputs only), or null when empty or a don't-care. */ export function parseCell(s: string | undefined, bits: number, input: boolean): number | 'P' | null | { error: string } { const t = (s ?? '').trim() if (!t || t === '-' || t.toLowerCase() === 'x') return null if (input && /^(p|↑)$/i.test(t)) return 'P' let v: number if (/^\d+$/.test(t)) v = parseInt(t, 10) else if (/^0x[0-9a-f]+$/i.test(t)) v = parseInt(t.slice(2), 16) else if (/^0b[01]+$/i.test(t)) v = parseInt(t.slice(2), 2) else if (/^-\d+$/.test(t)) v = 2 ** bits + parseInt(t, 10) else return { error: `"${t}" is not a number${input ? ' or P' : ''}` } if (v < 0 || v >= 2 ** bits) return { error: `${t} does not fit in ${bits} bit${bits === 1 ? '' : 's'}` } return v } /** Ticks of a row: N, or ≤N (also <=N) to wait for the outputs. Empty: one pulse when the row has a P, else none. */ export function parseTicks(s: string | undefined): { n: number; wait: boolean } | null | { error: string } { const t = (s ?? '').trim() if (!t) return null const m = /^(≤|<=|<|max\s*|up\s*to\s*)?\s*(\d+)$/i.exec(t) if (!m) return { error: `Ticks "${t}": a number, or ≤ and a number` } const n = parseInt(m[2]!, 10) if (n > HAND_TICKS) return { error: `Ticks: at most ${HAND_TICKS}` } return { n, wait: !!m[1] } } /** Runs a bench's rows on the component, in order. */ export function runBench(getDef: DefLookup, defId: string, rows: BenchRow[], maxTicks = AUTO_TICKS): BenchResult { const def = getDef(defId) const res: BenchResult = { rows: [], pass: 0, fail: 0 } if (!def) return { ...res, error: 'The component it tests no longer exists' } const cols = benchColumns(def) const sim = new Simulator(compile(getDef, defId)) sim.run(SETTLE) const clocks = sim.nl.clocks.length > 0 let left = maxTicks const read = (c: BenchColumn) => c.keys.reduce((v, k, i) => v + (sim.output(k) ? 2 ** i : 0), 0) for (const row of rows) { const out: RowResult = { ok: null, got: {}, ticks: 0 } res.rows.push(out) const fail = (error: string) => { out.ok = false out.error = error res.fail++ } // Inputs, pulses held low for now. const pulses: BenchColumn[] = [] let bad = '' for (const c of cols.ins) { const v = parseCell(row.set?.[c.name], c.keys.length, true) if (v && typeof v === 'object') bad ||= `${c.name}: ${v.error}` else if (v === 'P') { pulses.push(c) c.keys.forEach(k => sim.setSource(k, false)) } else if (v !== null) c.keys.forEach((k, i) => sim.setSource(k, Math.floor(v / 2 ** i) % 2 === 1)) } const checks: { c: BenchColumn; want: number }[] = [] for (const c of cols.outs) { const v = parseCell(row.expect?.[c.name], c.keys.length, false) if (v && typeof v === 'object') bad ||= `${c.name}: ${v.error}` else if (typeof v === 'number') checks.push({ c, want: v }) } const ticks = parseTicks(row.ticks) if (ticks && 'error' in ticks) bad ||= ticks.error if (bad) { fail(bad) continue } const spec = (ticks as { n: number; wait: boolean } | null) ?? { n: pulses.length ? 1 : 0, wait: false } if (spec.n && !pulses.length && !clocks) { fail('Ticks, but nothing to tick: give a clock input P, or a clock inside') continue } if (!sim.run(SETTLE)) { fail('It oscillates and never settles') continue } const matches = () => checks.every(({ c, want }) => read(c) === want) const tick = (): boolean => { for (const c of pulses) c.keys.forEach(k => sim.setSource(k, true)) if (clocks) sim.setClock(1) if (!sim.run(SETTLE)) return false for (const c of pulses) c.keys.forEach(k => sim.setSource(k, false)) if (clocks) sim.setClock(0) return sim.run(SETTLE) } let stopped = '' for (let t = 0; t < spec.n; t++) { if (spec.wait && checks.length && matches()) break if (left-- <= 0) { stopped = `Stopped after ${maxTicks.toLocaleString('en')} ticks in all` break } if (!tick()) { stopped = 'It oscillates and never settles' break } out.ticks++ } for (const c of cols.outs) out.got[c.name] = read(c) if (stopped) { fail(stopped) if (left <= 0) { res.error = stopped break } continue } if (!checks.length) continue out.ok = matches() if (out.ok) res.pass++ else { res.fail++ if (spec.wait) out.error = `Not within ${spec.n} ticks` } } return res } /** Every combination of the inputs, counting up (the first column the highest), outputs left to fill. */ export function combinationRows(def: ComponentDef): BenchRow[] | { error: string } { const { ins } = benchColumns(def) const bits = ins.reduce((n, c) => n + c.keys.length, 0) if (!ins.length) return { error: 'It has no inputs' } if (bits > MAX_COMBO_BITS) return { error: `${bits} input bits are ${2 ** bits} combinations: at most ${MAX_COMBO_BITS} bits` } const rows: BenchRow[] = [] for (let i = 0; i < 2 ** bits; i++) { let rest = i const set: Record = {} for (let k = ins.length - 1; k >= 0; k--) { const c = ins[k]! const n = 2 ** c.keys.length set[c.name] = String(rest % n) rest = Math.floor(rest / n) } rows.push({ set }) } return rows } /** * The rows with what the component shows now in their empty output cells * (to keep it working the same). Outputs already filled in stay as they are, * so a row that waits for them waits the same. */ export function recordExpected(getDef: DefLookup, defId: string, rows: BenchRow[]): BenchRow[] { const r = runBench(getDef, defId, rows, HAND_TICKS) return rows.map((row, i) => { const got = r.rows[i]?.got if (!got || (r.rows[i]?.error && r.rows[i]?.ok !== false)) return row const expect = { ...row.expect } for (const [k, v] of Object.entries(got)) if (!expect[k]?.trim()) expect[k] = String(v) return { ...row, expect } }) } /** A bench cell's value for a column, by name. */ export const cellOf = (row: BenchRow, side: 'set' | 'expect', name: string) => row[side]?.[name] ?? '' export type { Bench, BenchRow }