---
title: "Reference and troubleshooting"
---

# Reference and troubleshooting

HDL module settings, hdl.json keys, supported tools and file formats with their verification state, agent tools, what asks before it writes to a device, what is recorded, how policy applies, and fixes for common problems.

## Settings

All keys are under `neuralInverse.hdl.`. They hold machine facts only (tool paths, extra arguments, the PDK root, the language server choice); a design's options belong in `hdl.json`. Settings that name executables are restricted in untrusted workspaces.

| Setting | Default | Meaning |
|---|---|---|
| `enabled` | `false` | Turns the environment on |
| `projectFile` | `hdl.json` | The project file, relative to the workspace folder |
| `paths.<tool>` | empty | Path to a tool or its folder |
| `lint.onSave` | `true` | Lint on save |
| `lint.verilatorArguments`, `lint.ghdlArguments` | `[]` | Extra lint arguments |
| `simulation.icarusArguments`, `simulation.verilatorArguments`, `simulation.ghdlArguments`, `simulation.nvcArguments` | `[]` | Extra simulation arguments |
| `simulation.ghdlWaveform`, `simulation.nvcWaveform` | `true` | FST of every signal for VHDL testbenches |
| `simulation.compiledLibraries` | `{}` | Compiled vendor simulation libraries by simulator |
| `cocotb.python`, `cocotb.waveform` | empty, `true` | cocotb |
| `vunit.python`, `vunit.arguments`, `vunit.waveform` | empty, `[]`, `true` | VUnit |
| `implementation.yosysArguments`, `implementation.nextpnrArguments` | `[]` | Extra synthesis and place and route arguments |
| `implementation.vivadoSynthesisArguments` | `[]` | Extra `synth_design` options for Vivado targets |
| `implementation.parallelRuns` | 2 | Open-flow strategy runs at once |
| `program.openFPGALoaderArguments` | `[]` | Extra openFPGALoader arguments |
| `openxc7.chipdbDirectory` | empty | nextpnr-xilinx chip databases |
| `vivado.boardRepoPaths` | `[]` | Company Vivado board files |
| `asic.pdkRoot` | empty (`PDK_ROOT`) | PDK folder |
| `asic.drc`, `asic.lvs` | `true` | Run the PDK's DRC and LVS decks |
| `verilog.languageServer`, `verilog.languageServerArguments` | `auto`, `[]` | Verible or svls |
| `vhdl.languageServer`, `vhdl.languageServerArguments` | `auto`, `[]` | vhdl_ls |
| `keymap` | `none` | `none`, `vivado`, `quartus`; see [Edit HDL and constraints](https://neuralinverse.com/docs/modules/hdl/editing/#vendor-keymaps) |
| `templates.folders` | `[]` | Company template folders |

## hdl.json keys

The project file is described on [Requirements and project setup](https://neuralinverse.com/docs/modules/hdl/setup/#the-project-file-hdljson); a JSON schema gives completion and validation. The full set of keys:

| Key | What it holds | Page |
|---|---|---|
| `name`, `sources`, `top`, `includeDirs`, `defines`, `vhdlStandard`, `buildDirectory` | The design | [Setup](https://neuralinverse.com/docs/modules/hdl/setup/) |
| `testbenches[]`: `name`, `top`, `sources`, `simulator`, `timeout`, `defines`, `cocotb`, `vunit`, `vendor` | Testbenches, cocotb modules, VUnit scripts, vendor simulation runs | [Simulate and test](https://neuralinverse.com/docs/modules/hdl/simulate/) |
| `formal` | SymbiYosys files | [Formal](https://neuralinverse.com/docs/modules/hdl/formal/) |
| `targets[]`: `name`, `family`, `device`, `package`, `chipFamily`, `constraints`, `top`, `frequency`, `board`, `cable` | FPGA targets | [Open flow](https://neuralinverse.com/docs/modules/hdl/implement/), [Vendor builds](https://neuralinverse.com/docs/modules/hdl/vendor-builds/) |
| `targets[].activity` | Testbench switching activity for power | [Vendor builds](https://neuralinverse.com/docs/modules/hdl/vendor-builds/) |
| `targets[].vivado` | Imported file sets, IP, block designs, `upgradeIp`, strategies with directives and hooks, `messageConfig`, `waivers`, `qorSuggestions`, `incremental`, `outOfContext`, `ipRepositories`, board part | [Vendor builds](https://neuralinverse.com/docs/modules/hdl/vendor-builds/#amd-vivado) |
| `targets[].quartus` | `edition`, IP, `upgradeIp`, files, parameters, assignments, `partitions`, `rapidRecompile`, `designAssistant`, `designAssistantWaivers`, `niosv` | [Vendor builds](https://neuralinverse.com/docs/modules/hdl/vendor-builds/#altera-quartus-prime) |
| `targets[].libero`, `dieVoltage`, `programmer` | `constraintTools`, `cores`, `initialization` | [Vendor builds](https://neuralinverse.com/docs/modules/hdl/vendor-builds/#microchip-libero-soc) |
| `targets[].radiant`, `performanceGrade`, `synthesis`, `xcf` | `ip`, `strategyFile`, `strategy` | [Vendor builds](https://neuralinverse.com/docs/modules/hdl/vendor-builds/#lattice-radiant) |
| `targets[].debug` | ILA probes and options, Signal Tap file, or Reveal probes, trigger units and expressions | [Hardware debug](https://neuralinverse.com/docs/modules/hdl/hardware-debug/) |
| `targets[].configMemory`, `exportHardware`, `tandem` | Configuration memory, Vitis hand-off, tandem configuration | [Program the board](https://neuralinverse.com/docs/modules/hdl/program/) |
| `targets[].reconfiguration` | Partitions, modules and configurations | [ECO and partial reconfiguration](https://neuralinverse.com/docs/modules/hdl/eco/) |
| `hls[]` | Vitis HLS components | [IP, packaging and HLS](https://neuralinverse.com/docs/modules/hdl/ip/#vitis-hls) |
| `asic[]` | Chips | [ASIC](https://neuralinverse.com/docs/modules/hdl/asic/) |

## Supported tools and their state

| Tool | State |
|---|---|
| Verilator, Icarus Verilog, GHDL, NVC, VUnit, cocotb 2 | Verified (Linux) |
| Verible 0.0-3622, vhdl_ls 0.88.0 | Verified (Linux) |
| SymbiYosys, eqy | Verified (Linux); equivalence on open-flow netlists only |
| Yosys, nextpnr (iCE40, ECP5, Gowin), icepll, ecppll, gowin_pll | Verified (Linux) |
| openXC7 (nextpnr-xilinx, Project X-Ray) | Verified (Linux); bitstream built, not programmed |
| OpenROAD, KLayout 0.28 and 0.30, Magic 8.3.465, netgen 1.5.272 | Verified (Linux) on the test designs |
| openFPGALoader | Modelled; no board programmed |
| AMD Vivado, Vitis HLS | Kit shipped; not yet run against Vivado |
| Altera Quartus Prime | Kit shipped; not yet run against Quartus |
| Microchip Libero SoC, FlashPro Express | Kit shipped; not yet run |
| Lattice Radiant, Radiant Programmer | Kit shipped; not yet run |
| Questa, Riviera-PRO, Xcelium, VCS, XSim | Kit shipped (Vivado and Quartus flows); modelled (Libero) |

## File formats

| Format | What the module does | State |
|---|---|---|
| `.v`, `.vh`, `.sv`, `.svh`, `.vhd`, `.vhdl` | Colouring always; language servers, lint, elaboration with the environment on | Verified (Linux) |
| `.pcf`, `.lpf`, `.cst`, `.sdc`, `.xdc` | Colouring, checks against the top, I/O planner edits | Verified (Linux) for placement constraints |
| `.pdc`, `.ldc`, `.fdc`, `.ndc` (Libero, Radiant) | I/O planner and constraint editor edits, Libero checks | Kit shipped (Libero); modelled (Radiant) |
| `hdl.json` | The project, with a schema | Verified (Linux) |
| `.vcd`, `.fst` | Waveform Viewer, our own readers | Verified against GTKWave's reader |
| `<dump>.layout.json` | The waveform viewer's saved layout | Verified (Linux) |
| `.ghw` | Not read | |
| `.sby`, `.eqy` | Formal tasks and equivalence checks in the Testing view | Verified (Linux) |
| `.gds`, `.oas` | Layout Viewer, our own readers | Verified against KLayout |
| `.xpr`, `.xci`, `.xcix`, `.bd` (Vivado) | Import, project edits, IP, diagrams | Readers and writers verified on real files (Linux); Vivado runs kit shipped |
| `component.xml` (IP-XACT) | Customize IP forms, packaged IP | Reader verified on real files (Linux); kit shipped |
| `.wcfg` (Vivado) | Waveform layout over a VCD the XSim run writes | Kit shipped |
| `.wdb` (Vivado) | Not read: proprietary | |
| `.ltx`, `.tsm` | ILA probes file; ILA trigger state machine programs | Kit shipped |
| `.rqs` | Vivado QoR suggestions applied before synthesis | Kit shipped |
| `.qpf`, `.qsf`, `.ip`, `.qip`, `.qsys`, `.ipx` (Quartus) | Import, assignment edits, IP, diagrams, the IP catalogue | Readers and writers verified on real files (Linux); Quartus runs kit shipped |
| `.stp` (Signal Tap) | Compiled in by the flow; not edited (format undocumented) | |
| `.mif`, `.hex` | In-System Memory saves, Nios V memory images | Kit shipped |
| `.prjx`, `.cxf` (Libero) | Projects, SmartDesign diagrams | Readers verified on real files (Linux) |
| `.vm`, `.edn`, `.srr`, `.fse` (Synplify Pro) | Technology view, state machine encodings | Modelled |
| `.rdf`, `.ldf`, `.sty`, `.ipx`, `.rvl`, `.rvs`, `.rva`, `.trc`, `.xcf` (Radiant, Diamond, Reveal) | Projects, strategies, IP, Reveal projects and captures, chain files | Readers and writers verified on real files (Linux) |
| `.gprj` (Gowin EDA) | Import | Modelled |
| `.mcs`, `.bin`, `.prm`, `.xsa` | Configuration memory images, Vitis hardware platform | Kit shipped |
| `.jic`, `.rpd`, `.pof` | Quartus configuration memory images | Modelled |

## Confirmations, records and policy

**Writes to a device always ask first.** **Program FPGA Board** shows the target, the board or cable, the bitstream with its size, build time and SHA-256, what the write replaces, and any timing failure, then hashes the bitstream again and refuses a changed one. Vendor hardware-debug and configuration-memory actions confirm too: programming from Hardware Debug confirms the SHA-256; JTAG-to-AXI writes and In-System Sources and Probes and memory writes are each confirmed, read back and compared; Reveal Analyzer settings are written after a confirmation; an ECO's `write_bitstream` runs only after a confirmation, and only once the changes are routed and DRC shows no error; Pblock edits show the XDC lines before they are written.

![A Quartus In-System Memory write waiting for confirmation, with the target, cable, addresses and values](https://neuralinverse.com/docs-images/modules/hdl/in-system-memory-confirm.webp)

**Records:**

- Each programming is logged with the bitstream's hash.
- Each build is remembered with the commit it came from, and the FPGA Implementation panel shows what changed against the previous build.
- Each Vivado ECO is recorded in the build folder as `eco.json`, a change log and a replay script.
- Vendor kits' archives hold logs, reports and generated scripts, with only the sizes and SHA-256 of bitstreams.

**Your organisation's policy:** with Neural Inverse Govern, builds and simulations that run as tasks or launch configurations, and changes to `neuralInverse.*` settings, are decided by the in-app policy check, which can allow, deny or require approval. The policy format also has rules for hardware operations such as loading a bitstream (`domainActions`); the HDL module does not yet submit its operations to that check in this release, so the confirmations above are the control that stops an unintended write. See [Govern](https://neuralinverse.com/docs/govern/).

**Agent tools:** most HDL actions are also tools the Editor's agents can call (builds, simulations, timing queries, IP, project edits, hardware debug and more). Read-only tools run without asking; every tool that changes a file, runs a vendor tool's state-changing step, or touches a board asks you to confirm, and the Tcl consoles' agent tools confirm any Tcl that is not a query.

**Downloads:** the module downloads nothing itself. Part and board lists, PDKs and device databases are read from where your tools installed them, never copied into the product.

## Troubleshooting

| Problem | What to do |
|---|---|
| Only colouring works | Turn on `neuralInverse.hdl.enabled` (or run **Neural Inverse: Enable HDL Environment**) and trust the workspace. |
| The status bar says **HDL: n of m tools** | Click it or run **Show HDL Tools**: it lists the missing tools with install hints. Set `neuralInverse.hdl.paths.<tool>` for tools in custom folders. |
| Go to Definition does not find a module in another file | The language servers read the sources from `hdl.json`; check its `sources` globs. **Restart HDL Language Servers** after big changes. |
| `vhdl_ls` does not start | It needs its standard libraries; its status says how to install them or pass `--libraries`. |
| A view stays blank after a SystemVerilog change | Elaboration through Yosys failed. Lint the design and check Problems; the supported SystemVerilog subset is Yosys's. |
| The CDC view calls a Gray-coded FIFO unsafe | A known limit of the RTL crossings view. On Vivado targets, Vivado's Report CDC classifies the pointers as synchronised; see [Timing analysis and constraints](https://neuralinverse.com/docs/modules/hdl/timing/#report-cdc). |
| Equivalence stops at a memory | Yosys 0.33 cannot model some memories there; the partitions it cannot prove are listed. |
| A vendor project file written into a new folder is not listed | Fixed on Linux (the Editor now searches added folders); on macOS and Windows the file watcher has not been checked. Run **Refresh Vivado and Quartus Projects**. |
| A vendor build fails at the licence | The message names the FlexNet feature, where the tool looked, and what to set. |
| A Pro Quartus project is built with Standard (or the reverse) | The build stops with a message; install the edition the `edition` key names. |
| A vendor path behaves differently on your installation | Run the matching verification kit and send the archive; vendor paths have not yet been run against the real tools. |

![Show HDL Tools: each tool found with its version and path, and an install hint for a missing one](https://neuralinverse.com/docs-images/modules/hdl/hdl-tools.webp)

To report a problem: what you did, what you expected, what happened, the tool versions, and a screenshot or the log, or the kit's archive.