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_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 andFalse
otherwise. It will receive theproject
andoutput_path
as arguments. Can beNone
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.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 thehdl-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:
- 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.simulation_utils module
- exception tsfpga.examples.simulation_utils.NoVcsDiffTestsFound
Bases:
Exception
Raised by
find_git_test_filter()
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_test: 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_test – Source and simulation files from these modules will be included in the simulation project, but no testbenches. Provide your dependency modules here, if you have any.
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[VivadoIpCoreProject] | 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_filter(args: Namespace, repo_root: Path, modules: ModuleList, modules_no_test: 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:
args – Command line argument namespace.
repo_root – Path to the repository root. Git commands will be run here.
modules – Will be passed on to
SimulationProject.add_modules()
.modules_no_test – Will be passed on to
SimulationProject.add_modules()
.reference_branch – The name of the reference branch that is used to collect a diff.
setup_vunit_kwargs – Will be passed on to
SimulationProject.add_modules()
.
- Returns:
An updated argument namespace from which a VUnit project can be created.