hdlmake.mk --- simple HDL build system
hdlmake.mk tries to provide a unified user environment for working with FPGAs.
Minimum requirements:
- GNU make
- GNU Emacs
For synthesise, running simulations, test benches, or doing formal verification additional tools might be required.
The following targets are always available:
all Compiles all test-benches and simulation (if any).
info Show current configuration.
check Runs all test-benches (if any).
clean Cleans up any build artifacts.
help Prints out a help message.
indent Format code using verilog-mode and GNU Emacs.
Creating a very simple project
The absolutely simplest project consists of one GNUmakefile (or Makefile) with the following:
PROJECT = blinky
include hdlmake.mk/hdlmake.mk
This assumes that your top-level module is called "blinky". You can then put your test-bench HDL in "blinky_tb.v", and your HDL in "blinky.v".
Running "make tb" will run the "blinky_tb" test-bench, and you can view the resulting waveforms using "make vcd"; or just run "make vcd" directly, it will run the test-bench if it hasn't been run.
General Configuration
The following variable must be set by the user:
- PROJECT
User configurable variables
- TOPLEVEL
- SRCS_V
- SRCS_VHD
Simulation
Verilator (verilator)
User configurable variables:
- VERILATOR_ROOT
- VERILATORFLAGS
- VERILATOR_CPPFLAGS
Available targets:
- sim
Simulators for test benches
Supported simulators:
- ghdl
- icarus
- cvc
- cver
- none
Additional required tools:
- gtkwave
User configurable variables:
- TESTBENCH
- TESTBENCHES
- TB_SRCS_V
- TB_SRCS_VHD
Available targets:
- tb
- vcd
- tb-TB
- vcd-TB
GHDL
User configurable flags:
- GHDL
- GHDLFLAGS
- GHDLRUNFLAGS
Icarus Verilog (icarus)
User configurable flags:
- IVERILOG
- IVERILOGFLAGS
CVC (cvc)
User configurable flags:
- CVC
- CVCFLAGS
GPL Cver (cver)
User configurable flags:
- CVER
- CVERFLAGS
Formal Verification
Supported formal verification tools
- symbiyosys
- none
Available targets:
- formal
SymbiYosys (symbiyosys)
User configurable flags:
- SBY
- SBYFLAGS
Vendors
Supported vendor types:
- xilinx-ise
- xilinx-vivado
- altera-quartus
- no-vendor
- none
User configurable variables:
- CONSTRAINTS
BITFILE
SYN_SRCS_V
SYN_SRCS_VHD
Available targets:
- syn
Xilinx ISE (xilinx-ise)
This assumes that Xilinx ISE is properly setup (i.e., settings64.sh or settings32.sh has been sourced), and that the XILINX variable is pointing to its installation directory.
The following variable must be set by the user:
- TARGET: The full part-speed-package identifier for the Xilinx part to be targeted, e.g. xc6slx9-2-tqg144.
User configurable flags:
XILINX: Install location of Xilinx ISE.
ISEFLAGS
XSTFLAGS
NGDBUILDFLAGS
MAPFLAGS
PARFLAGS
BITGENFLAGS
TRCEFLAGS
FUSEFLAGS
ISIMFLAGS
Available targets:
- trace
- isim
Xilinx Vivado (xilinx-vivado)
This assumes that Xilinx Vivado is properly setup (i.e., settings64.sh or settings32.sh has been sourced), and that the XILINX variable is pointing to its installation directory.
The following variable must be set by the user:
- TARGET: The full part-speed-package identifier for the Xilinx part to be targeted, e.g. xc6slx9-2-tqg144.
User configurable flags:
- XILINX: Install location of Xilinx Vivado.
Altera / Intel Quartus (altera-quartus)
The following variable must be set by the user:
- FAMILY
- TARGET
User configurable flags
- MAPFLAGS
- FITFLAGS
- ASMFLAGS
- STAFLAGS
Available targets:
- modelsim
No Vendor (no-vendor)
FPGA Programming Tools
Supported programmer types:
- fpgaprog
- quartus_pgm
- impact
- djtgcfg
- xc3sprog
- vivado
- none
The variable BITFILE must be set, either by a "vendor" or explicitly by the user.
- BITFILE
Available targets:
- prog
fpgaprog
User configurable variables:
- FPGAPROG
- FPGAPROGFLAGS
quartus_pgm
User configurable variables:
- QUARTUS_PGM
- QUARTUS_PGMFLAGS
impact
User configurable variables:
- IMPACT
- IMPACTFLAGS
djtgcfg
User configurable variables:
- DJTGCFG
- DJTGCFGFLAGS
xc3sprog
User configurable variables:
- XC3SPROG
- XC3SPROGFLAGS
Conventions for Simulation, Test Benches and Formal Verification
When writing test benches or other simulations, use the SIMULATION macro to toggle the debugging output or checks when run in a simulator. For formal verification properties use the FORMAL macro to guard the statements.
Each module that contains specific simulation statements should also
contain a local variable debug' that can be used to toggle additional
output (e.g. by setting
DUT.debug = 1' in a top-level test bench).
Additional variables can be used to allow tracing for specific paths
in a module .
All $display/$monitor statements should be of the following format:
$display("%t: %m: MESSAGE", $time, ARGUMENTS);
When writing or reading from inputs or outputs respectively, try to use the following format, this can be easily parsed by other tools later on:
$display("%t: %m: W @%o <- %o", $time, address, d);
$display("%t: %m: R @%o -> %o", $time, address, q);
Glossary / Naming Conventions
- d: data in
- q: data out