tsfpga package

A set of reusable functions for working with HDL projects.

Submodules

tsfpga.about module

tsfpga.about.get_doc()

Prepend get_short_doc() to this to get the complete doc.

tsfpga.about.get_readme_rst(include_website_link, verify=True)

Get the complete README.rst for tsfpga (to be used on website and in PyPI release).

Also possible to verify that readme.rst in the project root is identical. RST file inclusion in README.rst does not work on gitlab unfortunately, hence this cumbersome handling where the README is duplicated in two places.

Parameters

  • include_website_link (bool) – Include a link to the website in README.

  • verify (bool) – Verify that the readme.rst in repo root (which is shown on gitlab) corresponds to the string produced by this function.

tsfpga.about.get_short_doc()
tsfpga.about.get_slogan()

tsfpga.build_project_list module

class tsfpga.build_project_list.BuildProjectBuildWrapper(project, collect_artifacts, **kwargs)

Bases: object

Wrapper to build a project, for usage in the build runner. Mimics a VUnit test object.

__init__(project, collect_artifacts, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

property build_result_report_length

The number of lines in the build_result report from this project.

run(output_path, read_output)

VUnit test runner sends another argument “read_output” which we don’t use.

class tsfpga.build_project_list.BuildProjectCreateWrapper(project, **kwargs)

Bases: object

Wrapper to create a build project, for usage in the build runner. Mimics a VUnit test object.

__init__(project, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

run(output_path, read_output)

VUnit test runner sends another argument “read_output” which we don’t use.

class tsfpga.build_project_list.BuildProjectList(modules, project_filters=None, include_netlist_not_top_builds=False, no_color=False)

Bases: object

Interface to handle a list of FPGA build projects. Enables building many projects in parallel.

__init__(modules, project_filters=None, include_netlist_not_top_builds=False, no_color=False)
Parameters

  • modules (list(BaseModule)) – Module objects that can define build projects.

  • project_filters (list(str)) – Project name filters. Can use wildcards (*). Leave empty for all.

  • include_netlist_not_top_builds (bool) – Set True to get only netlist builds, instead of only top level builds.

  • no_color (bool) – Disable color in printouts.

build(projects_path, num_parallel_builds, num_threads_per_build, output_path=None, collect_artifacts=None, **kwargs)

Build all the projects in the list.

Parameters

  • projects_path (pathlib.Path) – The projects will be placed here.

  • num_parallel_builds (int) – The number of projects that will be built in parallel.

  • num_threads_per_build (int) – The number threads that will be used for each parallel build process.

  • output_path (pathlib.Path) – Where the artifacts should be placed.

  • collect_artifacts (function) –

    Callback to collect artifacts. Takes two named arguments:

    project (VivadoProject): The project that is being built.
    output_path (pathlib.Path): Where the artifacts should be placed.
    Must return True.

  • kwargs –

    Other arguments as accepted by VivadoProject.build().

    Note

    Argument project_path can not be set, it is set by this class based on the project_paths argument to this function.

    Argument num_threads is set by the num_threads_per_build argument to this function. This naming difference is done to avoid confusion with regards to num_parallel_builds.

Returns

True if everything went well.

Return type

bool

create(projects_path, num_parallel_builds, **kwargs)

Create build project on disk for all the projects in the list.

Parameters

  • projects_path (pathlib.Path) – The projects will be placed here.

  • num_parallel_builds (int) – The number of projects that will be created in parallel.

  • kwargs –

    Other arguments as accepted by VivadoProject.create().

    Note

    Argument project_path can not be set, it is set by this class based on the project_paths argument to this function.

Returns

True if everything went well.

Return type

bool

create_unless_exists(projects_path, num_parallel_builds, **kwargs)

Create build project for all the projects in the list, unless the project already exists.

Parameters

  • projects_path (pathlib.Path) – The projects will be placed here.

  • num_parallel_builds (int) – The number of projects that will be created in parallel.

  • kwargs –

    Other arguments as accepted by VivadoProject.create().

    Note

    Argument project_path can not be set, it is set by this class based on the project_paths argument to this function.

Returns

True if everything went well.

Return type

bool

open(projects_path)

Open the projects in EDA GUI.

Parameters

projects_path (pathlib.Path) – The projects are placed here.

Returns

True if everything went well.

Return type

bool

class tsfpga.build_project_list.BuildProjectOpenWrapper(project)

Bases: object

Wrapper to open a build project, for usage in the build runner. Mimics a VUnit test object.

__init__(project)

Initialize self. See help(type(self)) for accurate signature.

run(output_path, read_output)

VUnit test runner sends another argument “read_output” which we don’t use.

class tsfpga.build_project_list.BuildReport(printer=<vunit.color_printer.LinuxColorPrinter object>)

Bases: vunit.test.report.TestReport

add_result(*args, **kwargs)

Add a a test result.

Inherited and adapted from the VUnit function. Uses a different Result class.

print_latest_status(total_tests)

This method is called for each build when it should print its result just as it finished, but other builds may not be finished yet.

Inherited and adapted from the VUnit function: * Removed support for the “skipped” result. * Do not use abbreviations in the printout. * Use f-strings.

set_report_length(report_length_lines)
class tsfpga.build_project_list.BuildResult(name, status, time, output_file_name)

Bases: vunit.test.report.TestResult

print_status(printer, padding=0)

This method is called for each build when it should print its result in the “Summary” at the end when all builds have finished.

Inherited and adapted from the VUnit function.

report_length_lines = None
set_report_length(report_length_lines)
class tsfpga.build_project_list.BuildRunner(report, output_path, verbosity=1, num_threads=1, fail_fast=False, dont_catch_exceptions=False, no_color=False)

Bases: vunit.test.runner.TestRunner

Build runner that mimics a VUnit TestRunner. Most things are used as they are in the base class, but some behavior is overridden.

class tsfpga.build_project_list.ThreadSafeCollectArtifacts(collect_artifacts)

Bases: object

A thread-safe wrapper around a user-supplied function that makes sure the function is not launched more than once at the same time. When two builds finish at the same time, race conditions can arise depending on what the function does.

Note that this is a VERY fringe case, since builds usually take >20 minutes, and the collection probably only takes a few seconds. But it happens sometimes with the tsfpga example projects which are identical and quite fast (roughly three minutes).

__init__(collect_artifacts)

Initialize self. See help(type(self)) for accurate signature.

collect_artifacts(project, output_path)

tsfpga.build_step_tcl_hook module

class tsfpga.build_step_tcl_hook.BuildStepTclHook(tcl_file, hook_step)

Bases: object

Represent a TCL file that shall be used as hook in one of the build steps.

__init__(tcl_file, hook_step)
Parameters

  • tcl_file (pathlib.Path) – Path to a TCL file.

  • hook_step (str) – Name of a build step, e.g. “STEPS.ROUTE_DESIGN.TCL.PRE”.

property step_is_synth

True if the build step is in synthesis. False otherwise.

tsfpga.constraint module

class tsfpga.constraint.Constraint(file, used_in='all', scoped_constraint=False, processing_order='normal')

Bases: object

Class for handling a constraint file.

Can handle the regular global constraint files as well as scoped constraints. For the latter to work the constraint file name must be the same as the .vhd file name, which must be the same as the entity name.

__init__(file, used_in='all', scoped_constraint=False, processing_order='normal')
Parameters

  • file (pathlib.Path) – Path to the constraint file. Typically ends in .xdc or .tcl.

  • used_in (str) – Optionally the constraint can be enabled only for “synth” or “impl”.

  • scoped_constraint (bool) – If enabled the constraint file will be loaded with the “-ref” argument in Vivado. An entity with the same name must exist.

  • processing_order (str) – Optionally the processing order can be changed to “early” or “late”.

validate_scoped_entity(source_files)

Make sure that a matching entity file exists in case this is a scoped constraint. The list of source files should be the synthesis files for the module that this constraint belongs to.

tsfpga.create_vhdl_ls_config module

tsfpga.create_vhdl_ls_config.create_configuration(output_path, modules=None, vunit_proj=None, vivado_location=None, ip_core_vivado_project_directory=None)

Create a configuration file (vhdl_ls.toml) for the rust_hdl VHDL Language Server.

Can be used with modules and an “empty” VUnit project, or with a complete VUnit project with all user files added.

Execution of this function takes roughly 12 ms for a large project (62 modules and a VUnit project).

Parameters

  • output_path (pathlib.Path) – Output folder.

  • modules – A list of Module objects.

  • vunit_proj – A VUnit project.

  • vivado_location (pathlib.Path) – Vivado binary path. Will add unisim from this Vivado installation.

  • ip_core_vivado_project_directory (pathlib.Path) – Path to a Vivado project that contains generated “simulation” and “synthesis” files of IP cores (the “generate_target” TCL command). See simulate.py for an example of using this.

tsfpga.git_simulation_subset module

class tsfpga.git_simulation_subset.GitSimulationSubset(repo_root, reference_branch, vunit_proj, vunit_preprocessed_path=None, modules=None)

Bases: object

Find a subset of testbenches to simulate based on git history.

__init__(repo_root, reference_branch, vunit_proj, vunit_preprocessed_path=None, modules=None)
Parameters

  • repo_root (pathlib.Path) – Root directory where git commands will be run.

  • reference_branch (str) – What git branch to compare against, when finding what files have changed. Typically “origin/master”.

  • vunit_proj – A vunit project with all source files and testbenches added. Will be used for dependency scanning.

  • vunit_preprocessed_path (pathlib.Path) – If location/check preprocessing is enabled in your VUnit project, supply the path to vunit_out/preprocessed.

  • modules (ModuleList) – A list of modules that are included in the VUnit project. Must be supplied only if preprocessing is enabled.

find_subset()

Return all testbenches that have changes, or depend on files that have changes.

Returns

The testbench names and their corresponding library names. A list of tuples (“testbench name”, “library name”).

Return type

list(tuple(str, str))

tsfpga.git_utils module

tsfpga.git_utils.find_git_files(directory, exclude_directories=None, file_endings_include=None, file_endings_avoid=None)

Find files that are checked in to git.

Parameters

  • directory (pathlib.Path) – Search in this directory.

  • exclude_directories (list(pathlib.Path)) – Files in these directories will not be included.

  • file_endings_include (str or tuple(str)) –

  • file_endings_avoid (str or tuple(str)) – String or tuple of strings. Files with these endings will not be included.

Returns

The files that are available in git.

Return type

list(pathlib.Path)

tsfpga.git_utils.get_git_commit(directory)

Generally, eight to ten characters are more than enough to be unique within a project. The linux kernel, one of the largest projects, needs 11. https://git-scm.com/book/en/v2/Git-Tools-Revision-Selection#Short-SHA-1

tsfpga.git_utils.git_commands_are_available(directory)

True if “git” command executable is available, and directory is in a valid git repo.

tsfpga.hdl_file module

class tsfpga.hdl_file.HdlFile(path)

Bases: object

Class for representing a HDL source code file.

__init__(path)
Parameters

path (pathlib.Path) – Path to a HDL source code file.

file_endings = ('.vhd', '.v', '.vh')
property is_verilog_header

True if the file is a Verilog header file. Otherwise False.

property is_verilog_source

True if the file is a Verilog source file. Otherwise False.

property is_vhdl

True if the file is a VHDL file. Otherwise False.

verilog_header_file_ending = '.vh'
verilog_source_file_ending = '.v'
vhdl_file_ending = '.vhd'

tsfpga.ip_core_file module

class tsfpga.ip_core_file.IpCoreFile(path, **variables)

Bases: object

Class for handling an IP core file.

__init__(path, **variables)
Parameters

  • path (pathlib.Path) – Path to the TCL script that creates the IP. Should typically end in .tcl.

  • variables –

    These name/value variable pairs will be set in TCL before the IP core .tcl file is sourced. This makes it possible to parameterize the IP core creation.

    Note

    This is a “kwargs” style argument. You can pass any number of named arguments.

property name

A shorthand name for this IP core.

Type

str

tsfpga.module module

class tsfpga.module.BaseModule(path, library_name, default_registers=None)

Bases: object

Base class for handling a HDL module with RTL code, constraints, etc.

Files are gathered from a lot of different subfolders, to accommodate for projects having different catalog structure.

__init__(path, library_name, default_registers=None)
Parameters
add_vunit_config(test, name=None, generics=None, set_random_seed=False, pre_config=None, post_check=None)

Add config for VUnit test case. Wrapper that sets a suitable name and can set a random seed generic.

Parameters

  • test – VUnit test object. Can be testbench or test case.

  • name (str) – Optional designated name for this config. Will be used to form the name of the config together with the generics value.

  • generics (dict) – Generic values that will be applied to the testbench entity. The values will also be used to form the name of the config.

  • set_random_seed (bool, int) –

    Controls setting of the seed generic:

    • When this argument is not assigned, or assigned False, the generic will not be set.

    • When set to boolean True, a random natural (non-negative integer) generic value will be set.

    • When set to an integer value, that value will be set for the generic. This is useful to get a static test case name for waveform inspection.

    If the generic is to be set it must exist in the testbench entity, and should have VHDL type natural.

  • pre_config – Function to be run before the test. See VUnit documentation for details.

  • post_check – Function to be run after the test. See VUnit documentation for details.

create_regs_vhdl_package()

Create a VHDL package in this module with register definitions.

get_build_projects()

Get FPGA build projects defined by this module.

Note

This default method does nothing. Should be overridden by modules that set up build projects.

Returns

FPGA build projects.

Return type

list(VivadoProject)

get_ip_core_files(files_include=None, files_avoid=None, **kwargs)

Get IP cores for this module.

Note that the ip_core_file.IpCoreFile class accepts a variables argument that can be used to parameterize IP core creation. By overloading this method in a child class you can pass on kwargs arguments from the build/simulation flow to ip_core_file.IpCoreFile creation to achieve this parameterization.

Parameters

  • files_include (set(pathlib.Path)) – Optionally filter to only include these files.

  • files_avoid (set(pathlib.Path)) – Optionally filter to discard these files.

  • kwargs – Further parameters that can be sent by build/simulation flow to control what IP cores are included and what their variables are.

Returns

The IP cores for this module.

Return type

list(IpCoreFile)

get_scoped_constraints(files_include=None, files_avoid=None, **kwargs)

Constraints that shall be applied to a certain entity within this module.

Parameters

  • files_include (set(pathlib.Path)) – Optionally filter to only include these files.

  • files_avoid (set(pathlib.Path)) – Optionally filter to discard these files.

  • kwargs – Further parameters that can be sent by build/simulation flow to control what constraints are included.

Returns

The constraints.

Return type

list(Constraint)

get_simulation_files(include_tests=True, files_include=None, files_avoid=None, **kwargs)

See get_synthesis_files() for instructions on how to use files_include and files_avoid.

Parameters

  • include_tests (bool) – When False the test folder, where testbenches usually reside, is not included. The sim folder is always included.

  • files_include (set(pathlib.Path)) – Optionally filter to only include these files.

  • files_avoid (set(pathlib.Path)) – Optionally filter to discard these files.

  • kwargs – Further parameters that can be sent by simulation flow to control what files are included.

Returns

Files that should be included in a simulation project.

Return type

list(HdlFile)

get_synthesis_files(files_include=None, files_avoid=None, **kwargs)

Get a list of files that shall be included in a synthesis project.

The files_include and files_avoid arguments can be used to filter what files are included. This can be useful in many situations, e.g. when encrypted files of files that include an IP core shall be avoided. It is recommended to overload this function in a child class in your module_*.py, and call this super method with the arguments supplied.

Parameters

  • files_include (set(pathlib.Path)) – Optionally filter to only include these files.

  • files_avoid (set(pathlib.Path)) – Optionally filter to discard these files.

  • kwargs – Further parameters that can be sent by build flow to control what files are included.

Returns

Files that should be included in a synthesis project.

Return type

list(HdlFile)

pre_build(project, **kwargs)

This method hook will be called before an FPGA build is run. A typical use case for this mechanism is to set a register constant or default value based on the generics that are passed to the project. Could also be used to, e.g., generate BRAM init files based on project information, etc.

Note

This default method does nothing. Should be overridden by modules that utilize this mechanism.

Parameters
Returns

True if everything went well.

Return type

bool

property registers

Get the registers for this module. Can be None if no TOML file exists and no hook creates registers.

Type

hdl_registers.register_list.RegisterList

registers_hook()

This function will be called directly after creating this module’s registers from the TOML definition file. If the TOML file does not exist this hook will still be called, but the module’s registers will be None.

This is a good place if you want to add or modify some registers from Python. Override this method and implement the desired behavior in a child class.

Note

This default method does nothing. Shall be overridden by modules that utilize this mechanism.

setup_vunit(vunit_proj, **kwargs)

Setup local configuration of this module’s test benches.

Note

This default method does nothing. Should be overridden by modules that have any test benches that operate via generics.

Parameters

  • vunit_proj – The VUnit project that is used to run simulation.

  • kwargs – Use this to pass an arbitrary list of arguments from your simulate.py to the module where you set up your tests. This could be, e.g., data dimensions, location of test files, etc.

static test_case_name(name=None, generics=None)

Construct a string suitable for naming test cases.

Parameters

  • name (str) – Optional base name.

  • generics (dict) – Dictionary of values that will be included in the name.

Returns

For example MyBaseName.GenericA_ValueA.GenericB_ValueB.

Return type

str

tsfpga.module.get_hdl_modules(names_include=None, names_avoid=None)

Wrapper of get_modules() which returns the hdl_modules module objects. If this is a PyPI release of tsfpga, a release of hdl_modules will be bundled and modules from there will be returned.

If this is a repo checkout of tsfpga, the function will try to find the hdl_modules repo if it is next to the tsfpga repo.

If neither of those alternatives work, the function will assert False.

Arguments will be passed on to get_modules().

Returns

The module objects.

Return type

ModuleList

tsfpga.module.get_modules(modules_folders, names_include=None, names_avoid=None, library_name_has_lib_suffix=False, default_registers=None)

Get a list of Module objects based on the source code folders.

Parameters

  • modules_folders (list(pathlib.Path)) – A list of paths where your modules are located.

  • names_include (list(str)) – If specified, only modules with these names will be included.

  • names_avoid (list(str)) – If specified, modules with these names will be discarded.

  • library_name_has_lib_suffix (bool) – If set, the library name will be <module name>_lib, otherwise it is just <module name>.

  • default_registers (list(hdl_registers.register.Register)) – Default registers.

Returns

List of module objects (BaseModule or child classes thereof) created from the specified folders.

Return type

ModuleList

tsfpga.module_documentation module

class tsfpga.module_documentation.ModuleDocumentation(module)

Bases: object

Methods for generating a reStructuredText document with module documentation. The content is extracted from VHDL source file headers.

__init__(module)
Parameters

module (BaseModule) – The module which shall be documented.

create_rst_document(output_path, exclude_module_folders=None)

Create an .rst file in output_path with the content from get_rst_document(). If the module has registers, the HTML page will also be generated in output_path, so that e.g. sphinx can be run directly.

Parameters

  • output_path (pathlib.Path) – Document will be placed here.

  • exclude_module_folders (list(str)) – Folder names within the module root that shall be excluded from documentation.

get_overview_rst()

Get the contents of the module’s doc/<name>.rst, i.e. the module “overview” document.

Returns

Module overview RST. None if file does not exist.

Return type

str

get_register_rst(heading_character)

Get an RST snippet with a link to the module’s register documentation, if available. Note that this will create an RST :download: statement to the register .html page. When building, the .html file must be present in the same directory as the .rst file. This is done automatically by create_rst_document().

Parameters

heading_character (str) – Character to use for heading underline.

Returns

RST snippet with link to register HTML. None if module does not have registers.

Return type

str

get_rst_document(exclude_module_folders=None)

Get a complete RST document with the content of get_overview_rst(), get_register_rst(), and get_submodule_rst(), as well as a top level heading.

Parameters

exclude_module_folders (list(str)) – Folder names within the module root that shall be excluded from documentation.

Returns

An RST document.

Return type

str

get_submodule_rst(heading_character, heading_character_2, exclude_files=None, exclude_module_folders=None)

Get RST code with documentation of the different sub-modules (files) of the module. Contains documentation that is extracted from the file headers, as well as a symbolator symbol of the entity.

Parameters

  • heading_character (str) – Character to use for heading underline.

  • heading_character_2 (str) – Character to use for next level of heading underline.

  • exclude_files (set(pathlib.Path)) – Files that shall be excluded from the documentation.

  • exclude_module_folders (list(str)) – Folder names within the module root that shall be excluded from documentation. For example, if you chosen module structure places only netlist build wrappers in the “rtl/” folder within modules, and you do not want them included in the documentation, then pass the argument [“rtl”].

Returns

RST code with sub-module documentation.

Return type

str

tsfpga.module_list module

class tsfpga.module_list.ModuleList

Bases: object

Wrapper for a list of modules, with convenience functions.

__init__()

Initialize self. See help(type(self)) for accurate signature.

append(module)

Append a module to the list.

copy()

Create a shallow copy of the module list. This public function is available as a convenience and to mimic the interface of a regular python list.

get(module_name)

Get the module with the specified name. If no module matched, an exception is raised.

tsfpga.svn_utils module

tsfpga.svn_utils.check_that_svn_commands_are_available(cwd=None)
tsfpga.svn_utils.find_svn_files(directory, excludes=None, file_endings_include=None, file_endings_avoid=None)

Find files that are checked in to SVN. It runs “svn status” rather than “svn ls”. This means that it is a local operation, that does not require credentials or any connection with an SVN server.

Parameters

  • directory (pathlib.Path) – Search in this directory.

  • excludes (list(pathlib.Path)) – These files and folders will not be included.

  • file_endings_include (str or tuple(str)) –

  • file_endings_avoid (str or tuple(str)) – String or tuple of strings. Files with these endings will not be included.

Returns

The files that are available in SVN.

Return type

list(pathlib.Path)

tsfpga.svn_utils.get_svn_revision(cwd=None)
tsfpga.svn_utils.get_svn_revision_information(cwd=None)
tsfpga.svn_utils.svn_commands_are_available(cwd=None)
tsfpga.svn_utils.svn_local_changes_are_present(cwd=None)

Return true if the repo contains changes that have been made after the last commit. Info from here: https://rubyinrails.com/2014/01/11/svn-command-to-check-modified-files/

tsfpga.system_utils module

tsfpga.system_utils.create_directory(directory, empty=True)
tsfpga.system_utils.create_file(file, contents=None)
tsfpga.system_utils.delete(path, wait_until_deleted=False)

Delete a file or directory from the filesystem.

Parameters

  • path (pathlib.Path) – The file/directory to be deleted.

  • wait_until_deleted (bool) – When set to True, the function will poll the filesystem after initiating the deletion, and not return until the path is in fact deleted. Is needed on some filesystems/mounts in a situation where we delete a path and then directly want to write to it afterwards.

Returns

The path that was deleted (i.e. the original path argument).

Return type

pathlib.Path

tsfpga.system_utils.file_is_in_directory(file_path, directories)

Check if the file is in any of the directories.

Parameters
Returns

True if there is a common path.

Return type

bool

tsfpga.system_utils.load_python_module(file)
tsfpga.system_utils.path_relative_to(path, other)

Note Path.relative_to() does not support the use case where e.g. readme.md should get relative path “../readme.md”. Hence we have to use os.path.

tsfpga.system_utils.read_file(file)
tsfpga.system_utils.read_last_lines_of_file(file, num_lines)

Read a number of lines from the end of a file, without buffering the whole file. Similar to unix tail command.

Parameters

  • file (pathlib.Path) – The file that shall be read.

  • num_lines (int) – The number of lines to read.

Returns

The last lines of the file.

Return type

str

tsfpga.system_utils.run_command(cmd, cwd=None, env=None)
tsfpga.system_utils.system_is_windows()

tsfpga.vhdl_file_documentation module

class tsfpga.vhdl_file_documentation.VhdlFileDocumentation(vhd_file_path)

Bases: object

Methods to extract documentation from a VHDL source file.

__init__(vhd_file_path)
Parameters

vhd_file_path (pathlib.Path) – Path to the VHDL file which shall be documented.

get_header_rst()

Get the contents of the VHDL file’s header. This means everything that is in the comment block at the start of the file, after the copyright notice.

Returns

File header content.

Return type

str

get_symbolator_component()

Return a string with a component declaration equivalent to the entity declaration within the file. (We use entity’s but symbolator requires component’s).

Default values and range declarations on ports are removed since symbolator does not seem to handle them.

Returns

VHDL component declaration. None if file is a package, and hence contains no entity.

Return type

str