the guide · 2How do you run CS223 labs on a Mac without Vivado?

How do you install it in one line?

curl -fsSL https://nosey-dewdrop.github.io/dewfpga/install | bash

3 min 37 s to 4 min 17 s over three runs on the tested machine, plus about 4 minutes for the yosys-slang step added on 27 September (measured on its own: 70 s of clone, 2 min 53 s of compiling), 1.4 GB downloaded, about 0.3 GB kept 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; on slow wifi it takes longer, and it prints progress the whole time. It never asks for a password. It puts the dewfpga command into ~/.dewfpga (its sha256 is compared with nosey-dewdrop.github.io/dewfpga/dewfpga.tgz.sha256, so a broken download stops here), links it into Homebrew's bin, installs Yosys, openFPGALoader, Icarus Verilog and the build tools of section 3.1 through Homebrew, and builds nextpnr-xilinx, prjxray and the yosys-slang plugin (section 3.6) into ~/fpga at the three commits in section 9. Nothing touches your system Python. The last lines it prints:

all good.

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

To read the script before running it:

curl -fsSL https://nosey-dewdrop.github.io/dewfpga/install -o install.sh
code install.sh      # read it, then:
bash install.sh

Check that every piece is there:

dewfpga check

dewfpga check  (FPGA_HOME=/Users/you/fpga)
  ✓ yosys            /opt/homebrew/bin/yosys
  ✓ yosys-slang      /Users/you/fpga/yosys-slang/build/slang.so
  ✓ iverilog         /opt/homebrew/bin/iverilog
  ✓ openFPGALoader   /opt/homebrew/bin/openFPGALoader
  ✓ nextpnr-xilinx   /Users/you/fpga/nextpnr-xilinx/build/nextpnr-xilinx
  ✓ xc7frames2bit    /Users/you/fpga/prjxray/build/tools/xc7frames2bit
  ✓ fasm2frames      /Users/you/fpga/prjxray/utils/fasm2frames.py
  ✓ chipdb           /Users/you/fpga/chipdb/xc7a35t.bin
  ✓ venv             /Users/you/fpga/venv/bin/python
  ✓ python pkgs      fasm prjxray pyyaml textx simplejson intervaltree
all good.

A red ✗ names the missing piece: run the curl line again (it is the same as dewfpga install), it skips what is done. dewfpga: command not found has two causes: the Homebrew "Next steps" lines from section 1 were not pasted (the installer says so, Homebrew is installed (...) but not on your PATH, and prints the line to paste), or the installer stopped before its last line; scroll up to the first ERROR: line and look it up on the errors page.

Now plug the Basys3 into the Mac with the USB cable (the PROG port, next to the power switch) and flip the power switch on. Make the example project and flash it:

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:

VCD info: dumpfile blink.vcd opened for output.
PASS: 3 checks (see the waveform for the toggle)
blink_tb.sv:35: $finish called at 200000 (1ps)

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

xdc ok: 33 ports, all mapped.
pnr ok: 73 LUT, 27 FF, 278.71 MHz (PASS at 100.00 MHz)   (full log: blink.log)
blink.bit  2.2 MB

dewfpga flash:

Jtag frequency : requested 6.00MHz    -> real 6.00MHz
Open file DONE
Parse file DONE
load program
Load SRAM: [==================================================] 100.00%

Done
Shift IR 35
ir: 1 isc_done 1 isc_ena 0 init 1 done 1

done 1 means the chip accepted the design. Flip switch 0 up (SW0, the rightmost of the 16 switches): LED 15 (LD15, leftmost) lights and LED 0 (LD0, rightmost, just above SW0) blinks once a second. The design lives in SRAM, so a power cycle clears it; flash again.

If it prints ERROR: board not found. Is the USB (PROG port) plugged in and the power switch ON? instead, the Mac does not see the board: power switch, PROG port, a charge-only cable, the adapter, or the JP2 jumper. The board not found page goes through them in order.

The rules dewfpga follows in a folder:

• Every .sv and .v in the folder is handed to the tools, so submodules can live in their own files, and a file can be named anything: lab5.sv may hold module top_design. A file that holds no module (a package, an interface, or typedefs at file scope, alone in their file) is read before the files that hold a module, each after the files that declare a name it uses (a package before the files that name it, a typedef file before the interface that uses the type; alphabetical order would hand iface.sv before types.sv and iverilog would stop at the first nib_t), and the files are one compilation unit for both readers, as Vivado reads the files of one library (UG901 Ch.10, Compilation Units). A file that another file includes is read through the include only (handing it too would declare the package twice). A testbench has no ports and instantiates the design. $finish or $stop in a design module is an error; keep them in the testbench.
• 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.
• Inside a Vivado project, the .xpr chooses the enabled design, constraint and simulation sets and their top modules. A command inside its .srcs subfolders runs at the project root; outputs go beside the .xpr. Without an .xpr, a .srcs tree with sources_1, constrs_1 and sim_1 is supported. Missing design files stop the build; a problem confined to the simulation set stops sim. Multiple projects or ambiguous active sets produce an error. .v files retain Verilog-2005 keywords, and local include directories are passed to both readers. IP Catalog and Block Design generation are not supported.
• The pin file is <top>.xdc, or the only .xdc in the folder. Pins in it that the design does not use are ignored, so a fully uncommented Basys3_Master.xdc is fine.
• 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.
• Code that Vivado lets through and Yosys refuses: the course's SevSeg_4digit.sv port line (output [6:0]seg, logic dp) gets its direction written in by bit, with a note naming the line. Some other cases stop with the line and the fix, such as an instance without a name (clk_div(clk, out);) or a latch in an always_comb. Others stop with no line, or with advice that does not fit, and some build a bitstream that does not do what the code says, with no error. Section 7 lists what the course's files and old student repos hit; section 8 links the full measurement.
• 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.
• 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.

dewfpga install                     install the toolchain (safe to re-run)
dewfpga check                       is every piece in place
dewfpga sim|bit|flash|clean [top]   build a flat folder or a Vivado project
dewfpga tops                        list top candidates without writing files
dewfpga vscode [--remove]           set up or remove the editor integration
dewfpga new <dir>                   blink example with a VS Code task (Cmd Shift B = flash)
dewfpga uninstall                   remove what install built in ~/fpga, the CLI and its link;
                                    your files in ~/fpga and the brew packages stay
dewfpga --version

Continue with section 5.

previous: 1 What do you need before you start?
next: 3 How do you build the chain by hand?
This section in the whole guide
The commands this section names: dewfpga install · dewfpga check · dewfpga sim · dewfpga bit · dewfpga flash · dewfpga clean · dewfpga tops · dewfpga new · dewfpga uninstall · dewfpga vscode

Stuck on an error? Every error from this setup, filed under the exact line it printed.