OpenTestability / Command Reference
View on GitHub

Command Reference

Complete reference for all OpenTestability commands.

Command Syntax

opentest> <command> -i <input> [-o <output>] [-d <directory>] [-v]

Commands Overview

Command Purpose Input Output
cop COP probability metrics .v or .txt .txt + .json
scoap SCOAP metrics .v or .txt .json
tpi Test Point Insertion .json + metrics .v file
auto-cop COP with auto reconvergence .txt parsed .txt + .json
auto-scoap SCOAP with auto reconvergence .txt parsed .json
parse Parse Verilog netlist .v file .txt + .json
convert Convert text to JSON .txt file .json
dag Create DAG .json parsed .json DAG
reconv Basic reconvergence .json DAG .json results
simple Simple reconvergence .json DAG .json results
advanced Advanced reconvergence .json DAG .json results
compare Compare algorithms .json DAG .json comparison
test-reconv Run integration tests - Test results
visualize Generate graph .json DAG .png image
status Show project status - -
help Show help - -
exit Exit tool - -

cop

Calculate COP (Controllability Observability Program) testability metrics with automatic reconvergence detection.

Syntax

cop -i <input.v/.txt> [-o <output.txt>] [-d <directory>] [-v] [-j] [-r] [-a <algorithm>]

Parameters

NEW in v1.0.1: Verilog Auto-Pipeline

When input is a .v file, automatically:

  1. Parses Verilog to netlist
  2. Creates DAG
  3. Detects reconvergence (simple algorithm by default)
  4. Runs COP analysis with reconvergence-aware metrics
  5. Enables parallel computation if circuit >100,000 gates
  6. Outputs to data/results/ directory

Examples

Verilog Auto-Pipeline (Recommended):

opentest> cop -i priority_encoder.v
[INFO] Verilog auto-pipeline mode
[INFO] Parsing Verilog file...
[INFO] Creating DAG...
[INFO] Detecting reconvergence (simple algorithm)...
[INFO] Reconvergent sites: 13
[INFO] Circuit size: 17 gates
[INFO] Running COP analysis...
[✓] Results: /path/to/data/results/priority_encoder_cop.txt
[✓] JSON: /path/to/data/results/priority_encoder_cop.json

opentest> cop -i design.v -o custom_name.txt

Traditional Workflow (Parsed Files):

opentest> cop -i circuit.txt
[INFO] Automatic reconvergence detection enabled
[✓] COP analysis completed

opentest> cop -i circuit.txt -r -a advanced -j
[INFO] Using advanced reconvergence algorithm
[✓] COP completed with JSON output

Output Metrics

For each signal:

Output Format

Text Format (.txt):

Signal    C1      Obs     COP
------    ----    ----    ----
input_a   0.500   0.750   0.375
wire_n1   0.250   0.500   0.125
output_z  0.125   1.000   0.125

JSON Format (.json):

{
  "signal_name": {
    "C1": 0.500,
    "Obs": 0.750,
    "COP": 0.375
  }
}

tpi

Test Point Insertion (TPI) - Automated insertion of observation and control points to improve circuit testability.

Syntax

tpi -i <netlist.json> -m <metrics.json> [-o <output.v>] [-d <directory>] [-t <threshold>] [-n <max_points>] [-v]

Parameters

Prerequisites

TPI requires testability metrics from COP or SCOAP analysis. Run one of these first:

# Generate COP metrics (recommended for TPI)
opentest cop -i design.v -j
# OR generate SCOAP metrics
opentest scoap -i design.v

How It Works

  1. Metrics Analysis: Analyzes COP/SCOAP metrics to identify signals with poor testability
  2. Signal Selection: Ranks signals by testability metrics and selects candidates below threshold
  3. Test Point Design: Determines optimal observation and control point locations
  4. Netlist Modification: Inserts test points while maintaining circuit functionality
  5. Verilog Generation: Outputs enhanced Verilog with test infrastructure

Test Point Types

Examples

Basic TPI with COP metrics:

# Step 1: Generate metrics
opentest> cop -i priority_encoder.v -j
[✓] COP analysis completed: /path/to/priority_encoder_cop.json

