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.
- warptap/__init__.py +107 -0
- warptap/bsr_insert.py +330 -0
- warptap/bsr_model.py +113 -0
- warptap/bsr_plan.py +109 -0
- warptap/cli.py +27 -0
- warptap/errors.py +17 -0
- warptap/faultflow_retarget.py +168 -0
- warptap/icl_emit.py +405 -0
- warptap/icl_import.py +253 -0
- warptap/icl_model.py +117 -0
- warptap/jamplayer_check.py +83 -0
- warptap/netlist.py +235 -0
- warptap/pdl_emit.py +110 -0
- warptap/pdl_history.py +54 -0
- warptap/pdl_interpreter.py +280 -0
- warptap/pdl_verify.py +88 -0
- warptap/pipeline.py +50 -0
- warptap/py.typed +0 -0
- warptap/rtl/bc1_full.v +52 -0
- warptap/rtl/bc1_shift_only.v +30 -0
- warptap/rtl/bc7_bidir.v +47 -0
- warptap/rtl/instrument_write.v +65 -0
- warptap/rtl/sib_cell.v +63 -0
- warptap/rtl/tap_core.v +153 -0
- warptap/sib_insert.py +289 -0
- warptap/sib_layout.py +95 -0
- warptap/sib_model.py +141 -0
- warptap/sib_overshift.py +198 -0
- warptap/sib_plan.py +82 -0
- warptap/sib_retarget.py +61 -0
- warptap/sim_io.py +87 -0
- warptap/stapl_crc16.py +69 -0
- warptap/svf_openocd_check.py +72 -0
- warptap/tap_fsm.py +67 -0
- warptap/tap_ir.py +119 -0
- warptap/tap_ir_play.py +162 -0
- warptap/tap_ir_stapl.py +203 -0
- warptap/tap_ir_stil.py +291 -0
- warptap/tap_ir_svf.py +92 -0
- warptap/tap_model.py +214 -0
- warptap/tap_ports.py +28 -0
- warptap/yosys_io.py +146 -0
- warptap-0.0.1.dist-info/METADATA +103 -0
- warptap-0.0.1.dist-info/RECORD +48 -0
- warptap-0.0.1.dist-info/WHEEL +5 -0
- warptap-0.0.1.dist-info/entry_points.txt +2 -0
- warptap-0.0.1.dist-info/licenses/LICENSE +201 -0
- 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)
|