Metadata-Version: 2.4
Name: warptap
Version: 0.0.5
Summary: Insert IEEE 1149.1 (JTAG/TAP) and IEEE 1687 (IJTAG/ICL+PDL) test-access infrastructure into a design
Author-email: Rana Umar Nadeem <rana.umar.nadeem21@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/ranaumarnadeem/warptap
Project-URL: Documentation, https://ranaumarnadeem.github.io/warptap/
Project-URL: Repository, https://github.com/ranaumarnadeem/warptap
Project-URL: Changelog, https://github.com/ranaumarnadeem/warptap/blob/main/CHANGELOG.md
Keywords: jtag,ijtag,boundary-scan,ieee-1149.1,ieee-1687,icl,pdl,dft,test-access,svf,stapl,stil,design-for-test,tap-controller,eda,verilog,open-source-hardware
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: System :: Hardware
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: yowasp-yosys; extra == "dev"
Requires-Dist: antlr4-python3-runtime==4.7.2; extra == "dev"
Requires-Dist: z3-solver; extra == "dev"
Requires-Dist: sympy; extra == "dev"
Requires-Dist: networkx; extra == "dev"
Requires-Dist: Semi-ATE-STIL==0.3.2; extra == "dev"
Requires-Dist: lark; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.6; extra == "docs"
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Requires-Dist: mkdocstrings[python]>=1.0; extra == "docs"
Dynamic: license-file

# warptap

[![PyPI](https://img.shields.io/pypi/v/warptap)](https://pypi.org/project/warptap/)
[![Docs](https://img.shields.io/badge/docs-github%20pages-2ea44f)](https://ranaumarnadeem.github.io/warptap/)
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)

**warptap is an open-source Python library that inserts IEEE 1149.1 (JTAG/TAP) and IEEE 1687 (IJTAG) test-access networks into RTL before synthesis, emits ICL and PDL, and generates SVF, STAPL and STIL patterns to drive them.**

Design-for-test (DFT) instruments such as MBIST controllers, scan compression and on-chip monitors need a standard access path from the chip pins. Commercial flows (Tessent IJTAG, Modus) do this; warptap does it in open source. You describe which control and status signals need access, warptap inserts a TAP controller, Segment Insertion Bits (SIBs) and Test Data Registers, returns synthesizable Verilog, and gives you an Instrument Connectivity Language (ICL) model plus a Procedural Description Language (PDL) interpreter to read and write those signals.

- Documentation: https://ranaumarnadeem.github.io/warptap/
- PyPI: `pip install warptap`
- Status: alpha (0.0.x). APIs may change between releases.

## Features

- TAP controller and instruction register insertion (IEEE 1149.1), with a configurable IDCODE
  and an optional dedicated IJTAG access instruction (`ijtag_access_opcode`)
- IJTAG network insertion with SIBs and TDRs (IEEE 1687), including nested SIBs, multi-arm ScanMux and named sub-field addressing
- Boundary-scan register insertion, as an alternative to the IJTAG network (a design gets one or the other)
- ICL emission, and import of networks in warptap's own ICL shape
- TAP-only BSDL emission, matching the instruction the ICL `AccessLink` names
- PDL emission, import and an in-Python PDL interpreter
- Pattern output: SVF, STAPL (with CRC16) and STIL
- TAP and IJTAG network-integrity test programs, with the TDO they expect
- Retargeting of faultflow scan patterns, including compressed and compacted scan
- Pre-synthesis RTL insertion, so the result goes through your normal synthesis flow

## Install

```bash
pip install warptap
```

Needs a real `yosys` on `PATH` (shelled out to, never bundled).

warptap is a Python library. A `warptap` CLI entry point exists but is not stable yet: today
it only prints its version and help, with no subcommands.

## Part of an open-source DFT toolchain

| Tool | What it does |
|---|---|
| [faultflow](https://github.com/ranaumarnadeem/faultflow) | ATPG and fault simulation for Yosys gate-level netlists |
| [OpenTestability](https://github.com/ranaumarnadeem/OpenTestability) | SCOAP/COP testability analysis and test point insertion |
| [autoMBIST](https://github.com/ranaumarnadeem/autoMBIST) | MBIST, BIRA and BISR generation for OpenRAM memories |
| **warptap** | JTAG/IJTAG test-access insertion, ICL and PDL |

warptap is the access layer: autoMBIST's MBIST controllers become instruments on a
warptap-inserted IJTAG network, and faultflow's scan patterns, compressed and compacted ones
included, are retargeted through it.

## FAQ

**Is there an open-source alternative to Tessent IJTAG?**
warptap covers IJTAG network insertion, ICL and PDL generation, and PDL execution for open flows,
for the networks it inserts itself. It is not a general IEEE 1687 tool: ICL import recognizes
only warptap's own network shape, and it does not retarget PDL across arbitrary third-party ICL
hierarchies.

**Can I use warptap with Yosys and OpenROAD / LibreLane?**
warptap runs Yosys itself and returns plain Verilog, which you synthesize like any other source,
so it fits a Yosys-based flow. The test suite synthesizes the inserted Verilog with Yosys; it
does not run OpenROAD or LibreLane.

**Which pattern formats can it produce for a tester?**
SVF, STAPL and STIL. It also writes a TAP-only BSDL file describing the TAP it inserts.

**Does it work on gate-level netlists?**
Yes, if Yosys can read the netlist: give it interface-only (`(* blackbox *)`) declarations for the
library cells. The test suite inserts a network into a sky130 gate-level netlist this way. The
TAP, SIBs and instrument registers warptap adds are generic logic, not mapped to your cell
library, so the result still needs synthesis or technology mapping.

## Development

Requires a real `yosys` on `PATH` (this project shells out to it, the same way faultflow does
for its own Yosys usage; it is never bundled). On Windows, run everything through WSL; system `pip`
there is externally-managed (PEP 668), so install into a local venv:

```bash
git clone --recurse-submodules https://github.com/ranaumarnadeem/warptap.git
cd warptap
python3 -m venv .venv && ./.venv/bin/pip install -e '.[dev]'
./.venv/bin/python -m pytest
```

`third_party/icl_parser` is a git submodule (an ICL/PDL parser the grammar and import tests run
against). In an existing clone, and in every `git worktree`, run
`git submodule update --init third_party/icl_parser` first. The `dev` extra installs its Python
dependencies (`antlr4-python3-runtime==4.7.2`, `z3-solver`, `sympy`, `networkx`). Without the
submodule or those packages the parser tests fail with that instruction;
`WARPTAP_ALLOW_MISSING_ICL_PARSER=1` makes them skip instead.

If a real `yosys` isn't available at all, `WARPTAP_YOSYS_CMD` can point at any
Yosys-compatible executable, and `tests/conftest.py` falls back to a pip-installed
`yowasp-yosys` (WASM build, see the `dev` extra) if nothing is found on `PATH`.

Some tests also cross-simulate hand-authored RTL against its Python behavioral-model
counterpart using Icarus Verilog (`iverilog`/`vvp`, already present in the documented WSL
environment). There's no WASM fallback for these: if neither is on `PATH` nor pointed at via
`WARPTAP_IVERILOG_CMD`/`WARPTAP_VVP_CMD`, those tests skip cleanly rather than failing.
