Questions from students#

Makefiles#

You use makefiles in your projects. What are they for?

These files are used to synthesize or simulate the design by using commands on the shell without firing up the GUI. In other words they contain recipes to build your project.

You find more info on make in Sean Kross’ book The Unix Workbench. Makefiles can not only be used for compiling code but also for describing frequently used steps in a project.

Why do you use them? The GUI is easier to use after all.

I use them because these save me the mouse clicks for recurring tasks during the design process like synthesizing the design and programming the FPGA.

Alternatively you could also use a program that records your mouse actions and repeat them. It is more reliable and less error prone to use commands, though.

Another advantage of using Makefiles is that you can add the programming capabilities of your shell like Bash or Powershell to add further automation on top, e.g., synthesizing a project with fifty different configurations and select one with the best results.

Delivering only necessary files#

You recommend us to upload only the necessary files to a repository. Why?

These necessary files are typically called source files. For example your HDL files are source files but the bitstream and logs are generated files.

You should only upload source files if another developer (including your future you) will continue working on a project later. When you are working professionally you could be working in a team or your project will be used by someone else. Uploading unnecessary files will clutter developer’s view and could waste developer’s time in unnecessary searching tasks. For example assume that there are 10 files in a project directory, but only one of them is an actual source file, and a colleague of you who took over your project tries to introduce themselves to the project. They will first think that all of the files could influence the design and will start browsing them. This is unnecessary.

Note

Commands also help us to minimize the project file. If you have a complex project you could first export a script file that can regenerate your Vivado project and even recreate the block designs that you have drawn. Then you can extract only the required commands out of these files.

These commands are documented in Vivado UG – Using TCL scripts to Create Projects and Block Designs.

Including building & usage instructions in the project#

I uploaded my project to a repository. Why do you want us to write instructions how to compile the project and use it?

If you deliver a project it should contain instructions to build the project. This will ease the job for the user. Imagine you bought a new shelf from a home improvement store. The building instructions will ease your job. Usage instructions are helpful too.

The building instructions should typically include a build script. Why?

Surely you could also describe how to synthesize your project in the GUI. Writing the commands to create a bitstream are much shorter and less error prone.

How can I do that?

After your are done your project you can create a script file that opens your project and generates the bitstream using commands. For example here are excerpts from my makefile that generates scripts to open a project and generate a bitstream in Vivado:

syn.tcl:
	@echo open_project $(SYN_PROJ)                     > $@
	@echo synth_design                                >> $@
	@echo opt_design                                  >> $@
	@echo place_design                                >> $@
	@echo phys_opt_design                             >> $@
	@echo route_design                                >> $@
	@echo report_timing_summary                       >> $@
	@echo report_utilization                          >> $@
	@echo report_power                                >> $@
	@echo write_bitstream -force $(BITSTREAM)         >> $@

$(PROJ) and $(BITSTREAM) are the filenames of your Vivado project and the bitstream filename respectively. > $@ and >> $@ are part of Unix shell and makefile syntax and they write these lines to syn.tcl. They should not be included in your synthesis script file.

Similarly the following excerpt programs the bitstream.

program.tcl:
	@echo open_hw_manager                                 > $@
	@echo connect_hw_server                              >> $@
	@echo open_hw_target                                 >> $@
	@echo current_hw_device                              >> $@
	@echo puts \"Selected device: [current_hw_device]\"  >> $@
	@echo set_property PROGRAM.FILE {$(BITSTREAM)} [current_hw_device] >> $@
	@echo program_hw_device                              >> $@
	@echo close_hw_manager                               >> $@

You can execute a script file with Vivado using vivado -mode batch -source SCRIPT.tcl.

So an idea could be to put these scripts in your repository and write in the instructions that the user should run first vivado -mode batch -source syn.tcl and then vivado -mode batch -source program.tcl.

Language choice#

Why do you prefer Systemverilog over VHDL? A friend recommended me VHDL which supposed to be more popular in Europe.

The advancements in hardware description languages typically lag behind compared to the software languages. For example, as of 2022 the latest Systemverilog standard is from 2017 and the latest VHDL standard is from 2019. These standards are not implemented in Vivado though and Vivado supports Systemverilog 2012 and VHDL 2008.

In my opinion Systemverilog includes more convenient language features which I find beneficial especially for beginners.