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 settingDUT.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