Getting Started

Welcome to ConstraintForge, the next-generation pre-synthesis structural linter and diagnostic engine. ConstraintForge operates purely on structural logic depth via an in-memory Abstract Syntax Tree (AST). It bypasses physical placement and routing overhead to give you setup-time and CDC alerts in milliseconds.

Why ConstraintForge?

Latency

Bypasses physical placement and routing overhead. Execution in milliseconds.

Complexity

Topological DFS algorithm guarantees O(|V|+|E|) time complexity.

CDC Detection

Infers clock domains automatically and flags unsafe crossings before synthesis.

Fanout Rules

Monitors high-fanout nets globally with configurable thresholds for structural compliance.

Installation

Pull the engine and initialize the local environment. ConstraintForge relies on headless Yosys to extract the AST.

1. System Dependencies

brew install yosys

ConstraintForge relies on headless Yosys to extract the AST. Use apt-get install yosys for Linux.

2. Install via PIP

pip install constraintforge

Installs the ConstraintForge engine globally. You can now use the constraintforge command from any directory.

Execution & Diagnostics

Run the engine against your RTL. Unlike standard STA tools that require full physical routing constraints, ConstraintForge infers the exact mathematical logic depth directly from the Verilog source code.

AST Extraction

Headless Yosys

DAG Generation

Python Engine

Topological DFS

O(|V|+|E|) Math

constraintforge picorv32.v --top picorv32

[file.v] : The path to the target Verilog or SystemVerilog file.
--top <name> : Specifies the top-level module to extract the DAG from.
Enterprise / CI Flags:
--depth-threshold <int> : Configure maximum allowable logic depth (default: 30).
--fanout-threshold <int> : Configure maximum allowable fanout (default: 100).
--exceptions <file.json> : Suppress intentional false paths and safe CDCs to eliminate noise.
--explain : Print the exact node-by-node path trace for identified setup violations.
--sarif : Output native SARIF format to integrate directly into GitHub Code Scanning.

Note: ConstraintForge acts as a strict CI gate. It will return exit(1) if any violation exceeds your configured thresholds, and exit(0) if the structure is clean.

Understanding the Output

When the analysis finishes, the engine provides exact back-annotated source code line numbers for three critical failure modes:

Setup-Time Risk

Flags combinational paths exceeding your threshold (e.g., >30 gates). Identifies the exact Source DFF and Sink DFF causing the bottleneck.

CDC Violation

Automatically maps clock domains. If a signal crosses from clk_rx to clk_sys without a 2FF synchronizer, the engine throws a metastability alert.

High Fanout

Identifies nets driving extreme loads (e.g., >100 gates) which cause heavy routing delays, signaling where buffer trees need to be inserted.