# Step 2: Insert test points
opentest> tpi -i data/parsed/priority_encoder.json -m data/results/priority_encoder_cop.json
[i] Running Test Point Insertion
============================================================
Test Point Insertion Results
============================================================
  Design: priority_encoder
  Test points inserted: 3
    - Observation: 2
    - Control: 1
  Gate overhead: 4.2%
  Output: /path/to/data/TPI/priority_encoder_tp.v
============================================================
[+] TPI completed successfully

TPI with custom parameters:

opentest> tpi -i data/parsed/serial_ALU.json -m data/results/serial_ALU_scoap.json -t 30 -n 15 -v
[i] Running Test Point Insertion
Netlist: data/parsed/serial_ALU.json
Metrics: data/results/serial_ALU_scoap.json
Output: data/TPI/serial_ALU_tp.v
Threshold: 30
Max points: 15

[DEBUG] Analyzing 72 signals...
[DEBUG] Found 8 candidates below threshold 30
[DEBUG] Selecting 8 test points (within max limit of 15)
[DEBUG] Observation points: 5
[DEBUG] Control points: 3
[DEBUG] Inserting test infrastructure...
[+] TPI completed successfully

Custom output and directory:

opentest> tpi -i netlist.json -m metrics.json -o enhanced_design.v -d output/testable/
[✓] Test points inserted: output/testable/enhanced_design.v

Output Format

The TPI command generates enhanced Verilog with:

Observation Points (expose internal signals):

// Original signal: wire internal_sig;
// Added observation point:
output tp_obs_internal_sig;
buf obs_buf_1 (tp_obs_internal_sig, internal_sig);

Control Points (allow signal override):

// Original signal: wire control_sig;
// Added control point:
input tp_ctrl_control_sig;
input test_en;
wire control_sig_controlled;
mux2 ctrl_mux_1 (control_sig_controlled, control_sig, tp_ctrl_control_sig, test_en);

Complete Example Output:

module priority_encoder_tp(
    // Original ports
    input [3:0] data_in,
    output [1:0] data_out,
    output valid,
    
    // Added observation points
    output tp_obs_n1,
    output tp_obs_n3,
    
    // Added control points
    input tp_ctrl_n2,
    input test_en
);

// Original circuit with test points inserted
wire n1, n2_controlled, n3;
// ... rest of circuit with test infrastructure
endmodule

Metrics Compatibility

TPI works with both COP and SCOAP metrics:

COP Metrics (Probability-based):

SCOAP Metrics (Complexity-based):

Performance and Overhead

Integration with Tools

Generated Verilog is compatible with:

Best Practices

  1. Use COP metrics for general testability improvement
  2. Start with low max-points (5-10) to minimize overhead
  3. Adjust threshold based on metric distribution in your design
  4. Enable verbose mode for debugging and analysis
  5. Validate output with simulation before synthesis

parse

Parse gate-level Verilog netlists from synthesis tools.

Syntax

parse -i <input.v> [-o <output.txt>] [-d <directory>] [-v]

Parameters

Output

Creates two files:

  1. Text format (.txt): Human-readable gate list
  2. JSON format (.json): Machine-readable structured data

Example

opentest> parse -i serial_ALU.v
[✓] Parsed serial_ALU.v -> /path/to/serial_alu_parsed.txt

opentest> parse -i priority_encoder.v -o custom_name.txt -v

Input Format

Expects synthesized gate-level Verilog with standard cell instances:

module my_circuit(input a, b, output z);
  wire n1;
  AND2X1 gate1(.A(a), .B(b), .Y(n1));
  INVX1 gate2(.A(n1), .Y(z));
endmodule

convert

Convert text-based parsed netlists to JSON format.

Syntax

convert -i <input.txt> [-v]

Parameters

Example

opentest> convert -i serial_alu.txt
[✓] Converted to JSON: /path/to/serial_alu.json

Use Case

If you have old text-format netlists or manually created gate lists, convert them to JSON for DAG creation.

dag

Create Directed Acyclic Graph representation from parsed netlists.

Syntax

dag -i <input.json> [-v]

Parameters

Output

Creates DAG JSON file in data/dag_output/ with:

Example

opentest> dag -i priority_enc_parsed.json
[✓] DAG saved to /path/to/priority_enc_dag.json

Sequential Circuit Handling

For circuits with flip-flops:

scoap

Calculate SCOAP (Sandia Controllability Observability Analysis Program) testability metrics with automatic reconvergence detection.

