cli · simrun your testbench

dewfpga sim

What does its help text say?

dewfpga sim | bit | flash | clean [top]
                                 work on the .sv files in the current folder. top = the module nothing else
                                 instantiates (or name it: a module or a file). pins = <top>.xdc or the only .xdc
                                 In a Vivado project (a folder with one .xpr, or anywhere under its .srcs): the
                                 project's enabled files, its top module, its .xdc; outputs land next to the .xpr

From dewfpga --help, as bin/dewfpga prints it.

What does the README say?

Run reads the chosen file and the modules it uses from the other .sv/.v files of its folder (with the package files they name), never a file the design does not use. Run on a submodule's file builds the one top that uses it. Inside a Vivado project, Run builds the project: its files, its top, its .xdc. Literal include/data paths must be relative, without spaces or ... dewfpga sim runs a separate testbench. Short setup guide.

dewfpga sim|bit|flash|clean [top]   build a flat folder or a Vivado project

For coding agents, check, sim, bit and flash accept --json, for example dewfpga sim --json --timeout=180. Standard output contains one dewfpga/result@1 object; the process exit matches exit_code. Read diagnostics for source locations, error codes and fix links, and log.tail when no structured diagnostic is available. artifacts distinguishes new, cached and stale outputs; an old .bit is not proof that the current build succeeded. Full protocol and limits: agent interface.

test/fuzz/run.sh <first seed> <count> is separate from the suite: gen.py writes a random design per seed in the SystemVerilog DDCA teaches (every feature a switch, --list names them), dewfpga sim and dewfpga bit run on it, the netlist is simulated with the same testbench, and the two traces are compared bit by bit. Its last line counts the outcomes (ok, silent-wrong, refused-coded, refused-uncoded, crash, sim-refused).

From the README.

What does the guide say?

dewfpga new blink    # prints: blink/ ready:  cd blink && dewfpga flash    (VS Code: ⌘⇧B)
cd blink
dewfpga sim          # simulation
dewfpga bit          # .sv -> .bit
dewfpga flash        # .bit -> the board; runs bit first when the .bit is missing or older than the .sv

What each one prints when it works. dewfpga sim:

• dewfpga sim needs a testbench that instantiates the top; <top>_tb.sv is the usual name but any name works. bit and flash do not need one. A testbench that never reaches $finish is stopped after 120 s with an error; SIM_TIMEOUT=600 dewfpga sim waits longer. $stop ends the run like $finish. flash builds the .bit first if it is missing or older than the sources, so dewfpga flash alone is enough.

• dewfpga bit writes no bitstream when timing is not met, and synthesis failures remove the previous .bit. A failure during XDC validation can still leave an old .bit on disk; a file being present does not prove that the latest build succeeded. Without a create_clock in the XDC every clock is checked at 100 MHz, a divided one too, which Vivado does not time; a multiplier that Yosys puts in a DSP48E1 with a register inside is not timed at all (nextpnr-xilinx). When nothing changed, bit prints one line saying so. $display in synthesizable code is dropped, as Vivado does. dewfpga sim exits with an error when the testbench prints $error or $fatal, so a red run is visible.

dewfpga sim|bit|flash|clean [top]   build a flat folder or a Vivado project

From section 2, How do you install it in one line?.

How does a coding agent call it?

dewfpga check --json, dewfpga sim [top] --json, dewfpga bit [top] --json and dewfpga flash [top] --json print exactly one JSON object on stdout. Text commands retain their existing output. flash programs attached hardware; request it only when the user has authorized programming the board.

From the agent interface: the machine-readable CLI and the MCP server.

Which errors can it stop with?

32 codes in the error catalog.

