Jacquard Documentation

Welcome to the documentation for Jacquard, a GPU-accelerated RTL logic simulator.

Use the sidebar to navigate between topics, or start with the Getting Started guide.

Documents

Project Scope & Planning

Start here if you're considering a feature contribution or want to understand Jacquard's overall direction.

  • Project Scope & Guarantees: Top-level contract — what Jacquard is for, what it isn't, licensing and architecture constraints, stability tiers.
  • Why Jacquard: Honest positioning vs. STA tools and event-driven simulators; what's unique, what isn't, and what output interface would let users extract the value.
  • Timing Correctness: Scoped requirements for timing accuracy, validation, and the forthcoming timing IR.
  • Timing Model Extensions: Pre-spike design notes for δ(T) dynamic delay, clock-tree skew, and wire delay at scale. Formalised in ADR 0007.
  • Post-Phase-0 Roadmap: Sequencing of Phase 1+ work covering structured timing output (ADR 0008) and timing model fidelity (ADR 0007). (OpenTimer integration was originally Phase 1's centrepiece; ADR 0003 was Superseded by the spike — OpenSTA out of process is now the sole STA path per ADR 0001.)
  • Architecture Decision Records: Design decisions and their rationale (numbered, per-decision). See the index for status and how the ADRs relate.
  • Implementation Plans: Phased implementation plans with entry and exit criteria. See the index for status and reading order.
  • Spikes: Time-boxed experiments and their outcomes.

Core Documentation

  • Simulation Architecture: Detailed explanation of Jacquard's internal architecture

    • Pipeline stages (NetlistDB → AIG → StagedAIG → Partitions → FlattenedScript → GPU)
    • Data structures and representations
    • VCD input/output format requirements
    • Assertion and display support infrastructure
    • Performance characteristics
    • Known issues and limitations

  • Timing Simulation: CPU-based timing simulation with Liberty/SDF delays

  • Timing Violations: GPU-side setup/hold violation detection

Troubleshooting Guides

  • Troubleshooting VCD: Debugging VCD input issues
    • VCD hierarchy requirements
    • Signal naming and matching
    • Solutions for flat VCD generation
    • Diagnostic checklist
    • Working examples

Quick Reference

VCD Input Requirements (Critical!)

Jacquard expects VCD signals at absolute top-level (no module hierarchy):

// ✓ Correct testbench
initial begin
    $dumpfile("output.vcd");
    $dumpvars(1, clk, reset, din, dout);  // Depth 1, explicit signals
end

// ✗ Incorrect testbench
initial begin
    $dumpfile("output.vcd");
    $dumpvars(0, testbench);  // Dumps entire hierarchy
end

Debug Commands

# Enable debug logging
RUST_LOG=debug cargo run -r --features metal --bin jacquard -- sim <args>

# Verify with CPU simulation
cargo run -r --features metal --bin jacquard -- sim <args> --check-with-cpu

# Check VCD structure
grep '\$scope\|\$var' input.vcd | head -20

Key Statistics

When running Jacquard, look for these diagnostic outputs:

netlist has X pins, Y aig pins, Z and gates        # AIG complexity
current: N endpoints, try M parts                  # Partition count
Built script for B blocks, reg/io state size S     # Final script
WARN (GATESIM_VCDI_MISSING_PI) ...                 # VCD issues!

Investigation Methodology

This documentation was created through systematic investigation of Jacquard's behavior:

  1. Source Code Analysis: Examined src/aig.rs, src/flatten.rs, src/staging.rs
  2. Debug Tracing: Used RUST_LOG=debug to capture internal state
  3. Test Case Development: Created minimal reproducible examples
  4. Comparative Testing: Compared Jacquard vs iverilog outputs
  5. Third-Party Validation: Tested with real-world examples (sva-playground)

Known Issues Documented

  1. VCD Hierarchy Mismatch (CRITICAL):

    • Jacquard expects flat VCD hierarchy
    • Most testbenches generate hierarchical VCDs
    • See troubleshooting-vcd.md for solutions

  2. Complex FSM Simulation:

    • Some FSM designs don't simulate correctly
    • Under investigation (safe.v example in third_party tests)
    • May be related to synthesis optimization or reset handling

  3. Format String Preservation:

    • Yosys may not preserve format attributes
    • Display messages show placeholders
    • Extract format strings from pre-synthesis JSON as workaround

Contributing

When adding documentation:

  1. Be specific: Include actual commands, file paths, code snippets
  2. Show examples: Both working and non-working cases
  3. Link related docs: Cross-reference other documentation files
  4. Date updates: Update version and date at bottom of documents
  5. Test instructions: Verify all commands actually work

Future Documentation Needs

  • Performance tuning guide (optimal NUM_BLOCKS, --level-split)
  • Memory (SRAM) modeling and synthesis
  • Custom cell library support beyond AIGPDK
  • Multi-clock domain handling
  • VCD scope option detailed behavior
  • GPU kernel optimization internals
  • Main README: ../README.md - Project overview and quick start
  • CLAUDE.md: ../CLAUDE.md - Development guidelines and architecture overview
  • Test Suite: ../tests/ - Examples and regression tests
  • Third-Party Tests: ../tests/regression/third_party/ - Real-world examples with attribution

Last Updated: 2026-02-16 Maintained By: ChipFlow + Community Contributions