Syntax

scoap -i <input.v/.txt> [-o <output.json>] [-d <directory>] [-v] [-r] [-a <algorithm>]

Parameters

NEW in v1.0.1: Verilog Auto-Pipeline

When input is a .v file, automatically:

  1. Parses Verilog to netlist
  2. Creates DAG
  3. Detects reconvergence and extracts fanout points
  4. Runs SCOAP analysis with reconvergence-aware metrics
  5. Enables parallel computation if circuit >100,000 gates
  6. Outputs to data/results/ directory

Examples

Verilog Auto-Pipeline (Recommended):

opentest> scoap -i serial_ALU.v
[INFO] Verilog auto-pipeline mode
[INFO] Parsing Verilog file...
[INFO] Creating DAG...
[INFO] Detecting reconvergence...
[INFO] Fanout points extracted: 12
[INFO] Circuit size: 72 gates
[INFO] Running SCOAP analysis...
[✓] Results: /path/to/data/results/serial_ALU_scoap.json

opentest> scoap -i design.v -o my_scoap.json

Traditional Workflow (Parsed Files):

opentest> scoap -i serial_alu.txt
[INFO] Automatic reconvergence detection enabled
[✓] SCOAP analysis completed: /path/to/scoap_results.json

opentest> scoap -i circuit.txt -r -a simple
[INFO] Using simple reconvergence algorithm
[✓] SCOAP completed

Output Metrics

For each signal:

Lower values = easier to control/observe = better testability

Output Format

{
  "signal_name": {
    "CC0": 5,
    "CC1": 3,
    "CO": 2
  }
}

reconv

Basic reconvergent fanout detection algorithm.

Syntax

reconv -i <input.json> [-o <output.json>] [-d <directory>] [-v]

Parameters

What It Does

Detects reconvergent fanout points where a signal splits and reconverges, which can affect:

Example

opentest> reconv -i priority_enc_dag.json
[✓] Reconvergence analysis completed: /path/to/priority_enc_reconv.json

simple

Simple reconvergence detection algorithm with enhanced analysis.

Syntax

simple -i <input.json> [-o <output.json>] [-d <directory>] [-v]

Parameters

Same as reconv command.

Differences from reconv

Example

opentest> simple -i serial_alu_dag.json
[✓] Simple reconvergence analysis completed

advanced

Advanced reconvergence detection with comprehensive metrics.

Syntax

advanced -i <input.json> [-o <output.json>] [-d <directory>] [-v]

Parameters

Same as reconv command.

Features

Example

opentest> advanced -i priority_enc_dag.json
[✓] Advanced reconvergence analysis completed

compare

Compare all three reconvergence algorithms on the same circuit.

Syntax

compare -i <input.json> [-v]

Parameters

Output

Runs all three algorithms and creates a comparison report showing:

Example

opentest> compare -i serial_alu_dag.json

Comparison Summary:
  Baseline: 15 reconvergences
  Simple:   18 reconvergences
  Advanced: 22 reconvergences

[✓] Comparison saved to: /path/to/serial_alu_comparison.json

auto-cop

Run COP analysis with automatic reconvergence detection and parallel computation (NEW in v1.0.1).

Syntax

auto-cop -i <input.txt> [-o <output.txt>] [-w <workers>] [-v]

Parameters

Features

Example

opentest> auto-cop -i priority_enc.txt
[INFO] Auto-COP mode
[INFO] Creating DAG...
[INFO] Detecting reconvergence...
[INFO] Reconvergent sites: 13
[INFO] Circuit: 17 gates (sequential mode)
[✓] COP completed: /path/to/results/priority_enc_cop.txt

opentest> auto-cop -i large_circuit.txt -w 8
[INFO] Circuit: 250,000 gates (parallel mode activated)
[INFO] Workers: 8
[✓] COP completed with 3.8x speedup

auto-scoap

Run SCOAP analysis with automatic reconvergence detection and parallel computation (NEW in v1.0.1).

Syntax

auto-scoap -i <input.txt> [-o <output.json>] [-w <workers>] [-v]

Parameters

Features

Example

