Concepts
Projects
A project groups related synthesis jobs. Each project has:
- A slug (URL-safe identifier, e.g.,
my-counter) - A display name
- Optional defaults: target, max runtime, max memory, archive format, retention period
Jobs
A job is a single synthesis request. You provide source code, a target FPGA, and parameters. SuperSynth creates one run per seed and executes them in parallel.
Job statuses: created → queued → running → completed | failed | canceled | terminated
A job is terminated if it exceeds its time limit. A job is canceled if you cancel it manually.
Runs and Seeds
Each job fans out into one or more runs, each with a different random seed. The FPGA place-and-route tool uses this seed to explore different placement options. More seeds = better chance of finding a good result.
After all runs complete, a winner is selected based on the pick strategy (best_timing or best_area).
Pipeline Steps
Each run executes up to three steps:
| Step | Tool | What it does |
|---|---|---|
synth | Yosys | Synthesize HDL to gate-level netlist |
pnr | nextpnr | Place and route the netlist onto the FPGA |
bitstream | icepack/ecppack | Generate the binary bitstream |
You can run a subset (e.g., synth only) for quick validation.
Targets
A target identifies a specific FPGA device and package. Format: family:device:package.
Examples: ice40:hx8k:ct256, ecp5:85k:CABGA554
See FPGA Targets for the full list.
Build Profiles
A build profile bundles a target and tool arguments into a reusable configuration. Profiles are scoped to a project. When submitting a job, select a profile to inherit its target and tool args. Per-job overrides are merged on top.
Manage profiles via the Profiles tab on the project page, ssynth profile in the CLI, or the REST API.
Tool Arguments
You can pass extra arguments to each pipeline tool:
| Tool | Arguments | Example |
|---|---|---|
| Yosys | Extra synthesis passes | opt, abc9, flatten |
| nextpnr | Extra PnR flags | --tmg-ripup, --router router2 |
| Bitstream | Extra packing flags | --compress, --svf |
Arguments are allowlisted for safety. Set them on a build profile for reuse, or per-job for one-off tuning.
Custom Yosys Scripts
For full control over synthesis, provide a custom Yosys script (synth_script in hwbuild.yml). When set, SuperSynth runs yosys -s <your-script> instead of the auto-generated synthesis commands. The script should produce a JSON netlist for downstream PnR.
Credits
SuperSynth uses a credit-based billing model. Each run consumes credits based on compute time. Check your balance at Settings > Billing in the web UI, or via ssynth usage in the CLI.
API Keys
API keys (sk_live_...) authenticate the CLI and API integrations. Create them in Settings > API Keys. Keys are shown once at creation — save them immediately.