cli · flashbuild and load a project

dewfpga flash

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 sim|bit|flash|clean [top]   build a flat folder or a Vivado project

Measured 2026-09-19 and 20 on an M2 with 8 GB: clean install 3 min 37 s to 4 min 17 s (three runs), about 0.3 GB on disk (237 MB measured on 7 October; the optional agent SDK adds 51 MB; about 1 GB while it builds, the installer asks for 2 GB free); second run 2.7 s; bit 4.6 s, peak 552 MB RAM; chipdb generation peak 859 MB RAM. On the board, 19 and 20 September, five designs: the blink template, switches to LEDs, the Lab 2 adder/subtractor, the display counter and the traffic-light FSM, each built with dewfpga flash. With yosys 0.69 the chain built by the script produces byte-identical .frames to the hand-built chain that lit the LED; with another yosys the netlist differs and only the I/O placement is compared.

From the README.

What does the guide say?

all good.

Total: 217 s. Log: /Users/you/fpga/install.log
Next:  dewfpga new blink && cd blink && dewfpga flash

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 flash:

• 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 sim|bit|flash|clean [top]   build a flat folder or a Vivado project

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

dewfpga new blink gives the same blink.sv, blink_tb.sv and blink.xdc without the Makefile, and its tasks.json says dewfpga flash instead.

From section 4, What is in the project folder?.

With dewfpga: put the .sv files and the .xdc in one folder, cd into it, dewfpga flash. With lab4.sv and Basys3_Master.xdc in the folder that is all. With several .sv files, name the top: dewfpga flash lab4.

From section 5, How do you use it for your own lab?.

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?

6 codes in the error catalog.

• board-not-found: The programmer could not open the Basys3 USB interface. Check physical connection and, if macOS sees the device, the programming process's USB access.
• 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-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.
• toolchain-not-installed: nextpnr-xilinx, the chip database or another tool is not under FPGA_HOME; the build needs all of them.
• openfpgaloader-failed: The board was found, and programming still failed; openFPGALoader's own lines above say why.

Which patch notes name it?

• #2 132 SystemVerilog probes run through the product, every stage checked
• #6 The CLI's untested paths get checks, one number for the count, a test that reads the bitstream, the board test ready for the board
• #29 A failed build leaves no old bitstream, wrong pins are named, a quick save rebuilds
• Your own project, from editor to board
• The folder command needs no pin file for the board's port names

previous: dewfpga bit
next: dewfpga tops
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