tsfpga.examples package

Subpackages

Submodules

tsfpga.examples.build_fpga module

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_single_project module

Build FPGA projects from the command line. Note that this is an example script that illustrates how FPGA build projects can be built one by one. This is not the recommended standard build flow, see ‘build_fpga.py’ instead.

The benefit of building one by one is that build status is written directly to STDOUT.

tsfpga.examples.build_fpga_single_project.main() → None

Main function for building single FPGA projects. Note that this is not the recommended standard build flow, see ‘build_fpga.py’ instead.

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

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

Note that this is not the recommended standard build flow, see ‘build_fpga.py’ instead.

Note that this functions is a modified clone of the one in ‘build_fpga_utils.py’.

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_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 (can be overridden by command line argument).

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

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

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.generate_register_artifacts(modules: ModuleList, output_path: Path) → None

Example of a function to generate register artifacts from the given modules. Will generate pretty much all register artifacts available. In your own build flow you might want to only generate a subset of these.

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, project_list: BuildProjectList, args: argparse.Namespace, collect_artifacts_function: Callable[[VivadoProject, Path], bool] | None) → int

Example of a function to setup and execute build projects. As instructed by the arguments.

Parameters:

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

  • project_list – 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. Which is typically the case for synthesis-only builds such as netlist builds.

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

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

tsfpga.examples.simulation_utils.set_git_test_pattern(args: Namespace, repo_root: Path, vunit_proj: VUnit, modules: ModuleList, reference_branch: str = 'origin/main') → bool

Update the VUnit project’s test pattern to run everything that has a difference in the local git tree compared to a reference branch.

Parameters:

  • args – Command line argument namespace.

  • repo_root – Path to the repository root. Git commands will be run here.

  • vunit_proj – The test pattern of this VUnit project will be updated.

  • modules – Will look for changes in these modules’ register data files also.

  • reference_branch – Changes in the local tree compared to this branch will be simulated.

Returns:

True if any HDL-related changes were found in git.