Skip to content

ranaumarnadeem/OpenTestability

BranchesTags

Repository files navigation

OpenTestability

Professional Test Point Insertion and Circuit Testability Analysis Tool

A comprehensive open-source framework for automated test point insertion (TPI) and digital circuit testability analysis, featuring advanced testability metrics, reconvergent fanout detection, and design-for-testability (DFT) capabilities.

Documentation

View Full Documentation

Quick Start

Installation

# Clone the repository
git clone https://github.com/ranaumarnadeem/OpenTestability.git
cd OpenTestability

# Set up virtual environment (WSL recommended)
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Place PDK liberty files
# Copy your Sky130 liberty files to data/pdk/ directory
# Default: data/pdk/sky130_tt_1.8_25_nldm.lib

Tool Environment Usage

OpenTestability requires specifying a mode flag (--yosys or --genus) to run:

# Genus Mode - Traditional workflow with full command set
python3 opentest --genus
opentest [genus]> cop -i design.v
opentest [genus]> scoap -i design.v
opentest [genus]> tpi -i netlist.json -m metrics.json -t 50 -n 10
opentest [genus]> help
opentest [genus]> exit

# Yosys Mode - Streamlined workflow for Yosys synthesis outputs
python3 opentest --yosys
opentest [yosys]> cop -i design.v -j
opentest [yosys]> scoap -i design.v
opentest [yosys]> analyze_and_add_tp -i design.json -m metrics.json
opentest [yosys]> help
opentest [yosys]> exit

# View available commands for each mode
python3 opentest --genus
opentest [genus]> help

python3 opentest --yosys
opentest [yosys]> help

Available Commands

Genus Mode Commands

To use Genus mode: python3 opentest --genus

Command Description Usage
tpi Test Point Insertion tpi -i <netlist.json> -m <metrics.json> [-o <output.v>] [-t <threshold>] [-n <max_points>]
cop Calculate COP metrics cop -i <input.v/.txt> [-o <output.txt>] [-r] [-a <algorithm>] [-j]
scoap Calculate SCOAP metrics scoap -i <input.v/.txt> [-o <output.json>] [-r] [-a <algorithm>]
auto-cop COP with auto reconvergence auto-cop -i <input.txt> [-o <output.txt>] [-w <workers>]
auto-scoap SCOAP with auto reconvergence auto-scoap -i <input.txt> [-o <output.json>] [-w <workers>]
parse Parse Verilog netlist parse -i <input.v> [-o <output.json>] [-d <directory>] [-v]
convert Convert text to JSON convert -i <input.txt> [-v]
dag Create DAG from netlist dag -i <input.json> [-o <output.json>] [-r] [-a <algorithm>]
reconv Basic reconvergence detection reconv -i <input.json> [-o <output.json>] [-d <directory>] [-v]
simple Simple reconvergence detection simple -i <input.json> [-o <output.json>] [-d <directory>] [-v]
advanced Advanced reconvergence detection advanced -i <input.json> [-o <output.json>] [-d <directory>] [-v]
compare Compare all algorithms compare -i <input.json> [-v]
test-reconv Run integration tests test-reconv [-v]
visualize Generate circuit visualization visualize -i <input.json> [-o <output.png>] [-d <directory>] [-v]
status Show project status status
help Show help information help [command]

Yosys Mode Commands

To use Yosys mode: python3 opentest --yosys

Command Description Usage
cop Calculate COP metrics cop -i <input.v> [-o <output.json>] [-j]
scoap Calculate SCOAP metrics scoap -i <input.v> [-o <output.json>]
analyze_and_add_tp Complete TPI pipeline analyze_and_add_tp -i <input> -m <metrics.json> [-o <output>] [-t <threshold>] [-n <max_points>]
help Show help information help [command]

PDK Setup

OpenTestability uses PDK liberty files for cell library information during test point insertion and tool integration.

Liberty File Location

Place your PDK liberty files in the data/pdk/ directory:

data/pdk/
└── sky130_tt_1.8_25_nldm.lib  # Default Sky130 liberty file

Supported PDKs

  • Sky130: Standard cell library for test point insertion
  • Custom PDKs: Place your liberty files in data/pdk/ and update configuration

The default liberty file path is data/pdk/sky130_tt_1.8_25_nldm.lib and is used by:

  • Test point insertion for cell selection
  • Tool integration scripts (Fault, OpenROAD, Yosys)
  • Synthesis and ATPG workflows

Primary Features

Test Point Insertion (TPI)

Automated design-for-testability (DFT) implementation:

  • Metrics-Driven: Analyzes COP/SCOAP metrics to identify hard-to-test signals
  • Observation Points: Inserts buffers to expose internal signals as primary outputs
  • Control Points: Inserts muxes to allow external control of signal values during test mode
  • Industry-Standard Output: Generates Verilog-2001 compatible with commercial EDA tools
  • Professional DFT Interface: Clean separation of functional and test interfaces

