tsfpga.examples package



tsfpga.examples.build_fpga module

tsfpga.examples.build_fpga.collect_artifacts(project: VivadoProject, output_path: Path) bool

Example of a method to collect build artifacts. Will create a zip file with the bitstream, hardware definition (.xsa) and register documentation.

  • project – Project object that has been built, and who’s artifacts shall now be collected.

  • output_path – Path to the build output. Artifact zip will be placed here as well.


True if everything went well.

tsfpga.examples.build_fpga.main() None

Main function for building FPGA projects. If you are setting up a new build flow from scratch, you probably want to copy and modify this function, and reuse the others.

tsfpga.examples.build_fpga_utils module

tsfpga.examples.build_fpga_utils.arguments(default_temp_dir: Path) Namespace

Setup of arguments for the example build flow.


default_temp_dir (pathlib.Path) – Default value for output paths.

tsfpga.examples.build_fpga_utils.generate_register_artifacts(modules: ModuleList, output_path: Path) None

Generate register artifacts from the given modules.

  • modules – Registers from these modules will be included.

  • output_path – Register artifacts will be placed here.

tsfpga.examples.build_fpga_utils.setup_and_run(modules: ModuleList, projects: BuildProjectList, args: Namespace, collect_artifacts_function: Callable[[VivadoProject, Path], bool] | None) int

Setup and execute build projects. As instructed by the arguments.

  • modules – When running a register generation, registers from these modules will be included.

  • projects – These build projects will be built.

  • args – Command line argument namespace.

  • collect_artifacts_function – Function pointer to a function that collects build artifacts. Will be run after a successful implementation build. The function must return True if successful and False otherwise. It will receive the project and output_path as arguments. Can be None if no special artifact collection operation shall be run.


0 if everything passed, otherwise non-zero. Can be used for system exit code.

tsfpga.examples.build_module_documentation module

tsfpga.examples.build_module_documentation.generate_documentation() None
tsfpga.examples.build_module_documentation.main() None

tsfpga.examples.conf module

Configuration file for the Sphinx documentation builder. For building documentation of the example modules.

tsfpga.examples.example_env module

Common functions and definitions in the example build environment.

tsfpga.examples.example_env.get_default_registers() list[Register]

Default registers for tsfpga examples.

tsfpga.examples.example_env.get_hdl_modules(names_include: set[str] | None = None, names_avoid: set[str] | None = None) ModuleList

Wrapper of get_modules() which returns the hdl-modules module objects (https://hdl-modules.com), if available.

If hdl-modules can not be found in the default repo checkout location, the function will assert False.

Arguments will be passed on to get_modules().


The module objects.

Return type:


tsfpga.examples.example_env.get_tsfpga_example_modules(names_include: set[str] | None = None, names_avoid: set[str] | None = None) ModuleList

Wrapper of the regular get_modules(). call with correct settings for tsfpga example modules. This will include the example tsfpga modules, but not the “real” modules.

Arguments will be passed on to get_modules().

tsfpga.examples.example_pythonpath module

Import this file in order to have the default locations of the hdl-registers/hdl-registers and vunit/vunit repos added to PYTHONPATH.

tsfpga.examples.simulate module

tsfpga.examples.simulate.find_git_test_filters(args: Namespace, repo_root: Path, modules: ModuleList, modules_no_sim: ModuleList | None = None, reference_branch: str = 'origin/master', **setup_vunit_kwargs: Any) list[str]

Construct a VUnit test filter that will run all test cases that are affected by git changes. The current git state is compared to a reference branch, and differences are derived. See GitSimulationSubset for details.


A list of VUnit test case filters.

tsfpga.examples.simulate.main() None

Main function for the simulation flow. If you are setting up a new simulation environment you probably want to copy and modify this function. The other functions and classes should be reusable in most cases.

tsfpga.examples.simulation_utils module

class tsfpga.examples.simulation_utils.SimulationProject(args: Namespace, enable_preprocessing: bool = False)

Bases: object

Class for setting up and handling a VUnit simulation project. Should be reusable in most cases.

__init__(args: Namespace, enable_preprocessing: bool = False) None

Create a VUnit project, configured according to the given arguments.

  • args – Command line argument namespace from simulate.py.

  • enable_preprocessing – If True, VUnit location/check preprocessing will be enabled.

add_modules(modules: ModuleList, modules_no_sim: ModuleList | None = None, include_vhdl_files: bool = True, include_verilog_files: bool = True, include_systemverilog_files: bool = True, **setup_vunit_kwargs: Any) None

Add module source files to the VUnit project.

  • modules – These modules will be included in the simulation project.

  • modules_no_sim – These modules will be included in the simulation project, but their test files will not be added.

  • include_vhdl_files – Optionally disable inclusion of VHDL files from the modules.

  • include_verilog_files – Optionally disable inclusion of Verilog files from the modules.

  • include_systemverilog_files – Optionally disable inclusion of SystemVerilog files from the modules.

  • setup_vunit_kwargs – Further arguments that will be sent to BaseModule.setup_vunit() for each module. Note that this is a “kwargs” style argument; any number of named arguments can be sent.

add_vivado_ip_cores(modules: ModuleList, vivado_part_name: str = 'xc7z020clg400-1', vivado_ip_core_project_class: Type[Any] | None = None) Path | None

Generate IP cores from the modules, unless instructed not to by args. When running with a commercial simulator they will be added to the VUnit project.

  • modules – IP cores from these modules will be included in the simulation project.

  • vivado_part_name – Part name to be used for Vivado IP core project. Might have to change from default depending on what parts you have available in your Vivado installation.

  • vivado_ip_core_project_class – Class to be used for Vivado IP core project. Can be left at default in most cases.


Path to the Vivado IP core project’s project directory. None if Vivado IP cores were not added due to command line argument.

add_vivado_simlib() VivadoSimlibCommon | None

Add Vivado simlib to the VUnit project, unless instructed not to by args. Will compile simlib if necessary.


The simlib object, None if simlib was not added due to command line argument.

tsfpga.examples.simulation_utils.create_vhdl_ls_configuration(output_path: Path, temp_files_path: Path, modules: ModuleList, ip_core_vivado_project_directory: Path | None = None) None

Create config for vhdl_ls (https://github.com/VHDL-LS/rust_hdl). Granted this might no be the “correct” place for this functionality. But since the call is somewhat quick (~10 ms), and simulate.py is run “often” it seems an appropriate place in order to always have an up-to-date vhdl_ls config.

  • output_path – Config file will be placed here.

  • temp_files_path – Some temporary files will be placed here.

  • modules – These modules will be added.

  • ip_core_vivado_project_directory – Vivado IP core files in this location will be added.

tsfpga.examples.simulation_utils.get_arguments_cli(default_output_path: Path) VUnitCLI

Get arguments for the simulation flow.


default_output_path (pathlib.Path) – Will be set as default for output path arguments (both VUnit files and Vivado files).