warptap 0.0.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (48) hide show
  1. warptap/__init__.py +107 -0
  2. warptap/bsr_insert.py +330 -0
  3. warptap/bsr_model.py +113 -0
  4. warptap/bsr_plan.py +109 -0
  5. warptap/cli.py +27 -0
  6. warptap/errors.py +17 -0
  7. warptap/faultflow_retarget.py +168 -0
  8. warptap/icl_emit.py +405 -0
  9. warptap/icl_import.py +253 -0
  10. warptap/icl_model.py +117 -0
  11. warptap/jamplayer_check.py +83 -0
  12. warptap/netlist.py +235 -0
  13. warptap/pdl_emit.py +110 -0
  14. warptap/pdl_history.py +54 -0
  15. warptap/pdl_interpreter.py +280 -0
  16. warptap/pdl_verify.py +88 -0
  17. warptap/pipeline.py +50 -0
  18. warptap/py.typed +0 -0
  19. warptap/rtl/bc1_full.v +52 -0
  20. warptap/rtl/bc1_shift_only.v +30 -0
  21. warptap/rtl/bc7_bidir.v +47 -0
  22. warptap/rtl/instrument_write.v +65 -0
  23. warptap/rtl/sib_cell.v +63 -0
  24. warptap/rtl/tap_core.v +153 -0
  25. warptap/sib_insert.py +289 -0
  26. warptap/sib_layout.py +95 -0
  27. warptap/sib_model.py +141 -0
  28. warptap/sib_overshift.py +198 -0
  29. warptap/sib_plan.py +82 -0
  30. warptap/sib_retarget.py +61 -0
  31. warptap/sim_io.py +87 -0
  32. warptap/stapl_crc16.py +69 -0
  33. warptap/svf_openocd_check.py +72 -0
  34. warptap/tap_fsm.py +67 -0
  35. warptap/tap_ir.py +119 -0
  36. warptap/tap_ir_play.py +162 -0
  37. warptap/tap_ir_stapl.py +203 -0
  38. warptap/tap_ir_stil.py +291 -0
  39. warptap/tap_ir_svf.py +92 -0
  40. warptap/tap_model.py +214 -0
  41. warptap/tap_ports.py +28 -0
  42. warptap/yosys_io.py +146 -0
  43. warptap-0.0.1.dist-info/METADATA +103 -0
  44. warptap-0.0.1.dist-info/RECORD +48 -0
  45. warptap-0.0.1.dist-info/WHEEL +5 -0
  46. warptap-0.0.1.dist-info/entry_points.txt +2 -0
  47. warptap-0.0.1.dist-info/licenses/LICENSE +201 -0
  48. warptap-0.0.1.dist-info/top_level.txt +1 -0