opentest> auto-scoap -i serial_alu.txt
[INFO] Auto-SCOAP mode
[INFO] Creating DAG...
[INFO] Detecting reconvergence...
[INFO] Fanout points: 12
[INFO] Circuit: 72 gates (sequential mode)
[✓] SCOAP completed: /path/to/results/serial_alu_scoap.json

opentest> auto-scoap -i large_circuit.txt -w 8
[INFO] Circuit: 180,000 gates (parallel mode activated)
[INFO] Processing 24 reconvergent cones
[✓] SCOAP completed with 3.6x speedup

test-reconv

Run comprehensive integration test suite for reconvergence features (NEW in v1.0.1).

Syntax

test-reconv [-v]

Parameters

What It Tests

Example

opentest> test-reconv
[1/6] Testing COP integration...                ✓ PASS
[2/6] Testing SCOAP integration...              ✓ PASS
[3/6] Testing simple reconvergence...           ✓ PASS
[4/6] Testing advanced reconvergence...         ✓ PASS
[5/6] Testing parallel computation...           ✓ PASS
[6/6] Testing algorithm comparison...           ✓ PASS

All tests passed!

opentest> test-reconv -v
[Detailed test output with circuit information]

visualize

Generate circuit graph visualization using Graphviz.

Syntax

visualize -i <input.json> [-o <output.png>] [-v]

Parameters

Output

PNG image showing:

Example

opentest> visualize -i priority_enc_dag.json
[✓] Graph visualization saved to /path/to/priority_enc_graph.png

Customization

For custom styling, use the Python API directly with render_graph_with_custom_style().

status

Show current project status and file counts.

Syntax

status

Output

Displays:

Example

opentest> status

Project Status:
  Input: 3 files
  Parsed: 6 files
  DAG: 2 files
  Results: 4 files

help

Display help information.

Syntax

help [command]

Parameters

Examples

opentest> help
# Shows all available commands

opentest> help parse
# Shows detailed help for parse command

opentest> help scoap
# Shows detailed help for scoap command

exit

Exit the OpenTestability tool environment.

Syntax

exit

Example

opentest> exit
Exiting OpenTestability...

Alternatively, use Ctrl+D (Linux/macOS) or Ctrl+Z then Enter (Windows).

Tips & Best Practices

# Simplest workflow - one command!
cop -i design.v          # Automatic: Parse → DAG → Reconv → COP
scoap -i design.v        # Automatic: Parse → DAG → Reconv → SCOAP

# With custom output
cop -i design.v -o my_results.txt
scoap -i design.v -o my_results.json

NEW: Complete TPI (Test Point Insertion) Workflow

# Full TPI workflow - metrics to enhanced Verilog
cop -i design.v -j          # Step 1: Generate COP metrics in JSON
tpi -i data/parsed/design.json -m data/results/design_cop.json  # Step 2: Insert test points

# Alternative with SCOAP metrics
scoap -i design.v           # Step 1: Generate SCOAP metrics
tpi -i data/parsed/design.json -m data/results/design_scoap.json  # Step 2: Insert test points

# TPI with custom parameters
tpi -i netlist.json -m metrics.json -t 30 -n 15 -o enhanced.v

Traditional Step-by-Step Workflow

# When you need fine-grained control
parse -i circuit.v          # Step 1: Parse
dag -i circuit_parsed.json  # Step 2: Create DAG
cop -i circuit.txt          # Step 3: COP (auto-reconvergence)
scoap -i circuit.txt        # Step 3: SCOAP (auto-reconvergence)
reconv -i circuit_dag.json  # Step 4: Analysis
visualize -i circuit_dag.json  # Step 5: Visualize

Auto Commands with Reconvergence

# Explicit reconvergence integration
auto-cop -i circuit.txt -w 4
auto-scoap -i circuit.txt -w 8

Verbose Mode

Use -v flag when debugging or learning:

opentest> cop -i circuit.v -v
opentest> auto-scoap -i circuit.txt -v

Batch Processing

Exit tool mode and use direct command execution:

./opentest cop -i circuit1.v -j
./opentest cop -i circuit2.v -j
./opentest scoap -i circuit1.v
./opentest scoap -i circuit2.v

# Batch TPI processing
./opentest tpi -i data/parsed/circuit1.json -m data/results/circuit1_cop.json
./opentest tpi -i data/parsed/circuit2.json -m data/results/circuit2_cop.json

Performance Tips

Additional Resources