Manage chip verification regression runs using the simforge CLI tool. Use this skill whenever the user wants to submit, monitor, cancel, or analyze regression runs, wants to run simulation testcases in parallel, needs to merge coverage data from multiple simulation runs, asks about testplan YAML, tag-based case filtering, regression status, or failed case analysis — even if they don't explicitly say "simforge".
A lightweight CLI tool for managing simulation regressions asynchronously. Each project directory runs a background daemon that schedules and tracks simulation cases. Invoke it via shell commands — no SDK, no Python import.
submit → status → results → merge-cov → close
simforge submit — filter testplan by tags, dispatch all cases asyncsimforge status — poll progress (pending / running / passed / failed)simforge results — get per-case detailed resultssimforge merge-cov — merge coverage databases after run completessimforge close — shutdown the daemon when doneThe daemon auto-launches on first submit. It auto-shuts down after 3600s idle.
simforge operates relative to a project directory — the root of a DV project.
By default it uses the current working directory (CWD) as the project dir.
Always cd into the project root before running commands, or pass --project-dir <path> explicitly.
cd /proj/dv/my_ip # project root
simforge submit --tags smoke
Or from anywhere:
simforge submit --project-dir /proj/dv/my_ip --tags smoke
The daemon is per-project-dir: each unique directory gets its own daemon process. Multiple engineers can run separate daemons for different projects on the same machine.
<project_root>/ ← run simforge from here (or --project-dir)
├── cases/
│ └── testplan.yaml ← REQUIRED: defines all simulation cases
├── regress.cfg.yaml ← optional: parallel count, backend, run_dir
└── runs/ ← auto-created by simforge on first submit
└── 20240101_001/ ← one dir per run_id
├── config_snapshot.json
├── final_status.json ← written when run ends (completed/cancelled/error)
├── tc_smoke_1/
│ ├── run.sh
│ └── sim.log
└── tc_smoke_2/
├── run.sh
└── sim.log
| File | Required | Notes |
|---|---|---|
cases/testplan.yaml | Yes | Must exist before submit. Use --testplan to point to a different path |
regress.cfg.yaml | No | Place in project root; overrides defaults for backend/parallelism |
<project_root>/cases/testplan.yamlsimforge submit --testplan path/to/other.yaml (relative to project root)simforge list<project_root>/runs/ (controlled by run_dir in regress.cfg.yaml)run_id (YYYYMMDD_NNN)<run_dir>/<run_id>/<case_name>/<run_dir>/<run_id>/<case_name>/sim.log<run_dir>/<run_id>/<case_name>/coverage.vdbmerge-cov: <run_dir>/<run_id>/merged_cov/simforge stores daemon registry and auth tokens in ~/.simforge/:
~/.simforge/
├── registry.json ← tracks all running daemons (host, port, pid)
├── remote/
│ ├── s-<user>-<id>.token ← per-daemon auth token (chmod 600)
│ └── s-<user>-<id>.ready ← port/pid info written at startup
└── logs/
└── s-<user>-<id>.log ← daemon log
This directory is managed automatically — no manual setup needed.
Submit all matching cases from the testplan for async execution.
simforge submit [options]
| Parameter | Default | Description |
|---|---|---|
--testplan <path> | cases/testplan.yaml | Testplan file path (relative to project dir) |
--tags <t1,t2> | all | Include only cases with ALL listed tags |
--exclude-tags <t1,t2> | none | Exclude cases with ANY listed tag |
-j <n> | 4 | Max parallel simulation jobs |
--backend <local|lsf> | local | Job scheduler backend |
--seed <n|random> | random | Global simulation seed |
--timeout <sec> | from testplan | Override per-case timeout |
--project-dir <dir> | CWD | Project root directory |
--session <id> | auto | Isolate daemons for parallel workflows |
--json | off | JSON output |
Returns: run_id, total case count, list of case names, run directory path.
Example:
simforge submit --tags smoke -j 8
simforge submit --tags regress --exclude-tags slow -j 16 --seed 42
Poll the progress of a regression run.
simforge status [--run-id <id>] [--project-dir <dir>] [--json]
Returns: run status (running/completed/cancelled), counts of total/passed/failed/running/pending cases, elapsed time, list of currently running and failed case names.
Example:
simforge status
simforge status --run-id 20240101_002
simforge status --json
Cancel a running regression.
simforge cancel [--run-id <id>] [--project-dir <dir>] [--json]
Returns: run status, number of killed running jobs, number of cancelled pending jobs.
Get per-case detailed results.
simforge results [--run-id <id>] [--filter all|failed|passed] [--project-dir <dir>] [--json]
| Parameter | Default | Description |
|---|---|---|
--filter | all | Show all / only failed / only passed cases |
Returns: summary counts + per-case table with: name, status, seed, elapsed_sec, log_file path, error snippet.
Example:
simforge results --filter failed
simforge results --json
Merge per-case coverage databases into a single merged report.
simforge merge-cov [--run-id <id>] [--tool urg|imc|vcover] [--project-dir <dir>] [--json]
Returns: path to merged coverage directory, merger tool used, number of databases merged.
Auto-detects tool from simulator: VCS → urg, Xrun → imc, QuestaSim → vcover.
List testplan cases without starting a daemon. Useful for previewing tag filters.
simforge list [--testplan <path>] [--tags <t1,t2>] [--exclude-tags <t1,t2>]
[--project-dir <dir>] [--json]
Returns: total count + list of case names and their tags.
Example:
simforge list --tags smoke
simforge list --json | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['total'])"
List all runs: includes active (in-memory) runs from the current daemon and completed runs persisted to disk from past sessions.
simforge list-runs [--project-dir <dir>] [--session <id>] [--json]
Each entry shows: run_id, status, total/passed/failed, elapsed_sec, finished_at (disk runs), and source (live or disk).
Use this to see the history of all past regressions in a project, even after daemon restarts.
Global view of all running daemons across sessions.
simforge ps [--clean] [--json]
| Parameter | Description |
|---|---|
--clean | Remove stale (dead process) registry entries |
Returns: list of all active daemons with their run summaries, plus stale entries.
Shutdown the daemon for this project.
simforge close [--all] [--project-dir <dir>] [--session <id>] [--json]
| Parameter | Description |
|---|---|
--all | Close all daemons in this session |
The testplan file (cases/testplan.yaml by default) defines all simulation cases: