cli · bitbuild without a board

dewfpga bit

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?

dewfpga bit prints three lines and keeps the full place-and-route log in <top>.log:

Use a flat folder of .sv/.v modules (an .xdc only for ports without a board name), or run inside a Vivado project: its .xpr selects the enabled design, constraint and simulation files. Commands from a nested .srcs folder use the project root; outputs go there too. dewfpga tops lists top candidates without writing files. The project's selected top wins unless you name one: dewfpga bit <top>. In a flat folder, hierarchy and a unique matching .xdc select the top; ambiguous candidates require a choice. A filename alone does not select it. A testbench has no ports and instantiates the design; $finish/$stop in a design module is an error. A file that holds only a package, an interface or typedefs is read too, each after the files that declare a name it uses: a package before its users, a typedef file before the interface that uses the type (one that another file includes is read through the include, not twice). Example: dewfpga new blink.

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

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

dewfpga bit, three lines: the pin check, place and route, the bitstream. The full place-and-route log is in blink.log.

In a flat folder, hierarchy and a unique matching .xdc select the top. If several modules qualify, name one: dewfpga bit lab4 (module or source filename). A module's own filename alone does not select it. dewfpga tops lists candidates without changing files.
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?.

Yosys does not implement that inheritance. dewfpga bit supplies the direction in a temporary compiler copy before synthesis and tells you so. Your saved file is unchanged:

From section 7.1, Which course file breaks?.

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.

Tool	Arguments	Behavior
`bit`	absolute `project`, optional module `top`, `timeout_s`	build a bitstream; default 600 s, max 1800 s

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

Which errors can it stop with?

67 codes in the error catalog.

no-iostandard-property: A port in your design has no pin in the .xdc file. nextpnr names the wrong port.
port-neither-input-nor-output: The course's seven-segment module has a broken port line. Vivado accepts it, Yosys does not.
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-xdc-file: The folder has no .xdc and some ports have names the board does not use, so nothing says which pin they go to; ports with the board's names get their pins without a file.
two-xdc-files: Several .xdc files in the folder and none named after the top module; the CLI does not guess which one is the pin file.
no-top-module: The source scan ended without a top module and without a reason; naming the module on the command line settles it.
toolchain-not-installed: nextpnr-xilinx, the chip database or another tool is not under FPGA_HOME; the build needs all of them.
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.
port-without-pin: A port of the top module has no PACKAGE_PIN line in the XDC: the line is commented out, the index is missing, the name differs.
no-such-pin: A PACKAGE_PIN in the XDC names a pin the chip does not have: a typo, a pin of another board, a power pin, or a pin written in small letters (w5).
pin-used-twice: Two ports of the design have the same PACKAGE_PIN in the XDC: a copied line whose pin was not changed.
xdc-get-ports-form: A get_ports with a wildcard, a list of several ports or an option (-regexp, -filter): Vivado expands those, this check reads one full port name per line.
xdc-port-case: An XDC line names a port that differs from the design's only in case; names are case-sensitive, so the line pins nothing.
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.
ref-argument: A function or task argument passed by reference; yosys' reader stops on it and yosys-slang builds the call as nothing.
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.
package-not-found: An import or pkg::NAME names a package no file in the folder declares.
isunknown-in-design: $isunknown in synthesizable code; a chip has no x, and yosys folds the call to a constant that differs from the simulation.
latch: A combinational block leaves a signal unassigned on some path, so it has to remember its value: a latch, built as Vivado builds it, with the same warning.
latch-loop: A latch the reader turned into a combinational loop instead of a latch cell; the loop does not behave like the simulation, so the build stops.
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.
latch-hazard: An always_latch whose gate and data come from the same inputs: when both change at once the board races, where the simulation keeps the old value; the build goes on with the warning.
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.
async-reset-nonconst: In an always_ff with an asynchronous reset, the reset branch loads a register from a signal, or a signal is written outside the reset if/else; a flip-flop can only reset to a constant.
async-reset-polarity: The sensitivity list names one edge of the reset and the first if tests the other level, so the reset edge lands in the else branch, which loads a signal.
async-reset-not-alone: The block has a clock and an asynchronous reset in its sensitivity list, but the first if tests the reset ORed with another signal.
dual-edge: One always block clocked on posedge and negedge of the same clock; the chip's flip-flops have one clock edge.
initial-from-signal: An initial block, or a declaration, sets a register's start value from a signal; power-up values are constants.
two-always-drivers: The same register is assigned in two always blocks; yosys resolves the conflict silently, Vivado refuses it.
always-and-assign: A signal assigned both in an always block and with assign; two drivers on one wire.
two-assign-drivers: A signal with two assign lines; two drivers on one wire.
multiple-drivers: A signal written from more than one place that the checker could not sort into always blocks and assigns; two drivers on one wire.
undeclared-name: A name used but never declared; yosys' reader makes an implicit 1-bit wire with no driver, so the design would be built without it.
hierarchical-name: A signal reached through an instance name (u_cnt.count); yosys' own reader does not resolve it. With yosys-slang installed the design builds, with the read-with-slang note.
interface-member: A member of an interface instance read in the module that declares the instance; yosys' own reader makes an undriven wire of it. With yosys-slang installed the design builds.
module-not-found: An instance of a module no file in the folder declares.
enum-method-next-prev: The enum methods next() and prev(); neither reader builds them, Vivado does.
slang-refused: Both readers refused the code; yosys' own line is printed first, then yosys-slang's error with its caret.
slang-unimplemented: yosys-slang stops on a construct it has no implementation for, without a line; the code line dump above it shows the construct.
yosys-crashed: yosys died with a signal instead of an error message; a real literal in a parameter is the known cause, and the line that holds one is named.
second-reader-missing: The code needs the second reader, and it is not built; the error above it may go away with it.
read-with-slang: Not an error: yosys' own reader refused the code, yosys-slang read it, and synthesis went on as usual.
v-is-verilog-2005: A .v file that holds SystemVerilog; both readers, like Vivado, read .v as Verilog-2005, so logic and always_ff are syntax errors there.
fsm-encoding-kept: Not an error: a state register carries an fsm_encoding attribute, and the build keeps the codes the declaration gives it instead of letting yosys re-encode the register, so it powers up in the state with code 0, where dewfpga sim starts it; the build goes on.
no-create-clock: Not an error: the XDC has no create_clock line, so every clock is checked at the board's 100 MHz.
internal-tristate: A z driven onto an internal signal or a submodule port; the chip's tri-state buffers sit on pins only, and yosys keeps the buffer as a cell nextpnr cannot place.
tristate-to-logic: Two z drivers on one internal bus in one module; yosys builds them as logic, as Vivado does, so the board never shows the z or x the simulation shows.
wired-net: A wor or wand net with several drivers; yosys keeps the wired resolution as a $and/$or cell nextpnr cannot place.
power-operator: The ** operator with a variable base; yosys builds only constant powers and 2 ** n.
empty-module: An instance of a module with ports and no body; yosys keeps it as a black box, nextpnr has no cell of that type.
design-too-big: nextpnr ran out of a real resource of the chip; the counts are in the log.
timing-not-met: The longest path between two registers is longer than the clock period; the CLI writes no bitstream where Vivado would, with a critical warning.
empty-fasm: The place-and-route output file is empty, usually from a build interrupted between nextpnr and the bitstream.

Which patch notes name it?

previous: dewfpga sim
next: dewfpga flash
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