Quickstart Guide

Get your first coverage gap analysis running in under 10 minutes. This guide assumes you have an existing simulation environment with a coverage database already generated.

1. Install the phnq CLI

The CLI is distributed as a single binary for Linux and macOS. Windows support is via WSL2.

$ curl -sSL https://get.photoniqo.com/cli | sh
✓ phnq v0.9.1 installed to /usr/local/bin/phnq

Verify installation:

$ phnq --version
phnq version 0.9.1 · photoniqo.com

2. Authenticate

Log in with your Photoniq account credentials. Your API key is stored in ~/.phnq/config.toml.

$ phnq auth login
Enter your API key (from photoniqo.com/account): 
phnq_live_••••••••••••••••••••••••
✓ Authenticated as [email protected]
✓ Active project: my-chip-rtl (Explore tier)

3. Run your first analysis

Point the CLI at your UCDB file and RTL source directory. The tool reads coverage bins from the UCDB and indexes your RTL structure for gap analysis.

$ phnq analyze --ucdb ./sim_output/coverage.ucdb --rtl ./rtl/src

Photoniq v0.9.1 · Connecting to analysis engine...
✓ UCDB loaded: 12,847 coverage bins across 34 modules
✓ RTL indexed: 48,213 lines across ./rtl/src/**/*.sv
Running gap analysis...
⚠ 3 critical uncovered regions detected
⚠ 7 moderate-priority gaps found
Generating ranked test recommendations...

✓ Analysis complete in 4.2s
Results → ./phnq-manifest.json (10 recommendations)

4. Read the manifest

The output is a structured JSON file. Each entry in recommendations[] describes a specific test scenario ranked by predicted coverage impact.

$ cat phnq-manifest.json | jq '.recommendations[0]'
{
  "rank": 1,
  "test_scenario": "lsu_buffer_misaligned_access_edge",
  "target_module": "lsu_buffer",
  "confidence": 0.94,
  "coverage_bins_hit": [
    "misaligned_word_rd",
    "misaligned_dword_wr"
  ],
  "suggested_constraints": {
    "addr_alignment": "non_aligned",
    "access_size": ["word", "dword"],
    "bus_state": "active_transaction"
  },
  "rtl_path": "lsu_buffer.sv:147-183"
}

The suggested_constraints object provides concrete stimulus hints your testbench engineer can translate into SystemVerilog constraint blocks. The rtl_path field links directly to the uncovered code region.

VCS export

Export your UCDB from VCS using the -covdb and -covucp switches after simulation completes:

$ vcs ... -cm tgl+line+fsm+cond -cm_dir coverage.vdb
$ urg -dir coverage.vdb -dbname coverage.ucdb

Questa export

Questa writes UCDB natively. After simulation, merge and export:

$ vcover merge -out coverage.ucdb ./sim_run/*.ucdb

Xcelium export

Xcelium uses the IMC coverage management tool. Export to UCDB format for compatibility:

$ imc -load cov_work -execcmd "report -detail -ucdb coverage.ucdb"

UCDB format notes

Photoniq parses UCDB 1.0 and 2.0 schemas. If your simulator writes a proprietary binary format, pass the --format saif flag to use the SAIF parser instead. Minimum recommended coverage instrumentation: toggle + line + FSM state/transition. Functional coverage (covergroups) is parsed but prediction quality depends on how bins are instrumented.

For questions or integration issues, reach us at [email protected] or in the community Slack.