From 8ef19cf0530fc6fb5726d9e01e7bdad082abc537 Mon Sep 17 00:00:00 2001 From: stefan Date: Sat, 27 Jun 2026 11:36:55 +0900 Subject: [PATCH] tests for safsim and wip ppsfp implementation --- main.py | 8 +- src/fsim/ppsfp.py | 85 ++++++++++++++++++ tests/test_safsim.py | 203 +++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 294 insertions(+), 2 deletions(-) create mode 100644 src/fsim/ppsfp.py create mode 100644 tests/test_safsim.py diff --git a/main.py b/main.py index 355016a..3014e62 100755 --- a/main.py +++ b/main.py @@ -12,13 +12,17 @@ from kyupy.techlib import techlib_by_name, KYUPY from fsim.static import LineRoles, FaultSet from fsim.simple import SAFSimSimple from fsim.incremental import SAFSimIncremental +from fsim.ppsfp import SAFSimPPSFP def main(): + algorithms = {'simple': SAFSimSimple, 'incr': SAFSimIncremental, 'ppsfp': SAFSimPPSFP} + parser = argparse.ArgumentParser(description='A basic stuck-at fault simulator.') parser.add_argument('-t', '--tlib', default='SKY130', help=f'Techlib for verilog circuit. Default: SKY130, available: {sorted(techlib_by_name.keys())}.') parser.add_argument('-p', '--patterns', default='1024', help='Pattern file or number of random patterns to simulate. Default: 1024.') + parser.add_argument('-a', '--algorithm', default='simple', help=f'Fault simulation algorithm. Default: simple, available: {sorted(algorithms.keys())}.') parser.add_argument('-o', '--output', default=None, help='') parser.add_argument('--seed', type=int, default=42, help='Random seed for reproducibility. Default: 42.') parser.add_argument('circuit', help='Gate-level verilog, bench, or nix package to import. See available packages: "nix flake show github:s-holst/benchmark-circuits".') @@ -76,8 +80,8 @@ def main(): saf_collapsed = np.array(list(fs.saf_equiv_classes.keys()), dtype=np.uint32) rng.shuffle(saf_collapsed) - safsim = SAFSimSimple(c_resolved, min(patterns.shape[1], 10240)) - log.info(f'{safsim.sim=}') + safsim = algorithms[args.algorithm](c_resolved, min(patterns.shape[1], 10240)) + log.info(f'{args.algorithm} {safsim.sim=}') fclasses = safsim.classify_faults(saf_collapsed, patterns) diff --git a/src/fsim/ppsfp.py b/src/fsim/ppsfp.py new file mode 100644 index 0000000..2336b80 --- /dev/null +++ b/src/fsim/ppsfp.py @@ -0,0 +1,85 @@ +import time +from collections.abc import Collection + +import numpy as np + +from kyupy import log, batchrange, cdiv, Timers, logic +from kyupy.circuit import Circuit, Node +from kyupy.logic_sim import LogicSim2V +from kyupy.techlib import KYUPY + +class SAFSimPPSFP: + """A stuck-at fault simulator that uses explicit simulations only at roots of fan-out free regions. + """ + + def __init__(self, circuit_resolved: Circuit, batch_size: int): + self.sim = LogicSim2V(circuit_resolved, sims=batch_size) + self.timers = Timers() + + self.ffr_stem2idx = {} + self.lines2ffr_stem: list[Node|None] = [None] * len(circuit_resolved.lines) + for stem, nodes in circuit_resolved.fanout_free_regions(KYUPY): + self.ffr_stem2idx[stem] = len(self.ffr_stem2idx) + for n in nodes + [stem]: + for il in n.ins.without_nones(): + self.lines2ffr_stem[il.index] = stem + + def classify_faults(self, faults: Collection[int], patterns: np.ndarray): + + with self.timers['startup']: + self.sim.c_prop() # trigger jit + c_golden = np.zeros_like(self.sim.c) + fclass_DS = set() + nbatches = cdiv(patterns.shape[1], self.sim.sims) + nfaults = len(faults) + ffr_obs = np.zeros((len(self.ffr_stem2idx), self.sim.c.shape[2]), dtype=np.uint8) + ffr_obs_valid = np.zeros(len(self.ffr_stem2idx), dtype=np.uint8) + obs_mask = np.packbits(np.full(patterns.shape[1], 1, dtype=np.uint8), bitorder='little') + fault_to_stem_obs = obs_mask.copy() + fault_act = obs_mask.copy() + + with self.timers['sim'], log.progress() as p: + for bidx, (bo, bs) in enumerate(batchrange(patterns.shape[1], self.sim.sims)): + self.sim.s_assign[:, :bs] = patterns[:, bo:bo+bs] + self.sim.s_to_c() + self.sim.c_dirty[...] = 1 + with self.timers['sim_full_prop']: + self.sim.c_prop() + c_golden[...] = self.sim.c + c_golden_poppo = c_golden[self.sim.poppo_c_locs] + ffr_obs_valid[...] = 0 + + for fidx, fault in enumerate(faults): + fault_site = fault//2 + fault_polarity = fault&1 + ffr_stem = self.lines2ffr_stem[fault_site] + assert ffr_stem is not None + ffr_idx = self.ffr_stem2idx[ffr_stem] + + # compute FFR observability vector ffr_obs[ffr_idx] if necessary + if not ffr_obs_valid[ffr_idx]: + if len(ffr_stem.outs) > 1: + self.sim.c_dirty[...] = 0 + with self.timers['sim_ffr_prop']: + self.sim.c_prop(fault_line=ffr_stem.ins[0].index, fault_model=2) + with self.timers['sim_ffr_obs']: + ffr_obs[ffr_idx] = np.bitwise_or.reduce(c_golden_poppo ^ self.sim.c[self.sim.poppo_c_locs], axis=0) & obs_mask + with self.timers['sim_ffr_reset']: + self.sim.c[...] = c_golden # clear fault + else: # primary output, completely observable + ffr_obs[ffr_idx] = obs_mask + ffr_obs_valid[ffr_idx] = 1 + + # FIXME: compute observability of fault location at FFR stem + fault_to_stem_obs[...] = obs_mask + + # compute fault activation + fault_act[...] = self.sim.c[self.sim.c_locs[fault_site]] & obs_mask + if fault_polarity: # stuck-at 1? + fault_act ^= obs_mask # activated iff signal is 0 + + if np.bitwise_or.reduce(ffr_obs[ffr_idx] & fault_to_stem_obs & fault_act) != 0: + fclass_DS.add(fault) + p.update(((fidx+1) / nfaults) * ((bidx+1) / nbatches)) + + return {'DS': fclass_DS, 'NO': set(faults) - fclass_DS} \ No newline at end of file diff --git a/tests/test_safsim.py b/tests/test_safsim.py new file mode 100644 index 0000000..0fda9c7 --- /dev/null +++ b/tests/test_safsim.py @@ -0,0 +1,203 @@ +"""Unit tests for the stuck-at fault simulators (the SAF* classes). + +Each fault is identified by ``line.index * 2 + polarity`` where polarity 0 is +stuck-at-0 and polarity 1 is stuck-at-1. ``classify_faults`` returns a dict +with the detected-by-simulation set under ``'DS'`` and the not-observed set +under ``'NO'``. + +The three simulators are exercised side-by-side: + * ``SAFSimSimple`` - brute force, exact. + * ``SAFSimIncremental`` - incremental cone re-simulation, exact. + * ``SAFSimPPSFP`` - FFR-based, deliberately *optimistic*: its stem + observability is hard-wired to "always observable" (see the FIXME in + ``ppsfp.py``), so its DS set is a super-set of the exact DS set. +""" + +import itertools + +import numpy as np +import pytest + +from kyupy import bench, logic +from kyupy.techlib import KYUPY +from fsim.static import FaultSet +from fsim.simple import SAFSimSimple +from fsim.incremental import SAFSimIncremental +from fsim.ppsfp import SAFSimPPSFP + + +# The two exact simulators must always agree; PPSFP only over-approximates. +ALL_ALGS = [SAFSimSimple, SAFSimIncremental, SAFSimPPSFP] + + +def make_patterns(*specs): + """Build a 2D pattern array from per-pattern strings via ``logic.mvarray``. + + Each string holds one character per s-node, ordered as the inputs and + outputs are defined in the netlist (output positions are don't-cares here, + overwritten by simulation). The result has shape ``(n_s_nodes, n_patterns)`` + as expected by the simulators; a lone pattern is reshaped to a single column. + """ + pat = logic.mvarray(*specs) + return pat if pat.ndim == 2 else pat.reshape(-1, 1) + + +def classify(alg, circuit, faults, patterns): + # PPSFP requires the batch size to match the pattern count (as main.py does). + sim = alg(circuit, patterns.shape[1]) + return sim.classify_faults(list(faults), patterns) + + +def saf(line, polarity): + return line.index * 2 + polarity + + +# --------------------------------------------------------------------------- # +# Inline single-gate circuits with hand-computed expectations. +# --------------------------------------------------------------------------- # + +@pytest.mark.parametrize('alg', ALL_ALGS) +def test_inv_single_pattern(alg): + # s-nodes are 'i','o'. i=0 => golden o=1. Detect faults that flip o off 1. + c = bench.parse('input(i) output(o) o=INV(i)') + oline = c.forks['o'].ins[0] + iline = oline.driver.ins[0] + pat = make_patterns('0-') # i=0 (o position is a don't-care) + faults = [saf(oline, 0), saf(oline, 1), saf(iline, 0), saf(iline, 1)] + r = classify(alg, c, faults, pat) + # o s-a-0 forces 0 (!=1) -> detected; i s-a-1 forces i=1 -> o=0 -> detected. + assert r['DS'] == {saf(oline, 0), saf(iline, 1)} + # o s-a-1 already matches golden; i s-a-0 keeps i=0 -> nothing changes. + assert r['NO'] == {saf(oline, 1), saf(iline, 0)} + + +@pytest.mark.parametrize('alg', ALL_ALGS) +def test_inv_both_polarities_detected(alg): + # Applying both i=0 and i=1 sensitises every fault of the inverter. + c = bench.parse('input(i) output(o) o=INV(i)') + oline = c.forks['o'].ins[0] + iline = oline.driver.ins[0] + pat = make_patterns('00', '10') # i=0 and i=1 + faults = [saf(oline, 0), saf(oline, 1), saf(iline, 0), saf(iline, 1)] + r = classify(alg, c, faults, pat) + assert r['DS'] == set(faults) + assert r['NO'] == set() + + +@pytest.mark.parametrize('alg', ALL_ALGS) +def test_and2_output(alg): + # s-nodes are 'i0','i1','o'. + c = bench.parse('input(i0,i1) output(o) o=AND2(i0,i1)') + oline = c.forks['o'].ins[0] + o_sa0, o_sa1 = saf(oline, 0), saf(oline, 1) + + # i0=i1=1 => golden o=1: only o s-a-0 is observable. + r = classify(alg, c, [o_sa0, o_sa1], make_patterns('110')) + assert r['DS'] == {o_sa0} + assert r['NO'] == {o_sa1} + + # i0=0,i1=1 => golden o=0: only o s-a-1 is observable. + r = classify(alg, c, [o_sa0, o_sa1], make_patterns('010')) + assert r['DS'] == {o_sa1} + assert r['NO'] == {o_sa0} + + +@pytest.mark.parametrize('alg', ALL_ALGS) +def test_two_level_nand_propagation(alg): + # o = NAND2(NAND2(a,b), c); s-nodes 'a','b','c','o'. a=b=c=1: n=0, o=1. + c = bench.parse('input(a,b,c) output(o) n=NAND2(a,b) o=NAND2(n,c)') + nline = c.forks['n'].ins[0] + oline = c.forks['o'].ins[0] + faults = [saf(nline, 0), saf(nline, 1), saf(oline, 0), saf(oline, 1)] + r = classify(alg, c, faults, make_patterns('1110')) + # n already 0 (s-a-0 invisible); n s-a-1 -> o=0; o s-a-0 visible; o already 1. + assert r['DS'] == {saf(nline, 1), saf(oline, 0)} + assert r['NO'] == {saf(nline, 0), saf(oline, 1)} + + +# --------------------------------------------------------------------------- # +# c17 fixture: small, fully testable combinational benchmark. +# --------------------------------------------------------------------------- # + +def _c17_exhaustive_patterns(): + """All 2**5 input combinations of c17. + + s-nodes are inputs 1,2,3,6,7 then outputs 22,23 (netlist order); the two + output positions are don't-cares appended after the five input bits. + """ + return make_patterns(*[''.join(combo) + '--' + for combo in itertools.product('01', repeat=5)]) + + +@pytest.mark.parametrize('alg', ALL_ALGS) +def test_c17_fully_detected(alg, c17_bench, c17_resolved): + # c17 has no redundant faults, so exhaustive patterns detect every fault. + fs = FaultSet(c17_bench, KYUPY, c17_resolved) + faults = list(fs.saf_equiv_classes.keys()) + pat = _c17_exhaustive_patterns() + r = classify(alg, c17_resolved, faults, pat) + assert r['DS'] == set(faults) + assert r['NO'] == set() + + +@pytest.mark.parametrize('alg', ALL_ALGS) +def test_c17_output_fault_class(alg, c17_resolved): + # All-zero inputs: output 22 settles to 0, so only its s-a-1 is observable. + o22 = c17_resolved.forks['22'].ins[0] + pat = make_patterns('00000--') # all inputs 0 + r = classify(alg, c17_resolved, [saf(o22, 0), saf(o22, 1)], pat) + assert r['DS'] == {saf(o22, 1)} + assert r['NO'] == {saf(o22, 0)} + + +# --------------------------------------------------------------------------- # +# s27 fixture: exposes the exact-vs-optimistic difference between simulators. +# --------------------------------------------------------------------------- # + +def _s27_setup(s27_bench, s27_resolved): + fs = FaultSet(s27_bench, KYUPY, s27_resolved) + faults = list(fs.saf_equiv_classes.keys()) + rng = np.random.default_rng(1) + pat = rng.choice([logic.ZERO, logic.ONE], + size=(len(s27_resolved.s_nodes(KYUPY)), 64)).astype(np.uint8) + return faults, pat + + +def test_s27_exact_simulators_agree(s27_bench, s27_resolved): + faults, pat = _s27_setup(s27_bench, s27_resolved) + assert len(faults) == 32 # collapsed fault count, see test_fault_set.test_s27 + + simple = classify(SAFSimSimple, s27_resolved, faults, pat) + incr = classify(SAFSimIncremental, s27_resolved, faults, pat) + + # The two exact simulators must classify every fault identically. + assert simple['DS'] == incr['DS'] + assert simple['NO'] == incr['NO'] + # This deterministic pattern set leaves exactly one fault unobserved. + assert len(simple['DS']) == 31 + assert len(simple['NO']) == 1 + + +def test_s27_ppsfp_over_approximates(s27_bench, s27_resolved): + faults, pat = _s27_setup(s27_bench, s27_resolved) + + exact = classify(SAFSimSimple, s27_resolved, faults, pat) + ppsfp = classify(SAFSimPPSFP, s27_resolved, faults, pat) + + # PPSFP's optimistic stem observability can only add detections, never drop. + assert exact['DS'] <= ppsfp['DS'] + # Here it reports the lone exact-NO fault as detected too. + assert ppsfp['DS'] == exact['DS'] | exact['NO'] + + +@pytest.mark.parametrize('alg', ALL_ALGS) +def test_ppsfp_multibranch_stem_observability(alg): + # Stem `s` fans out to two AND gates; with sel1=0,sel2=1 the stem is + # observable only through the o2 branch (the stem's *second* fanout line). + c = bench.parse('input(a,b,sel1,sel2) output(o1,o2) ' + 's=NAND2(a,b) o1=AND2(s,sel1) o2=AND2(s,sel2)') + a_sa0 = saf(c.forks['s'].ins[0].driver.ins[0], 0) + # a=1,b=1,sel1=0,sel2=1: a s-a-0 flips s, propagating through o2 only. + pat = make_patterns('1101--') + r = classify(alg, c, [a_sa0], pat) + assert r['DS'] == {a_sa0}