hexforge / tool reference
Tool reference
Every subcommand, every flag, the five constraint directives and the error codes, on one page with a search box over all of it. The search reads a static index (/api/refindex.json) in your browser; with it off, the full reference is below and nothing is hidden.
Type to search tool flags, error codes, boards, examples and constraint directives.
Subcommands
Four programs, each reading one file and writing one file. There is no driver that runs them in sequence; the example makefiles do that in four lines so the chain stays readable.
hxc .v → .hxn
Parse the subset, elaborate parameters and generate blocks, flatten hierarchy, emit a gate and register netlist.
| Flag | Meaning |
|---|---|
-o <file> | Output netlist path. Default is the input name with .hxn. |
-I <dir> | Add a directory to the `include search path. Repeatable. |
-D <name>[=<val>] | Define a preprocessor macro, as `define would. |
--top <module> | Name the top module explicitly when the file holds several. |
--param <NAME=VAL> | Override a top-level parameter at elaboration. Repeatable. |
--dump-netlist | Also write a human-readable listing next to the .hxn. |
-v | Print each elaboration pass and the final cell and register counts. |
hxsyn .hxn → .hxr
Map logic to LUT4s and flip-flops, pack them into tiles, place, then route. Single-threaded and deterministic for a given seed.
| Flag | Meaning |
|---|---|
--device <part> | Target device, one of T4-12K, T4-25K, T4-45K, M1-8K. Required. |
-o <file> | Routed-design output path. Default is the input name with .hxr. |
--seed <n> | Placement seed. Changes the result but not its legality; default 1. |
--effort {low,medium,high} | Placement effort. high is the default and rarely worth lowering. |
--max-iters <n> | Router iteration cap. Default 40 since 0.7.2; runs needing more never converged. |
--report <file> | Write the packing and routing summary to a file as well as stdout. |
hxta .hxr → report
Static timing: clock groups, worst slack per clock, and the longest paths with per-cell delays.
| Flag | Meaning |
|---|---|
--device <part> | Device whose delay table to use. Required and must match the .hxr. |
--corner {fast,typical,slow} | Process-voltage-temperature corner. Default slow; sign off on slow. |
--paths <n> | How many of the longest paths to print. Default 10. |
--clock <name> | Restrict the report to one clock group. |
--derate <pct> | Add a flat pessimism percentage to every delay before computing slack. |
--json | Emit the report as JSON, including per-path hop counts, since 0.7.1. |
hxpack .hxr → .bit
Serialise the routed design into the device frame format and append the configuration header.
| Flag | Meaning |
|---|---|
--board <name> | Board whose pin map and configuration mode to use. Required. |
-o <file> | Bitstream output path. Default is the input name with .bit. |
--config-mode {spi-x1,spi-x4} | Override the board's configuration width, since 0.7.1. Fenwick A2 needs spi-x1. |
--no-crc | Omit the trailing CRC word. For boards whose loader rejects it; off by default. |
Constraints file (.hxs)
Exactly five directives, parsed top to bottom. Anything else is an error, because a constraints language that quietly ignores a line you got wrong is worse than one that stops.
| Directive | Form | What it does |
|---|---|---|
set_io | set_io <port> <pin> [-std <iostd>] | Map a top-level port to a device pin and optionally an IO standard. |
create_clock | create_clock <name> -period <ns> <port> | Declare a clock and its period at a port. |
set_input_delay | set_input_delay <ns> -clock <name> <port> | External delay before data arrives at an input, relative to a clock. |
set_output_delay | set_output_delay <ns> -clock <name> <port> | External delay required after an output, relative to a clock. |
set_false_path | set_false_path -from <a> -to <b> | Exclude a path from timing; the tool's only way to silence a W204 crossing. |
Error and warning codes
The full index with the reasoning behind each rejection lives on the error codes page, driven by the same data the compiler reports. The short version: E-codes stop the build, W-codes do not, and both are stable across releases even when the message text is reworded.