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.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.- 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_sim – Will be passed on to
SimulationProject.add_modules()
.reference_branch (str) – 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:
A list of VUnit test case filters.
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.
- 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, 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.
- Parameters:
output_path – Config file will be placed in this directory.
temp_files_path – Some temporary files will be stored in a folder within this directory.
modules – These modules will be added.
ip_core_vivado_project_directory – Vivado IP core files in this location will be added.