TPI Workflow

# Genus Mode - Complete TPI workflow
python3 opentest --genus
opentest [genus]> cop -i design.v -j
opentest [genus]> tpi -i design.json -m metrics.json -t 50 -n 10

# Yosys Mode - Streamlined workflow
python3 opentest --yosys
opentest [yosys]> cop -i design.v -j
opentest [yosys]> analyze_and_add_tp -i design.json -m metrics.json -t 50 -n 10

Yosys Mode

Streamlined workflow for Yosys synthesis outputs:

  • Simplified Commands: Core testability commands (cop, scoap)
  • Complete Pipeline: analyze_and_add_tp for end-to-end TPI workflow
  • Direct Integration: Works with Yosys JSON and Verilog formats

Yosys Mode Workflow

# Start Yosys mode
python3 opentest --yosys

# Run testability analysis
opentest [yosys]> cop -i design.v -j
opentest [yosys]> scoap -i design.v

# Complete TPI pipeline
opentest [yosys]> analyze_and_add_tp -i design.json -m metrics.json -t 40 -n 15

TPI Parameters

  • -i, --input: Parsed netlist file (JSON format from parse command)
  • -m, --metrics: Metrics file (COP or SCOAP JSON output)
  • -o, --output: Output Verilog file (default: <input>_tp.v)
  • -t, --threshold: Testability threshold (default: 50) - lower values mean harder to test
  • -n, --max-points: Maximum test points to insert (default: 10)
  • -d, --directory: Output directory (default: data/TPI/)
  • -v, --verbose: Enable verbose output and debugging information

TPI Output

The TPI command generates enhanced Verilog with:

  • Observation Points: Internal signals buffered to new primary outputs (tp_obs_<signal>)
  • Control Points: Muxes for signal override via test enable (tp_ctrl_<signal>, test_en)
  • Gate Overhead: Detailed reporting of added gates and area impact
  • Tool Compatibility: Compatible with Fault, Yosys, OpenROAD, Verilator, and commercial tools

Supporting Analysis Features

Advanced Testability Metrics

Supporting TPI with comprehensive analysis capabilities:

  • Direct Verilog Analysis: Both modes support direct Verilog input
  • Automatic Pipeline: Handles parsing, DAG creation, reconvergence detection, and analysis
  • Smart Parallel: Automatically enables parallel mode for circuits >100,000 gates
  • Custom Output: Supports -o option for custom output filenames
# Genus Mode
python3 opentest --genus
opentest [genus]> cop -i my_design.v
opentest [genus]> scoap -i my_design.v

# Yosys Mode
python3 opentest --yosys
opentest [yosys]> cop -i my_design.v
opentest [yosys]> scoap -i my_design.v

Integrated Reconvergence Detection

Automatic reconvergence handling for accurate testability metrics:

  • Automatic Detection: COP and SCOAP now automatically detect reconvergent fanout
  • Three Algorithms: Basic, Simple (recommended), and Advanced methods
  • Correlation-Aware: Bayesian network-based adjustments for accurate metrics
  • 98% Accuracy: Simple algorithm achieves 98%+ match with baseline methods
from opentestability.core.cop import run_cop

# Automatic reconvergence detection and parallel computation
run_cop('circuit.txt', 'results.txt',
        reconvergence_algorithm='auto',  # Auto-select best algorithm
        auto_parallel=True)              # Parallel for >100k gates

Parallel Computation Enhancement

Automatic parallel processing for large circuits:

  • Automatic Activation: Enabled for circuits >100,000 gates
  • 3-4x Speedup: Significant performance improvement on large designs
  • Thread-Safe: Concurrent processing of reconvergent fanout regions
  • Configurable: Adjustable worker threads (default: 4)

Modular Architecture

The codebase has been reorganized for better maintainability:

  • COP package: Includes parallel computation support
  • SCOAP package: Split into 7 focused modules
  • Reconvergence package: Three algorithm implementations (basic, simple, advanced) with integration module
  • DAG package: Clean separation of DAG construction logic
  • 100% backward compatible: Old import paths still work

Algorithm Details

COP (Combinational Observability Probability)

  • Purpose: Calculate probability-based observability metrics
  • Reconvergence-Aware: Automatic correlation adjustments at fanout reconvergence
  • Parallel Support: Automatic for circuits >100,000 gates
  • Use Case: Probability-based test pattern generation, fault coverage estimation

SCOAP (Sandia Controllability/Observability Analysis Program)

  • Purpose: Calculate controllability and observability metrics
  • Reconvergence-Aware: Integrated fanout point detection and processing
  • Parallel Support: Concurrent processing of reconvergent cones
  • Use Case: Test point insertion, DFT optimization, circuit testability analysis