• unknown-option: A word starting with - after the command, or an argument after install: the commands take a module or file name at most, install takes nothing.
• no-source-file: The current folder holds no .sv or .v file; dewfpga works on the files in the folder you run it in.
• run-inside-the-folder: The argument holds a slash: the CLI takes a module or a file name in the current folder, not a path.
• file-name-with-space: A .sv, .v or .xdc file name with a space in it; yosys, iverilog and nextpnr take file lists split at spaces.
• utf8-bom: The file starts with the three invisible bytes EF BB BF that Notepad and some editors write; yosys reads them as a token it does not know.
• no-testbench: No module without ports instantiates the top module, so there is nothing to simulate it with.
• no-top-module: The source scan ended without a top module and without a reason; naming the module on the command line settles it.
• explicit-port: Not an error: a port list in Vivado's netlist form names a port with an expression, .dp(\<const0> ), which Vivado builds and yosys' reader does not; the copy the tools read writes it as a plain port.
• module-without-endmodule: A module's endmodule is missing or misspelled, so the module never ends; the scan stops here instead of naming the wrong top.
• two-tops: Two or more design modules that nothing instantiates; the CLI does not pick one by file name (Lab 4 folders name the file after the wrong one).
• top-is-a-testbench: The module named on the command line has no ports, so it is a testbench; a bitstream needs a design with ports.
• no-such-module: The name on the command line is neither a module nor a file of this folder.
• no-design-module: Every module in the folder has no ports; there is nothing to build.
• module-defined-twice: Two files in the folder declare the same module; the tools would take the last one read, so a backup could be built instead of the design.
• finish-in-design: A $finish or $stop inside a module with ports; there is no hardware for it, and yosys stops on it where Vivado drops it.
• decl-init-reads-signal: `logic [3:0] sum = sw[3:0] + sw[7:4];` sets a power-up value from a signal; it is not a continuous assignment, and the board would show the value from time 0 forever.
• unnamed-instance: `inv(sw[0], led[0]);`, an instance without a name: Vivado accepts it, the standard and yosys do not, so the CLI names it u_inv in a temporary compiler copy and says so. Your saved source stays unchanged.
• vivado-netlist-in-folder: A .v file whose header says it is a Vivado post-synthesis simulation netlist sits next to the sources; it is not a design and yosys cannot read it.
• iverilog-refused: iverilog stopped with an error; its own lines are above, and this line names the first of them.
• sim-from-build: Not an error: iverilog refused a construct in the design, so the testbench ran against the design as the build elaborates it, read by the reader the note names.
• sim-from-build-parameters: iverilog refused the design and the testbench sets the top module's parameters; the simulation of the design as the build reads it cannot apply them, so it stops instead of testing another design.
• sim-starts-as-board: Not an error: a register or a memory of the design has no start value, and the simulation starts it where the board starts it (the reset value; 0 without a reset; a LUT RAM word at 0) instead of x, so a case or an if that reads it before the first reset takes the same branch in the simulation and on the board.
• sim-timeout: The testbench never called $finish, or needs longer than the timeout; the CLI killed the simulator.
• sim-exit: vvp ended with a non-zero exit: a $fatal in the testbench, or a run that ended without $finish.
• testbench-error: The simulation ran to $finish, and the testbench printed ERROR: lines with $error: a check failed.
• packed-typedef-2d: A typedef of a two-dimensional packed array used to declare a parameter or a net; yosys flattens the type and every row index picks one bit.
• package-file-not-given: The package lives in a file the tools are not given: a .svh or .vh that no design file `includes, or a file outside the folder or the project.
• included-twice: The testbench `includes a file the simulation reads with the design already (a package file of the folder, or one the design `includes), so the package is declared twice and iverilog stops.
• package-not-found: An import or pkg::NAME names a package no file in the folder declares.
• unique-case-overlap: Two items of a unique casez (or casex) can match the same value; the simulator takes the first, the hardware ORs both, so the board would not do what the simulation showed.
• implicit-port-width: A .* or .name port connection whose port and signal widths differ: the simulator pads or cuts and runs, neither synthesis reader builds it; the same line at sim and at bit names the port, the two widths and the fix.
• cannot-write-here: The build directory is not writable, or the disk has no space for the temporary source copies.

Which patch notes name it?

• #2 132 SystemVerilog probes run through the product, every stage checked
• #3 Silent wrongs stop the build
• #5 Every message in one shape, with its code and its page
• #28 dewfpga sim simulates what the build reads when iverilog refuses the design
• #29 A failed build leaves no old bitstream, wrong pins are named, a quick save rebuilds
• #31 A random-design generator checks the SystemVerilog DDCA teaches against its own simulation
• #32 A latch whose gate and data change together, and a unique casez whose items overlap: the chain names both before the board differs from the simulation
• #33 The chain reads every design file, not only the ones that hold a module, and a .* connection whose port and signal widths differ is named with the fix before either reader refuses it
• #35 A register read before its first reset: dewfpga sim starts it where the board starts it, and the netlist keeps the state codes the student wrote

What does dewfpga clean do?

The help text above lists it with dewfpga sim.

What does the guide say?

• bit leaves its working files next to the sources (.json, .fasm, .frames, .log, _routed.json), sim leaves <top>_sim, <top>_sim.out and <top>.vcd, flash leaves <top>_flash.out. dewfpga clean removes all of them and the .bit; the .sv and .xdc stay. Run it before you hand a lab in.

From section 2, How do you install it in one line?.

previous: dewfpga run
next: dewfpga bit
Every command: dewfpga install · dewfpga check · dewfpga run · dewfpga sim · dewfpga bit · dewfpga flash · dewfpga clean · dewfpga tops · dewfpga new · dewfpga uninstall · dewfpga vscode · dewfpga … --json · dewfpga mcp