tsfpga package

Subpackages

Submodules

tsfpga.about module

tsfpga.about.get_doc()

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

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

class tsfpga.formal_project.FormalConfig(top, generics=None, engine_command='smtbmc', solver_command='z3', mode='bmc', depth=20)

Bases: object

__init__(top, generics=None, engine_command='smtbmc', solver_command='z3', mode='bmc', depth=20)
Parameters

  • top (str) – Name of top level entity.

  • generics (dict) – Generics that will be applied to the top level.

  • engine_command (str) – Engine command, e.g. smtbmc --syn --nopresat

  • solver_command (str) – Solver command, e.g. z3 rewriter.cache_all=true opt.enable_sat=true

  • mode (str) – Typically bmc or prove.

  • depth (int) – In bmc mode, this parameter is the depth of the bounded model check. In prove mode it is ignored for all engines except smtbmc where it is used as the depth for k-induction.

property test_name
class tsfpga.formal_project.FormalProject(project_path, modules)

Bases: object

__init__(project_path, modules)
add_config(**kwargs)
list_tests(test_filters='*')
run(num_threads=1, verbose=False, quiet=False, no_color=False, test_filters=None)
class tsfpga.formal_project.FormalTestCase(formal_config)

Bases: object

__init__(formal_config)
property name
run(output_path, read_output)

VUnit test runner sends another argument “read_output” which we don’t use. It can be used to read back the STDOUTput from a test. Typically used in a post test hook.

set_compiled_libraries(compiled_libraries)
set_src_files(src_files)

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

  • path (pathlib.Path) – Path to the module folder.

  • library_name (str) – VHDL library name.

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

add_vunit_config(test, name=None, generics=None, pre_config=None, post_check=None)

Add config for VUnit test case. Wrapper that sets a suitable name.

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_formal_files(files_include=None, files_avoid=None, **kwargs)

Returns the files to be used for formal verification. By default these are the same that are used by synthesis (by calling get_synthesis_files()). Overload this method to select files manually.

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

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 formal flow to control what files are included.

Returns

Files that should be included in a formal verification project.

Return type

list(HdlFile)

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 is not included. The use case is when testing a primary module that depends on other secondary modules. In this case we may want to compile the simulation files (sim folder) of the secondary modules but not their test files (test folder).

    Note

    The test files are considered private to the module and should never be used by other modules.

  • 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

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_formal(formal_proj, **kwargs)

Setup this module’s formal tests.

Note

This default method does nothing. Should be overridden by modules that utilize formal verification.

Parameters

  • formal_proj – The formal project that is being used.

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

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.

Example result: MyName.GenericA_ValueA.GenericB_ValueB

tsfpga.module.get_module_object(path, name, library_name_has_lib_suffix, default_registers)
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(Register)) – Default registers.

Returns

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

Return type

ModuleList

tsfpga.module.iterate_module_folders(modules_folders)

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)

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.

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

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.

Returns

An RST document.

Return type

str

get_submodule_rst(heading_character, exclude_files=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.

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__()
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.sby_writer module

class tsfpga.sby_writer.SbyWriter

Bases: object

Writes a SymbiYosys script file

static write_sby(output_path, top, formal_settings, compiled_libraries, src_files, generics=None)

Create SymbiYosys script. This script will run ghdl –synth

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)
tsfpga.system_utils.file_is_in_directory(file_path, directories)

Check if the file is in any of the directories.

Parameters

  • file_path (pathlib.Path) – The file to be checked.

  • directories (list(pathlib.Path)) – The directories to be controlled.

Returns

True if there is a comon path.

Return type

bool

tsfpga.system_utils.load_python_module(file)
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)
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

tsfpga.yosys_project module

class tsfpga.yosys_project.YosysProject(top=None, generics=None, formal_settings=None)

Bases: object

Used for handling a Yosys poject, synthesized with GHDL. Currently supports formal verification, but has no real build support.

__init__(top=None, generics=None, formal_settings=None)
run_formal(project_path, src_files, compiled_libraries)

Module contents

A set of reusable functions for working with HDL projects.