Simple Reconvergence (Recommended)

  • Accuracy: 98%+ match with baseline methods
  • Performance: Optimized for real-world circuits
  • Use Case: Production applications, general circuit analysis

Advanced Reconvergence

  • Accuracy: Highly selective, research-grade
  • Performance: Best for complex pipelined circuits
  • Use Case: Research, academic analysis, complex VLSI designs

Baseline Reconvergence

  • Accuracy: Traditional approach
  • Performance: Reliable baseline
  • Use Case: Comparison, legacy compatibility

Project Structure

opentestability/
├── src/opentestability/
│   ├── core/                                   # Core analysis algorithms
│   │   ├── scoap/                              # SCOAP testability analysis
│   │   │   ├── main.py                         # Main entry point
│   │   │   ├── netlist_parser.py              # Netlist parsing
│   │   │   ├── gate_logic.py                  # Gate-level computation
│   │   │   ├── controllability.py             # CC0/CC1 algorithms
│   │   │   ├── observability.py               # CO algorithms
│   │   │   ├── parallel.py                    # Parallel computation
│   │   │   └── output.py                      # Result formatting
│   │   ├── dag/                                # DAG construction
│   │   │   └── builder.py                     # DAG builder
│   │   ├── reconvergence/                      # Reconvergence detection
│   │   │   ├── basic.py                       # Baseline BFS algorithm
│   │   │   ├── simple.py                      # Simplified paper algorithm
│   │   │   └── advanced.py                    # Advanced paper algorithm
│   │   └── testpoint/                          # Test Point Insertion
│   │       ├── main.py                        # TPI orchestrator
│   │       ├── analyzer.py                    # Metrics analysis
│   │       ├── designer.py                    # Test point design
│   │       ├── inserter.py                    # Netlist modification
│   │       ├── verilog_writer.py              # Verilog generation
│   │       ├── validator.py                   # Result validation
│   │       └── tech_library.py                # Cell library support
│   ├── parsers/
│   │   ├── verilog_parser.py                   # Verilog parsing
│   │   ├── yosys_parser.py                     # Yosys JSON parsing
│   │   └── yosys_writer.py                     # Yosys JSON generation
│   ├── visualization/
│   │   └── graph_renderer.py                   # Circuit visualization
│   └── utils/
│       ├── file_utils.py                       # File utilities
│       └── user_interaction.py                 # User prompts & format detection
├── data/
│   ├── input/                                  # Input Verilog/Yosys files
│   ├── parsed/                                 # Parsed netlists
│   ├── pdk/                                    # PDK liberty files (place Sky130 .lib files here)
│   ├── temp/
│   │   └── yosys_metadata/                     # Temporary Yosys metadata storage
│   ├── dag_output/                             # DAG representations
│   ├── reconvergence_output/                   # Analysis results
│   └── scoap_output/                           # SCOAP results
├── tests/                                      # Test suite
├── docs/                                       # Documentation
└── examples/                                   # Example circuits

Contributing

We welcome contributions from the open source community!

Documentation Contributions

Important: For documentation changes, always use the docs branch:

git checkout docs
# Make your documentation changes
git commit -m "docs: your changes"
git push origin docs

Development Setup

# Install development dependencies
pip install -r requirements-dev.txt

# Run tests
python -m pytest tests/

# Run linting
flake8 src/
black src/

Adding New Algorithms

  1. Create a new detector class in src/opentestability/core/
  2. Implement the standard interface
  3. Add CLI command in opentestability
  4. Update comparison framework
  5. Add tests and documentation

Documentation

License

This project is licensed under the Apache-2.0 License - see the LICENSE file for details.

Acknowledgments

  • Xu & Edirisuriya (2004): Research paper "A New Way of Detecting Reconvergent Fanout Branch Pairs in Logic Circuits"
  • Open Source Community: Contributors and maintainers
  • Academic Research: VLSI testing and design automation community
  • Zainalabedin Navabi: Digital System Test and Testable Design Using HDL Models and Architectures -Laung-Terng Wang: VLSI Test Principles and Architectures

Support

OpenTestability - Professional Circuit Testability Analysis

About

OpenTestability is an open-source tool for structural analysis of digital circuits, enabling computation of SCOAP metrics, Controllibility Observability Probability (COP), reconvergent path detection, and structural distance measures from gate-level Verilog netlists.

ranaumarnadeem.github.io/OpenTestability/

Topics

open-source distance vlsi cop pyverilog dfts soacp

Resources

Readme

License

Apache-2.0 license

Contributing

Contributing
Activity

Stars

20 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

1 tags

Packages

 
 
 

Contributors

Languages