warptap/__init__.py ADDED
@@ -0,0 +1,107 @@
1
+ """warptap — inserts IEEE 1149.1 (JTAG/TAP) and IEEE 1687 (IJTAG/ICL+PDL) test-access
2
+ infrastructure into a design.
3
+
4
+ This module re-exports the real entry points a caller actually needs -- everything else stays
5
+ reachable via its own module (``warptap.<module>``), this is a curated surface, not a
6
+ flattening of every internal helper. See README.md's own Usage section for an end-to-end
7
+ example using these names.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ from warptap.bsr_insert import BsrInsertError, insert_bsr
13
+ from warptap.errors import WarptapError
14
+ from warptap.faultflow_retarget import FaultflowRetargetError, retarget_faultflow_patterns
15
+ from warptap.icl_emit import IclEmitError, to_icl
16
+ from warptap.icl_import import IclImportError, import_icl
17
+ from warptap.icl_model import (
18
+ ICLAddressError,
19
+ InstrumentDirection,
20
+ InstrumentNode,
21
+ ModuleInstance,
22
+ PhysicalGraph,
23
+ SibNode,
24
+ SignalBinding,
25
+ resolve_dotted_address,
26
+ )
27
+ from warptap.netlist import Netlist
28
+ from warptap.pdl_emit import PdlEmitError, to_pdl
29
+ from warptap.pdl_interpreter import PDLError, PDLInterpreter
30
+ from warptap.pdl_verify import PDLVerifyError, ReadCheckResult, check_reads, correlate_observed
31
+ from warptap.pipeline import insert_test_access
32
+ from warptap.sib_insert import SibInsertError, insert_sib_network
33
+ from warptap.sib_plan import InstrumentSpec, build_sib_plan
34
+ from warptap.tap_ir import (
35
+ GotoState,
36
+ PulsePin,
37
+ Runtest,
38
+ ShiftDR,
39
+ ShiftIR,
40
+ bits_from_int,
41
+ bits_to_int,
42
+ )
43
+ from warptap.tap_ir_stapl import TapIrStaplError, to_stapl
44
+ from warptap.tap_ir_stil import TapIrStilError, to_stil
45
+ from warptap.tap_ir_svf import TapIrSvfError, to_svf
46
+ from warptap.yosys_io import YosysError, ingest, write_verilog_from_json
47
+
48
+ __version__ = "0.0.1"
49
+
50
+ __all__ = [
51
+ "__version__",
52
+ # errors
53
+ "WarptapError",
54
+ "BsrInsertError",
55
+ "FaultflowRetargetError",
56
+ "IclEmitError",
57
+ "IclImportError",
58
+ "ICLAddressError",
59
+ "PdlEmitError",
60
+ "PDLError",
61
+ "PDLVerifyError",
62
+ "SibInsertError",
63
+ "TapIrStaplError",
64
+ "TapIrStilError",
65
+ "TapIrSvfError",
66
+ "YosysError",
67
+ # netlist / ingest / re-emit
68
+ "Netlist",
69
+ "ingest",
70
+ "write_verilog_from_json",
71
+ # network model
72
+ "InstrumentDirection",
73
+ "InstrumentNode",
74
+ "ModuleInstance",
75
+ "PhysicalGraph",
76
+ "SibNode",
77
+ "SignalBinding",
78
+ "resolve_dotted_address",
79
+ # insertion
80
+ "InstrumentSpec",
81
+ "build_sib_plan",
82
+ "insert_bsr",
83
+ "insert_sib_network",
84
+ "insert_test_access",
85
+ # PDL
86
+ "PDLInterpreter",
87
+ "to_pdl",
88
+ "check_reads",
89
+ "correlate_observed",
90
+ "ReadCheckResult",
91
+ # ICL
92
+ "to_icl",
93
+ "import_icl",
94
+ # tap_ir / pattern export
95
+ "GotoState",
96
+ "PulsePin",
97
+ "Runtest",
98
+ "ShiftDR",
99
+ "ShiftIR",
100
+ "bits_from_int",
101
+ "bits_to_int",
102
+ "to_svf",
103
+ "to_stapl",
104
+ "to_stil",
105
+ # faultflow
106
+ "retarget_faultflow_patterns",
107
+ ]
warptap/bsr_insert.py ADDED
@@ -0,0 +1,330 @@
1
+ """Boundary-scan register insertion — the impure surgery phase (implementation_plan.md §7
2
+ Stage 3). Given a :class:`~warptap.bsr_plan.BsrPlan` for a target module, imports
3
+ ``tap_core.v`` and the BC cell templates as hierarchical submodules (plan §4.2's "hand-author
4
+ once, capture as JSON" mechanism realized as ordinary Yosys submodule instantiation — see
5
+ ``netlist.Netlist.add_module``'s docstring for why this is simpler than flattened cloning),
6
+ instantiates one cell per :class:`~warptap.bsr_plan.BsrCell`, stitches them into a single
7
+ shift chain, and wires the chain into ``tap_core``'s ``external_dr_tdo`` input.
8
+
9
+ BIDIR/BC_7 cells reuse the target design's own existing tri-state driver for their port
10
+ (``func_in``/enable), found by pattern-matching a ``$mux`` cell with one operand tied to the
11
+ constant ``"z"`` — confirmed empirically that Yosys's default ``proc`` lowering of the standard
12
+ ``assign io = enable ? drive_val : 1'bz;`` idiom produces exactly this shape, *not* a dedicated
13
+ ``$tribuf`` cell (which only appears from passes this project's ingest pipeline doesn't run).
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ from pathlib import Path
19
+
20
+ from warptap.bsr_plan import BsrFunction, BsrPlan
21
+ from warptap.errors import WarptapError
22
+ from warptap.netlist import Bit, Module, Netlist
23
+ from warptap.tap_ports import TCK, TDI, TDO, TMS, TRST_N
24
+ from warptap.yosys_io import ingest
25
+
26
+ _RTL_DIR = Path(__file__).resolve().parent / "rtl"
27
+
28
+ _TAP_CORE = "tap_core"
29
+ _BC1_SHIFT_ONLY = "bc1_shift_only"
30
+ _BC1_FULL = "bc1_full"
31
+ _BC7_BIDIR = "bc7_bidir"
32
+
33
+
34
+ class BsrInsertError(WarptapError):
35
+ """Raised when the target design's structure doesn't match what a Stage 3
36
+ insertion step needs — e.g. no existing tri-state driver found for a bidir
37
+ port — rather than guessing and silently emitting something wrong."""
38
+
39
+
40
+ def _find_existing_tristate_driver(
41
+ top_mod: Module, port_bits: list[Bit]
42
+ ) -> tuple[list[Bit], list[Bit]]:
43
+ """Find the cell driving `port_bits` through the standard
44
+ ``assign io = enable ? drive_val : 1'bz;`` idiom. Returns
45
+ ``(drive_value_bits, enable_bits)``. Raises :class:`BsrInsertError`, naming the
46
+ port bits, if no such driver is found or its polarity isn't the expected
47
+ ``S ? B : A``-with-``A=="z"`` shape (any other shape is a real, distinct case
48
+ this v1 doesn't attempt to guess at)."""
49
+ for cell in top_mod.data.get("cells", {}).values():
50
+ if cell.get("type") != "$mux":
51
+ continue
52
+ connections = cell.get("connections", {})
53
+ if connections.get("Y") != list(port_bits):
54
+ continue
55
+ a_bits, b_bits, s_bits = (
56
+ connections.get("A", []),
57
+ connections.get("B", []),
58
+ connections.get("S", []),
59
+ )
60
+ if a_bits == ["z"]:
61
+ return b_bits, s_bits # Y = S ? B : z -- driven (by B) when S=1
62
+ raise BsrInsertError(
63
+ f"found a $mux driving bits {port_bits} but its 'z' operand isn't in "
64
+ "the expected position (A) -- polarity not handled by this v1"
65
+ )
66
+ raise BsrInsertError(
67
+ f"no existing tri-state driver ($mux with a 'z' operand) found for bits "
68
+ f"{port_bits} -- bidir port insertion needs the design's own drive-value/"
69
+ "enable signals to preserve, and none could be found"
70
+ )
71
+
72
+ # Must match rtl/tap_core.v's own parameter defaults: v1 never overrides them on the
73
+ # hierarchical instance (plan §2 — avoids an unverified per-instance-parameter-override
74
+ # JSON round-trip risk), so these are the actual values in effect, not just a convenient
75
+ # default to relax later.
76
+ DEFAULT_IR_WIDTH = 4
77
+ DEFAULT_OPCODE_EXTEST = 0b0000
78
+
79
+
80
+ def _import_template(netlist: Netlist, module_name: str, *, yosys_command: str | None) -> Module:
81
+ rtl_path = _RTL_DIR / f"{module_name}.v"
82
+ raw = ingest([rtl_path], module_name, yosys_command=yosys_command)
83
+ mod = netlist.add_module(module_name, raw["modules"][module_name])
84
+ # Each template is ingested standalone (its own `hierarchy -top <name>` run), so
85
+ # Yosys marks it `(* top = 1 *)` in its own JSON. Only the actual target design's
86
+ # top module should carry that marker once everything is merged into one netlist
87
+ # — multiple "top" modules is misleading and a plausible source of confusion for
88
+ # any later pass that doesn't pass an explicit `-top` override.
89
+ mod.data.get("attributes", {}).pop("top", None)
90
+ mod.set_module_attribute("keep_hierarchy", 1)
91
+ mod.set_module_attribute("keep", 1)
92
+ return mod
93
+
94
+
95
+ def insert_bsr(
96
+ netlist: Netlist,
97
+ top: str,
98
+ plan: BsrPlan,
99
+ *,
100
+ ir_width: int = DEFAULT_IR_WIDTH,
101
+ opcode_extest: int = DEFAULT_OPCODE_EXTEST,
102
+ yosys_command: str | None = None,
103
+ ) -> None:
104
+ """Insert a TAP + boundary-scan chain into ``netlist``'s ``top`` module,
105
+ matching ``plan`` (from ``bsr_plan.build_bsr_plan``). Adds five new top-level
106
+ JTAG ports (tck/tms/tdi/trst_n/tdo). Every scanned port's *original* bits stay
107
+ fully wired to whatever originally drove/read them — output3 pins get
108
+ ``detach_port``-ed (the real pin becomes new bits driven through a tri-state
109
+ buffer), but their old bits remain the cell's functional passthrough input, so
110
+ normal-mode (``trst_n`` asserted) behavior is provably unchanged — see
111
+ ``tests/test_bsr_insert_equivalence.py``.
112
+
113
+ ``ir_width``/``opcode_extest`` must match ``rtl/tap_core.v``'s actual compiled
114
+ parameters (its own defaults, currently — see the module-level constants above)
115
+ since this function never overrides them on the instance.
116
+ """
117
+ top_mod = netlist.module(top)
118
+ port_bits_by_name = {p.name: p.bits for p in top_mod.ports()}
119
+ # ^ snapshot BEFORE any detach_port calls below, so output3 cells see each
120
+ # port's ORIGINAL functional-drive bits, not a port added in this same pass.
121
+
122
+ _import_template(netlist, _TAP_CORE, yosys_command=yosys_command)
123
+ _import_template(netlist, _BC1_SHIFT_ONLY, yosys_command=yosys_command)
124
+ _import_template(netlist, _BC1_FULL, yosys_command=yosys_command)
125
+ _import_template(netlist, _BC7_BIDIR, yosys_command=yosys_command)
126
+
127
+ tck_bits = top_mod.add_port(TCK, "input")
128
+ tms_bits = top_mod.add_port(TMS, "input")
129
+ tdi_bits = top_mod.add_port(TDI, "input")
130
+ trst_n_bits = top_mod.add_port(TRST_N, "input")
131
+ tdo_bits = top_mod.add_port(TDO, "output")
132
+
133
+ # Allocated up front (bit IDs, not drivers) so the chain-building loop below can
134
+ # reference them before tap_core itself is instantiated at the end, once the
135
+ # chain's final `so` — tap_core's external_dr_tdo input — is actually known.
136
+ tap_state_bits = top_mod.new_wire(4, name="warptap_tap_state")
137
+ current_instruction_bits = top_mod.new_wire(ir_width, name="warptap_current_instruction")
138
+ capture_dr_bits = top_mod.new_wire(1, name="warptap_capture_dr")
139
+ shift_dr_bits = top_mod.new_wire(1, name="warptap_shift_dr")
140
+ update_dr_bits = top_mod.new_wire(1, name="warptap_update_dr")
141
+
142
+ extest_mode_bits = top_mod.new_wire(1, name="warptap_extest_mode")
143
+ opcode_bits: list[Bit] = [str((opcode_extest >> i) & 1) for i in range(ir_width)]
144
+ top_mod.add_cell(
145
+ "warptap_extest_decode",
146
+ "$eq",
147
+ parameters={
148
+ "A_SIGNED": 0, "B_SIGNED": 0,
149
+ "A_WIDTH": ir_width, "B_WIDTH": ir_width, "Y_WIDTH": 1,
150
+ },
151
+ port_directions={"A": "input", "B": "input", "Y": "output"},
152
+ connections={"A": current_instruction_bits, "B": opcode_bits, "Y": extest_mode_bits},
153
+ )
154
+
155
+ prev_so: list[Bit] = tdi_bits
156
+ control_pin_out: dict[int, list[Bit]] = {} # cell_number -> that control cell's pin_out
157
+ control_instance_by_number: dict[int, str] = {} # cell_number -> its own instance name
158
+
159
+ # A control cell is stitched *before* the output3/bidir cell it pairs with (plan
160
+ # ordering), but a bidir pairing's func_in is the port's own pre-existing enable
161
+ # signal — only discoverable once the paired cell is reached and its tri-state
162
+ # driver is searched for. Look ahead once so the control cell's own add_cell call
163
+ # can wire a harmless placeholder now and know to expect a real reconnect later,
164
+ # rather than guessing the pairing's shape mid-loop.
165
+ paired_function_by_control_number = {
166
+ c.disable_cell_index: c.function for c in plan.cells if c.disable_cell_index is not None
167
+ }
168
+
169
+ for cell in plan.cells:
170
+ instance_name = f"warptap_bsr_{cell.cell_number}"
171
+ cell_attrs = {
172
+ "warptap_bsr_cell_number": cell.cell_number,
173
+ "warptap_bsr_port_name": cell.port_name,
174
+ }
175
+
176
+ if cell.function is BsrFunction.INPUT:
177
+ so_bits = top_mod.new_wire(1, name=f"{instance_name}_so")
178
+ top_mod.add_cell(
179
+ instance_name,
180
+ _BC1_SHIFT_ONLY,
181
+ port_directions={
182
+ "pi": "input", "si": "input", "so": "output",
183
+ "capture_dr": "input", "shift_dr": "input",
184
+ "tck": "input", "trst_n": "input",
185
+ },
186
+ connections={
187
+ "pi": port_bits_by_name[cell.port_name],
188
+ "si": prev_so, "so": so_bits,
189
+ "capture_dr": capture_dr_bits, "shift_dr": shift_dr_bits,
190
+ "tck": tck_bits, "trst_n": trst_n_bits,
191
+ },
192
+ attributes=cell_attrs,
193
+ )
194
+ top_mod.set_keep(cell_name=instance_name)
195
+ prev_so = so_bits
196
+
197
+ elif cell.function is BsrFunction.CONTROL:
198
+ so_bits = top_mod.new_wire(1, name=f"{instance_name}_so")
199
+ pin_out_bits = top_mod.new_wire(1, name=f"{instance_name}_pin_out")
200
+ paired_function = paired_function_by_control_number.get(cell.cell_number)
201
+ # v1: plain output3 pairing has no pre-existing output-enable signal to
202
+ # preserve, so func_in is the fixed constant 1 (stated explicitly, not
203
+ # assumed). A bidir pairing DOES have one (the port's own original
204
+ # enable) but it isn't known yet — wire the same harmless placeholder
205
+ # and let the BIDIR branch below reconnect it once found.
206
+ func_in_connection: list[Bit] = ["1"]
207
+ top_mod.add_cell(
208
+ instance_name,
209
+ _BC1_FULL,
210
+ port_directions={
211
+ "func_in": "input", "si": "input", "so": "output", "pin_out": "output",
212
+ "capture_dr": "input", "shift_dr": "input", "update_dr": "input",
213
+ "extest_mode": "input", "tck": "input", "trst_n": "input",
214
+ },
215
+ connections={
216
+ "func_in": func_in_connection,
217
+ "si": prev_so, "so": so_bits, "pin_out": pin_out_bits,
218
+ "capture_dr": capture_dr_bits, "shift_dr": shift_dr_bits,
219
+ "update_dr": update_dr_bits, "extest_mode": extest_mode_bits,
220
+ "tck": tck_bits, "trst_n": trst_n_bits,
221
+ },
222
+ attributes=cell_attrs,
223
+ )
224
+ top_mod.set_keep(cell_name=instance_name)
225
+ prev_so = so_bits
226
+ control_pin_out[cell.cell_number] = pin_out_bits
227
+ if paired_function is BsrFunction.BIDIR:
228
+ control_instance_by_number[cell.cell_number] = instance_name
229
+
230
+ elif cell.function is BsrFunction.OUTPUT3:
231
+ func_in_bits = port_bits_by_name[cell.port_name] # old bits, still fully driven
232
+ top_mod.detach_port(cell.port_name) # old bits kept alive via func_in_bits above
233
+ new_pin_bits = top_mod.port_bits(cell.port_name) # the real pin, now free to drive
234
+ so_bits = top_mod.new_wire(1, name=f"{instance_name}_so")
235
+ cell_pin_out_bits = top_mod.new_wire(1, name=f"{instance_name}_pin_out")
236
+ top_mod.add_cell(
237
+ instance_name,
238
+ _BC1_FULL,
239
+ port_directions={
240
+ "func_in": "input", "si": "input", "so": "output", "pin_out": "output",
241
+ "capture_dr": "input", "shift_dr": "input", "update_dr": "input",
242
+ "extest_mode": "input", "tck": "input", "trst_n": "input",
243
+ },
244
+ connections={
245
+ "func_in": func_in_bits,
246
+ "si": prev_so, "so": so_bits, "pin_out": cell_pin_out_bits,
247
+ "capture_dr": capture_dr_bits, "shift_dr": shift_dr_bits,
248
+ "update_dr": update_dr_bits, "extest_mode": extest_mode_bits,
249
+ "tck": tck_bits, "trst_n": trst_n_bits,
250
+ },
251
+ attributes=cell_attrs,
252
+ )
253
+ top_mod.set_keep(cell_name=instance_name)
254
+ en_bits = control_pin_out[cell.disable_cell_index]
255
+ top_mod.add_cell(
256
+ f"{instance_name}_tribuf",
257
+ "$tribuf",
258
+ parameters={"WIDTH": 1},
259
+ port_directions={"A": "input", "EN": "input", "Y": "output"},
260
+ connections={"A": cell_pin_out_bits, "EN": en_bits, "Y": new_pin_bits},
261
+ )
262
+ prev_so = so_bits
263
+
264
+ elif cell.function is BsrFunction.BIDIR:
265
+ old_bits = port_bits_by_name[cell.port_name]
266
+ func_in_bits, orig_enable_bits = _find_existing_tristate_driver(top_mod, old_bits)
267
+ top_mod.detach_port(cell.port_name)
268
+ new_pin_bits = top_mod.port_bits(cell.port_name) # the real pin, now free to drive
269
+ so_bits = top_mod.new_wire(1, name=f"{instance_name}_so")
270
+ cell_pin_out_bits = top_mod.new_wire(1, name=f"{instance_name}_pin_out")
271
+ top_mod.add_cell(
272
+ instance_name,
273
+ _BC7_BIDIR,
274
+ port_directions={
275
+ "pin_in": "input", "func_in": "input", "si": "input", "so": "output",
276
+ "pin_out": "output", "capture_dr": "input", "shift_dr": "input",
277
+ "update_dr": "input", "extest_mode": "input",
278
+ "tck": "input", "trst_n": "input",
279
+ },
280
+ connections={
281
+ "pin_in": new_pin_bits, # always observes the real pin, drive-direction aside
282
+ "func_in": func_in_bits,
283
+ "si": prev_so, "so": so_bits, "pin_out": cell_pin_out_bits,
284
+ "capture_dr": capture_dr_bits, "shift_dr": shift_dr_bits,
285
+ "update_dr": update_dr_bits, "extest_mode": extest_mode_bits,
286
+ "tck": tck_bits, "trst_n": trst_n_bits,
287
+ },
288
+ attributes=cell_attrs,
289
+ )
290
+ top_mod.set_keep(cell_name=instance_name)
291
+
292
+ # Fix up the paired control cell's func_in, now that the port's own
293
+ # original enable signal is known -- normal-mode (non-EXTEST) drive
294
+ # behavior must keep matching the design's own original enable, not a
295
+ # constant, unlike a plain output3 pairing (plan §3 step 6).
296
+ control_instance = control_instance_by_number[cell.disable_cell_index]
297
+ top_mod.connect(control_instance, "func_in", orig_enable_bits)
298
+
299
+ en_bits = control_pin_out[cell.disable_cell_index]
300
+ top_mod.add_cell(
301
+ f"{instance_name}_tribuf",
302
+ "$tribuf",
303
+ parameters={"WIDTH": 1},
304
+ port_directions={"A": "input", "EN": "input", "Y": "output"},
305
+ connections={"A": cell_pin_out_bits, "EN": en_bits, "Y": new_pin_bits},
306
+ )
307
+ prev_so = so_bits
308
+
309
+ else:
310
+ raise NotImplementedError(f"bsr_insert.py does not yet handle {cell.function}")
311
+
312
+ top_mod.add_cell(
313
+ "warptap_tap_core",
314
+ _TAP_CORE,
315
+ port_directions={
316
+ "tck": "input", "tms": "input", "tdi": "input", "trst_n": "input",
317
+ "tdo": "output", "tap_state": "output", "current_instruction": "output",
318
+ "capture_dr": "output", "shift_dr": "output", "update_dr": "output",
319
+ "external_dr_tdo": "input",
320
+ },
321
+ connections={
322
+ "tck": tck_bits, "tms": tms_bits, "tdi": tdi_bits, "trst_n": trst_n_bits,
323
+ "tdo": tdo_bits, "tap_state": tap_state_bits,
324
+ "current_instruction": current_instruction_bits,
325
+ "capture_dr": capture_dr_bits, "shift_dr": shift_dr_bits,
326
+ "update_dr": update_dr_bits,
327
+ "external_dr_tdo": prev_so, # the chain's final `so` — "wire into the TAP's DR mux"
328
+ },
329
+ )
330
+ top_mod.set_keep(cell_name="warptap_tap_core")
warptap/bsr_model.py ADDED
@@ -0,0 +1,113 @@
1
+ """Python behavioral model of an inserted boundary-scan chain (implementation_plan.md §7
2
+ Stage 3), implementing ``warptap.tap_model``'s ``DataRegister`` protocol so it can be plugged
3
+ into ``TapModel.register_data_register(Instruction.EXTEST, ...)`` — the extension point
4
+ ``TapModelError`` already names. Used by ``tests/test_bsr_insert_cross_sim.py`` to
5
+ cross-simulate against the real inserted RTL; not used by ``bsr_insert.py`` itself, which only
6
+ ever emits RTL.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ from warptap.bsr_plan import BsrCell, BsrFunction, BsrPlan
12
+
13
+
14
+ class _CellState:
15
+ __slots__ = ("cell", "shift_ff", "po")
16
+
17
+ def __init__(self, cell: BsrCell):
18
+ self.cell = cell
19
+ self.shift_ff = 0
20
+ self.po = 0
21
+
22
+
23
+ class BoundaryScanRegister:
24
+ """Models the whole inserted chain as one ``DataRegister``, matching how
25
+ ``tap_core.v`` sees it: a single serial path from TDI, through every
26
+ :class:`~warptap.bsr_plan.BsrCell` in ``cell_number`` order, to
27
+ ``external_dr_tdo``. ``plan.cells`` must contain only INPUT/CONTROL/OUTPUT3
28
+ cells (v1 scope — BIDIR isn't modeled here yet, matching ``bsr_insert.py``)."""
29
+
30
+ def __init__(self, plan: BsrPlan):
31
+ for cell in plan.cells:
32
+ if cell.function not in (
33
+ BsrFunction.INPUT,
34
+ BsrFunction.CONTROL,
35
+ BsrFunction.OUTPUT3,
36
+ ):
37
+ raise NotImplementedError(
38
+ f"BoundaryScanRegister does not yet model {cell.function}"
39
+ )
40
+ self._states = [_CellState(c) for c in plan.cells]
41
+ self._functional_inputs: dict[str, int] = {}
42
+
43
+ def reset(self) -> None:
44
+ """Zero every cell's shift/update state, matching rtl/bc1_full.v's and
45
+ rtl/bc1_shift_only.v's own `trst_n` reset behavior. Callers driving this
46
+ model alongside a TapModel should call this whenever they call
47
+ TapModel.reset() — TapModel.reset() only resets its own FSM/IR state, it
48
+ has no way to know which DataRegister protocol implementations need
49
+ resetting too, since not all of them do (BypassRegister/IdcodeRegister's
50
+ backing rtl/tap_core.v registers have no explicit reset at all)."""
51
+ for state in self._states:
52
+ state.shift_ff = 0
53
+ state.po = 0
54
+
55
+ def set_functional_inputs(self, values: dict[str, int]) -> None:
56
+ """Set the live value each INPUT/OUTPUT3 cell observes, keyed by the cell's
57
+ real ``port_name``. Call this every cycle before ticking the owning
58
+ ``TapModel``, mirroring how the real RTL's ``pi``/``func_in`` ports are
59
+ continuously live, not just sampled once at capture time."""
60
+ self._functional_inputs = values
61
+
62
+ def _observed_value(self, cell: BsrCell) -> int:
63
+ if cell.function is BsrFunction.CONTROL:
64
+ return 1 # matches bsr_insert.py's fixed func_in for v1 control cells
65
+ return self._functional_inputs.get(cell.port_name, 0)
66
+
67
+ def capture(self) -> None:
68
+ for state in self._states:
69
+ state.shift_ff = self._observed_value(state.cell)
70
+
71
+ def shift(self, tdi: int) -> int:
72
+ if not self._states:
73
+ return tdi
74
+ tdo = self._states[-1].shift_ff
75
+ incoming = tdi
76
+ for state in self._states:
77
+ incoming, state.shift_ff = state.shift_ff, incoming
78
+ return tdo
79
+
80
+ def update(self) -> None:
81
+ for state in self._states:
82
+ if state.cell.function in (BsrFunction.CONTROL, BsrFunction.OUTPUT3):
83
+ state.po = state.shift_ff
84
+
85
+ def pin_drive_value(self, port_name: str, *, extest_mode: bool) -> int | str | None:
86
+ """What ``port_name``'s real pin currently reads: the driven ``0``/``1``
87
+ value, or ``"z"`` if tri-stated (its paired control cell's effective
88
+ enable is 0). ``None`` if ``port_name`` isn't an OUTPUT3 port at all.
89
+
90
+ Mirrors ``y = EN ? A : 1'bz`` with both ``A`` (the output3 cell's
91
+ ``pin_out``) and ``EN`` (the control cell's ``pin_out``) independently
92
+ following ``extest_mode ? po : func_in`` — outside EXTEST the control
93
+ cell's ``func_in`` is the fixed constant ``1`` (v1, matching
94
+ ``bsr_insert.py``), so the driver is always enabled in normal mode; under
95
+ EXTEST, whether it's enabled depends on whatever was last shifted into the
96
+ control cell's ``po`` via Update-DR — which starts disabled on reset
97
+ (``safe_value=0``'s whole point), not enabled by default."""
98
+ output_state = None
99
+ control_state = None
100
+ for state in self._states:
101
+ if state.cell.function is BsrFunction.OUTPUT3 and state.cell.port_name == port_name:
102
+ output_state = state
103
+ elif (
104
+ state.cell.function is BsrFunction.CONTROL
105
+ and state.cell.port_name == f"{port_name}_oe"
106
+ ):
107
+ control_state = state
108
+ if output_state is None:
109
+ return None
110
+
111
+ a_value = output_state.po if extest_mode else self._observed_value(output_state.cell)
112
+ en_value = control_state.po if (extest_mode and control_state is not None) else 1
113
+ return a_value if en_value else "z"
warptap/bsr_plan.py ADDED
@@ -0,0 +1,109 @@
1
+ """Pure planning phase for boundary-scan register insertion (implementation_plan.md §7
2
+ Stage 3, §3.1). Walks a target module's top-level ports and produces an ordered list of
3
+ :class:`BsrCell` records — the ``(cell_number, cell_type, port_name, function, safe_value,
4
+ disable_cell_index)`` tuple §3.1 specifies, directly modeled on BSDL's own
5
+ ``BOUNDARY_REGISTER`` attribute. No Yosys involved here; the impure surgery that actually
6
+ inserts cells into a netlist lives in ``bsr_insert.py``.
7
+ """
8
+
9
+ from __future__ import annotations
10
+
11
+ import enum
12
+ from typing import NamedTuple
13
+
14
+ from warptap.netlist import Module
15
+
16
+
17
+ class BsrFunction(enum.Enum):
18
+ INPUT = "input"
19
+ OUTPUT3 = "output3"
20
+ CONTROL = "control"
21
+ INTERNAL = "internal" # reserved for BSDL-schema completeness; v1 never emits this
22
+ CLOCK = "clock" # reserved for BSDL-schema completeness; v1 never emits this
23
+ BIDIR = "bidir"
24
+
25
+
26
+ class BsrCell(NamedTuple):
27
+ cell_number: int
28
+ cell_type: str # "BC_1" | "BC_7" in v1; open string since BC_4/8/9/10 are deferred, not rejected
29
+ port_name: str # a real top-level port name, or f"{port}_oe" for a control cell
30
+ function: BsrFunction
31
+ safe_value: int # 0 or 1
32
+ disable_cell_index: int | None # the paired control cell's cell_number, else None
33
+
34
+
35
+ class BsrPlan(NamedTuple):
36
+ cells: list[BsrCell]
37
+ skipped_ports: list[str] # excluded ports, never silently dropped — always echoed back
38
+
39
+
40
+ def build_bsr_plan(
41
+ module: Module,
42
+ *,
43
+ clock_ports: frozenset[str] = frozenset(),
44
+ excluded_ports: frozenset[str] = frozenset(),
45
+ ) -> BsrPlan:
46
+ """Walk ``module``'s top-level ports (declaration order — see ``Module.ports()``)
47
+ and build the BSR cell list.
48
+
49
+ ``clock_ports``/``excluded_ports`` are explicit and mandatory to opt a port out
50
+ of scanning — Yosys JSON gives no reliable "this is a clock" signal on a plain
51
+ port, so nothing is inferred by name or heuristic (matches the project's
52
+ "document limitations loudly" discipline). An excluded port gets no cell and no
53
+ ``cell_number`` at all: a clock pin never has a shift-register position.
54
+
55
+ Every port is handled by exactly one of: skip, or one of the three direction
56
+ branches below — an unrecognized ``direction`` raises immediately rather than
57
+ silently dropping the port, which is what actually guarantees no port goes
58
+ unaccounted for (an *inline* completeness guarantee, not a separate post-hoc
59
+ check — the latter would be dead code here, since this walk's own control flow
60
+ already can't fall through without either skipping or emitting a cell for every
61
+ port).
62
+
63
+ ``safe_value`` is uniformly 0 in v1: under the mux polarity ``bsr_insert.py``
64
+ wires (``pin_out = extest_mode ? po : func_in``, a control cell's ``pin_out``
65
+ tied directly to its paired tri-state buffer's ``EN``, no inversion), ``po=0``
66
+ on a control cell *is* the value that disables (Z-states) its paired driver —
67
+ so the uniform-0 default is the safe one by construction, not by coincidence
68
+ (see ``tests/test_bsr_plan.py``'s dedicated proof of this equivalence).
69
+
70
+ Control cells are always emitted immediately before the output3/bidir cell they
71
+ gate (``disable_cell_index == cell_number - 1``), matching the convention real
72
+ BSDL files use (confirmed against a live-fetched Lattice ECP5 BSDL file) — not
73
+ an IEEE mandate, a de facto convention worth matching so warptap's own output
74
+ looks normal to any real boundary-scan tool.
75
+ """
76
+ skip = clock_ports | excluded_ports
77
+ cells: list[BsrCell] = []
78
+ skipped: list[str] = []
79
+ cell_number = 0
80
+
81
+ for port in module.ports():
82
+ if port.name in skip:
83
+ skipped.append(port.name)
84
+ continue
85
+
86
+ if port.direction == "input":
87
+ cells.append(BsrCell(cell_number, "BC_1", port.name, BsrFunction.INPUT, 0, None))
88
+ cell_number += 1
89
+ elif port.direction in ("output", "inout"):
90
+ control_number = cell_number
91
+ cells.append(
92
+ BsrCell(
93
+ control_number, "BC_1", f"{port.name}_oe", BsrFunction.CONTROL, 0, None
94
+ )
95
+ )
96
+ cell_number += 1
97
+ driven_type = "BC_1" if port.direction == "output" else "BC_7"
98
+ driven_function = BsrFunction.OUTPUT3 if port.direction == "output" else BsrFunction.BIDIR
99
+ cells.append(
100
+ BsrCell(cell_number, driven_type, port.name, driven_function, 0, control_number)
101
+ )
102
+ cell_number += 1
103
+ else:
104
+ raise ValueError(
105
+ f"port {port.name!r} has unrecognized direction {port.direction!r} "
106
+ "(expected 'input', 'output', or 'inout')"
107
+ )
108
+
109
+ return BsrPlan(cells=cells, skipped_ports=skipped)