Getting started
The modules can be used straight away in your simulation and build project. Start by cloning the repo:
To checkout a stable release version, choose one of the tags.
If you are using a Python-based simulation/build flow, using hdl-modules with tsfpga (see installation) is highly recommended. It is easier, more compact and more portable than handling the source code manually.
Dependencies
The Module bfm as well as all testbenches in this project depend on the VHDL components in
VUnit version 5.0.0 or greater.
This VUnit version is currently in a pre-release state and can be installed with e.g.
python -m pip install vunit-hdl==5.0.0.dev5 or by cloning the
repository.
Feel free to exclude the Module bfm if you do not use VUnit. If that module as well as the testbenches are excluded, no dependencies are required.
Source code
When using tsfpga, simply call the function
get_hdl_modules()
and add to your list of modules.
Note that you must add the hdl-modules repository to your Python path to call this function,
either by using sys.path.append(...) or by setting the PYTHONPATH environment variable.
You can now use e.g.
get_synthesis_files(),
get_simulation_files()
and library_name just like with any other module.
Note that you probably want to set the include_tests argument to False when
calling get_simulation_files(),
so you are not running testbenches unnecessarily.
Manual workflow
When not using tsfpga, source code must be added manually to your build/simulation project.
Synthesizable source code is found in the src folder of each module.
These files should be added to your simulation and build project.
The library name is the same as the module name.
Testbenches are found in the test folder of each module.
Simulation code (BFMs) is found in the sim folder of each module.
The simulation code should be added to your simulation project but not your build project.
All files must be handled as VHDL-2008.
Scoped constraints
When using tsfpga, scoped constraint files are loaded automatically to the build project and correct settings are applied.
Background
Many entities in this project have corresponding constraint files that must be used in
build projects for proper operation.
These are found in the scoped_constraints directory of the module, which contains
.tcl files that have the same file name as the corresponding entity.
A constraint files being “scoped” means that it is applied relative to each instance of an entity. Using this, we do not have to search through the whole design hierarchy to find the signals that we are interested in.
Manual workflow
When not using tsfpga, scoped constraint files must be loaded in Vivado with e.g.
read_xdc -ref asynchronous_fifo /home/lukas/work/repo/hdl-modules/hdl-modules/modules/fifo/scoped_constraints/asynchronous_fifo.tcl
Warning
In order for constraints to be applied and actually have an effect there are many build tool settings that need to be set correctly. See this article for more information. This is done automatically when using tsfpga.
Register interfaces
Some modules in this project are controlled over a register bus and use hdl-registers to generate register interface code. For example Module dma_axi_write_simple. When using tsfpga, register HDL code is automatically generated and kept up to date in both simulation and build flow.
Manual workflow
When not using tsfpga, VHDL code generation from hdl-registers must be integrated in your simulation and build flow. In order to access the registers on a target device, C or C++ code generation must probably be integrated in your FPGA/software build flow.
Feedback
If you find any bugs or inconsistencies in this project, please start a discussion or create an issue on GitHub.