tsfpga.examples package

Subpackages

Submodules

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.

Parameters:

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

Returns:

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.

Parameters:

default_temp_dir – 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.

Parameters:

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

Parameters:

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

Returns:

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().

Returns:

The module objects.

Return type:

ModuleList

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

exception tsfpga.examples.simulation_utils.NoGitDiffTestsFound

Bases: Exception

Raised by find_git_test_filters() when no tests are found due to no VHDL-related git diff.

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.

Parameters:

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

Parameters:

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

Parameters:

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

Returns:

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.

Returns:

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, modules: ModuleList, vunit_proj: VUnit, ip_core_vivado_project_directory: Path | None = None) → None

Create a configuration file (vhdl_ls.toml) for the rust_hdl VHDL Language Server (https://github.com/VHDL-LS/rust_hdl).

The call is very quick (10-15 ms). Running it from simulate.py, a script that is run “often”, might be a good idea in order to always have an up-to-date vhdl_ls config.

Parameters:

  • output_path – Config file will be placed in this directory.

  • modules – All files from these modules will be added.

  • vunit_proj –

    All files in this VUnit project will be added. This includes the files from VUnit itself, and any user files.

    Warning

    Using a VUnit project with location/check preprocessing enabled might be dangerous, since it introduces the risk of editing a generated file.

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

tsfpga.examples.simulation_utils.find_git_test_filters(args: Namespace, repo_root: Path, modules: ModuleList, modules_no_sim: ModuleList | None = None, reference_branch: str = 'origin/main', **setup_vunit_kwargs: Any) → Namespace

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.

Parameters:
Returns:

An updated argument namespace from which a VUnit project can be created.

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

Get arguments for the simulation flow.

Parameters:

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