tsfpga.vivado package

Submodules

tsfpga.vivado.build_result module

class tsfpga.vivado.build_result.BuildResult(name)

Bases: object

project_name

The name of the build.

Type

str

success

True if the build and all pre- and post hooks succeeded.

Type

bool

synthesis_size

A dictionary with the utilization of primitives for the synthesized design. Will be None if synthesis failed or did not run.

Type

dict

implementation_size

A dictionary with the utilization of primitives for the implemented design. Will be None if implementation failed or did not run.

Type

dict

maximum_logic_level

The maximum level in the the logic level distribution. Will be None if synthesis failed or did not run.

Type

int

__init__(name)

Parameters

name (str) – The name of the build.

property logic_level_distribution

A table with logic level distribution as reported by Vivado. Will be None if synthesis failed or did not run.

Type

str

report()

Return a report of the build result. Includes all metrics and information that has been extracted from the Vivado reports.

Returns

The report.

Return type

str

size_summary()

Return a string with a formatted message of the size.

Returns

A human-readable message of the latest size. None if no size is set.

Return type

str

tsfpga.vivado.build_result_checker module

class tsfpga.vivado.build_result_checker.BuildResultChecker(limit)

Bases: object

Check a build result value against a limit.

Overload and implement the check method according to the resource you want to check.

__init__(limit)

Parameters

limit – The limit that the specified resource shall be checked against. Should be e.g. a LessThan object.

check(build_result)

Parameters

build_result (tsfpga.vivado.build_result.BuildResult) – Build result that shall be checked.

Returns

True if check passed, false otherwise.

Return type

bool

class tsfpga.vivado.build_result_checker.DspBlocks(limit)

Bases: tsfpga.vivado.build_result_checker.SizeChecker

In Vivado pre-2020.1 the resource was called “DSP48 Blocks” in the utilization report. After that it is called “DSP Blocks”. This class checks for both.

check(build_result)

Same as parent class, but checks for the legacy name as well as the current name.

name = 'DSP Blocks'

class tsfpga.vivado.build_result_checker.EqualTo(value)

Bases: object

Limit to be used with a checker to see that a figure is equal to the specified value.

__init__(value)

Parameters

value (int) – The result value shall be equal to this.

check(result_value)

class tsfpga.vivado.build_result_checker.Ffs(limit)

Bases: tsfpga.vivado.build_result_checker.SizeChecker

name = 'FFs'

class tsfpga.vivado.build_result_checker.LessThan(value)

Bases: object

Limit to be used with a checker to see that a figure is less than the specified value.

__init__(value)

Parameters

value (int) – The result value shall be less than this.

check(result_value)

class tsfpga.vivado.build_result_checker.LogicLuts(limit)

Bases: tsfpga.vivado.build_result_checker.SizeChecker

name = 'Logic LUTs'

class tsfpga.vivado.build_result_checker.LutRams(limit)

Bases: tsfpga.vivado.build_result_checker.SizeChecker

name = 'LUTRAMs'

class tsfpga.vivado.build_result_checker.MaximumLogicLevel(limit)

Bases: tsfpga.vivado.build_result_checker.BuildResultChecker

Check the maximum logic level of a build result against a limit.

check(build_result)

Parameters

build_result (tsfpga.vivado.build_result.BuildResult) – Build result that shall be checked.

Returns

True if check passed, false otherwise.

Return type

bool

name = 'Maximum logic level'

class tsfpga.vivado.build_result_checker.Ramb18(limit)

Bases: tsfpga.vivado.build_result_checker.SizeChecker

name = 'RAMB18'

class tsfpga.vivado.build_result_checker.Ramb36(limit)

Bases: tsfpga.vivado.build_result_checker.SizeChecker

name = 'RAMB36'

class tsfpga.vivado.build_result_checker.SizeChecker(limit)

Bases: tsfpga.vivado.build_result_checker.BuildResultChecker

Check a build result size value against a limit.

Overload and set the correct name, according to the names in the vendor utilization report.

Note that since this is to be used by netlist builds it checks the synthesized size, not the implemented one, even if available.

check(build_result)

Parameters

build_result (tsfpga.vivado.build_result.BuildResult) – Build result that shall be checked.

Returns

True if check passed, false otherwise.

Return type

bool

name = ''

class tsfpga.vivado.build_result_checker.Srls(limit)

Bases: tsfpga.vivado.build_result_checker.SizeChecker

name = 'SRLs'

class tsfpga.vivado.build_result_checker.TotalLuts(limit)

Bases: tsfpga.vivado.build_result_checker.SizeChecker

name = 'Total LUTs'

class tsfpga.vivado.build_result_checker.Uram(limit)

Bases: tsfpga.vivado.build_result_checker.SizeChecker

name = 'URAM'

tsfpga.vivado.common module

tsfpga.vivado.common.get_git_sha_slv(git_directory)

Get the current git SHA encoded as 32-character binary strings. Suitable for setting as std_logic_vector generics to a Vivado build, where they can be assigned to software-accessible registers to keep track of what revision an FPGA was built from.

Will return the left-most 16 characters of the git SHA, encoded into two 32-character strings.

Parameters

directory (pathlib.Path) – The directory where git commands will be run.

Returns

First object in tuple is the left-most eight characters of the git SHA encoded as a 32-character binary string. Second object is the next eight characters from the git SHA.

Return type

tuple(str, str)

tsfpga.vivado.common.get_vivado_path(vivado_path=None)

Wrapper to get a path to Vivado executable.

Parameters

vivado_path (pathlib.Path) – Path to vivado executable. Set to None to use whatever is available in the system PATH.

Returns

The path.

Return type

pathlib.Path

tsfpga.vivado.common.get_vivado_version(vivado_path=None)

Get the version number of the Vivado installation.

Parameters

vivado_path (pathlib.Path) – Path to vivado executable. Set to None to use whatever is available in the system PATH.

Returns

The version, e.g. "2021.2".

Return type

str

tsfpga.vivado.common.run_vivado_gui(vivado_path, project_file)

Setting cwd ensures that any .log or .jou files produced are placed in the same directory as the project.

Parameters

• vivado_path (pathlib.Path) – Path to Vivado executable. Can set to None to use whatever version is in PATH.

• project_file (pathlib.Path) – Path to a project .xpr file.

Returns

True if everything went well.

Return type

bool

tsfpga.vivado.common.run_vivado_tcl(vivado_path, tcl_file, no_log_file=False)

Setting cwd ensures that any .log or .jou files produced are placed in the same directory as the TCL file that produced them.

Parameters

• vivado_path (pathlib.Path) – Path to Vivado executable. Can set to None to use whatever version is in PATH.

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

Returns

True if everything went well.

Return type

bool

tsfpga.vivado.common.to_tcl_path(path)

Return a path string in a format suitable for TCL.

tsfpga.vivado.generics module

class tsfpga.vivado.generics.BitVectorGenericValue(value)

Bases: object

Use this type for generic values of type std_logic_vector.

__init__(value)

Parameters

value (str) – A string of variable length containing only “1” or “0”.

property length

The number of bits in the vector.

Type

int

class tsfpga.vivado.generics.StringGenericValue(value)

Bases: object

Use this type for generic values of type string.

__init__(value)

Parameters

value (str) – A string of variable length with any content.

tsfpga.vivado.generics.get_vivado_tcl_generic_value(value)

Convert generic values of different types to the format recognized by Vivado TCL: https://www.xilinx.com/support/answers/52217.html

Parameters

value (bool, int, float, StringGenericValue, BitVectorGenericValue) – A generic value.

tsfpga.vivado.hierarchical_utilization_parser module

class tsfpga.vivado.hierarchical_utilization_parser.HierarchicalUtilizationParser

Bases: object

Used for parsing the report_utilization -hierarchical report generated by Vivado.

static get_size(report)

Takes a hierarchical utilization report as a string and returns the top level size for the specified run.

Parameters

report (str) – A string containing the entire Vivado hierarchical utilization report.

tsfpga.vivado.ip_cores module

class tsfpga.vivado.ip_cores.VivadoIpCores(modules, output_path, part_name, vivado_project_class=None)

Bases: object

Handle a list of IP core sources. Has a mechanism to detect whether a regenerate of IP files is needed.

__init__(modules, output_path, part_name, vivado_project_class=None)

Parameters

• modules (list(BaseModule)) – IP cores from these modules will be included.

• output_path (pathlib.Path) – The Vivado project will be placed here.

• part_name (str) – Vivado part name to be used for the project.

• vivado_project_class – The Vivado project class that will be used for the IP core project. Is safe to leave at default in most cases.

property compile_order_file

Path to the generated compile order file.

Type

pathlib.Path

create_vivado_project()

Create IP core Vivado project.

create_vivado_project_if_needed()

Create IP core Vivado project if anything has changed since last time this was run. If

• List of TCL files that create IP cores,

• and contents of these files,

is the same then it will not create. But if anything is added or removed from the list, or the contents of a TCL file is changed, there will be a recreation.

Returns

True if Vivado project was created. False otherwise.

project_name = 'vivado_ip_project'

property vivado_project_file

Path to the Vivado project file.

Type

pathlib.Path

tsfpga.vivado.logic_level_distribution_parser module

class tsfpga.vivado.logic_level_distribution_parser.LogicLevelDistributionParser

Bases: object

Used for parsing the report_design_analysis -logic_level_distribution report generated by Vivado.

This code is very hard coded for how the report and table is formatted. See the unit tests for examples of this formatting.

static get_maximum_logic_level(table)

Returns the maximum logic level in the table.

Parameters

table (str) – The table as returned by get_table().

Returns

The maximum logic level.

Return type

int

static get_table(report)

Takes a report as a string and returns the table.

Parameters

report (str) – A string containing the entire Vivado report_design_analysis -logic_level_distribution report.

tsfpga.vivado.project module

class tsfpga.vivado.project.VivadoIpCoreProject(**kwargs)

Bases: tsfpga.vivado.project.VivadoProject

A Vivado project that is only used to generate simulation models of IP cores.

__init__(**kwargs)

Parameters

kwargs – Arguments as accepted by VivadoProject.__init__().

build(**kwargs)

Not implemented.

class tsfpga.vivado.project.VivadoNetlistProject(analyze_synthesis_timing=False, build_result_checkers=None, **kwargs)

Bases: tsfpga.vivado.project.VivadoProject

Used for handling Vivado build of a module without top level pinning.

__init__(analyze_synthesis_timing=False, build_result_checkers=None, **kwargs)

Parameters

• analyze_synthesis_timing (bool) – Enable analysis of the synthesized design’s timing. This will make the build flow open the design, and check for unhandled clock crossings and pulse width violations. Enabling it will add significant build time (can be as much as +40%). Also, in order for clock crossing check to work, the clocks have to be created using a constraint file.

• build_result_checkers (list(SizeChecker, MaximumLogicLevel)) – Checkers that will be executed after a successful build. Is used to automatically check that e.g. resource utilization is not greater than expected.

• kwargs – Further arguments accepted by VivadoProject.__init__().

build(**kwargs)

Build the project.

Parameters

kwargs – All arguments as accepted by VivadoProject.build().

class tsfpga.vivado.project.VivadoProject(name, modules, part, top=None, generics=None, constraints=None, tcl_sources=None, build_step_hooks=None, vivado_path=None, default_run_index=1, defined_at=None, **other_arguments)

Bases: object

Used for handling a Xilinx Vivado HDL project

__init__(name, modules, part, top=None, generics=None, constraints=None, tcl_sources=None, build_step_hooks=None, vivado_path=None, default_run_index=1, defined_at=None, **other_arguments)

Class constructor. Performs a shallow copy of the mutable arguments, so that the user can e.g. append items to their list after creating an object.

Parameters

• name (str) – Project name.

• modules (list(BaseModule)) – Modules that shall be included in the project.

• part (str) – Part identification.

• top (str) – Name of top level entity. If left out, the top level name will be inferred from the name.

• generics –

  A dict with generics values (dict(name: value)). Use this parameter for “static” generics that do not change between multiple builds of this project. These will be set in the project when it is created.

  Compare to the build-time generic argument in build().

  The generic value shall be of type

  • bool (suitable for VHDL type boolean and std_logic),

  • int (suitable for VHDL type integer, natural, etc.),

  • float (suitable for VHDL type real),

  • BitVectorGenericValue (suitable for VHDL type std_logic_vector, unsigned, etc.), or

  • StringGenericValue (suitable for VHDL type string).

• constraints (list(Constraint)) – Constraints that will be applied to the project.

• tcl_sources (list(pathlib.Path)) – A list of TCL files. Use for e.g. block design, pinning, settings, etc.

• build_step_hooks (list(BuildStepTclHook)) – Build step hooks that will be applied to the project.

• vivado_path (pathlib.Path) – A path to the Vivado executable. If omitted, the default location from the system PATH will be used.

• default_run_index (int) – Default run index (synth_X and impl_X) that is set in the project. Can also use the argument to build() to specify at build-time.

• defined_at (pathlib.Path) – Optional path to the file where you defined this project. To get a useful build.py --list message. Is useful when you have many projects set up.

• other_arguments –

  Optional further arguments. Will not be used by tsfpga, but will instead be passed on to

  • BaseModule.get_synthesis_files()

  • BaseModule.get_ip_core_files()

  • BaseModule.get_scoped_constraints()

  • VivadoProject.pre_create()

  • BaseModule.pre_build()

  • VivadoProject.pre_build()

  • VivadoProject.post_build()

  along with further arguments supplied at build-time to create() and build().

  Note

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

build(project_path, output_path=None, run_index=None, generics=None, synth_only=False, from_impl=False, num_threads=12, **pre_and_post_build_parameters)

Build a Vivado project

Parameters

• project_path (pathlib.Path) – A path containing a Vivado project.

• output_path (pathlib.Path) – Results (bit file, …) will be placed here.

• run_index (int) – Select Vivado run (synth_X and impl_X) to build with.

• generics –

  A dict with generics values (dict(name: value)). Use for run-time generics, i.e. values that can change between each build of this project.

  Compare to the create-time generics argument in __init__().

  The generic value types follow the same rules as for __init__().

• synth_only (bool) – Run synthesis and then stop.

• from_impl (bool) – Run the impl steps and onward on an existing synthesized design.

• num_threads (int) – Number of parallel threads to use during run.

• pre_and_post_build_parameters –

  Optional further arguments. Will not be used by tsfpga, but will instead be sent to

  • BaseModule.pre_build()

  • VivadoProject.pre_build()

  • VivadoProject.post_build()

  along with further other_arguments supplied to __init__().

  Note

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

Returns

Result object with build information.

Return type

build_result.BuildResult

create(project_path, ip_cache_path=None, **other_arguments)

Create a Vivado project

Parameters

• project_path (pathlib.Path) – Path where the project shall be placed.

• ip_cache_path (pathlib.Path) – Path to a folder where the Vivado IP cache can be placed. If omitted, the Vivado IP cache mechanism will not be enabled.

• other_arguments –

  Optional further arguments. Will not be used by tsfpga, but will instead be sent to

  • BaseModule.get_synthesis_files()

  • BaseModule.get_ip_core_files()

  • BaseModule.get_scoped_constraints()

  • VivadoProject.pre_create()

  along with further other_arguments supplied to __init__().

  Note

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

Returns

True if everything went well.

Return type

bool

open(project_path)

Open the project in Vivado GUI.

Parameters

project_path (pathlib.Path) – A path containing a Vivado project.

Returns

True if everything went well.

Return type

bool

post_build(**kwargs)

Override this function in a child class if you wish to do something useful with it. Will be called from build() right after the call to Vivado.

An example use case for this function is to encrypt the bit file, or generate any other material that shall be included in FPGA release artifacts.

Note

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

Parameters

kwargs – Will have all the build() parameters in it. Including additional parameters from the user. Will also include build_result with implemented/synthesized size, which can be used for asserting the expected resource utilization.

Returns

True if everything went well.

Return type

bool

pre_build(**kwargs)

Override this function in a child class if you wish to do something useful with it. Will be called from build() right before the call to Vivado.

Parameters

kwargs – Will have all the build() parameters in it. Including additional parameters from the user.

Returns

True if everything went well.

Return type

bool

pre_create(**kwargs)

Override this function in a child class if you wish to do something useful with it. Will be called from create() right before the call to Vivado.

An example use case for this function is when TCL source scripts for the Vivado project have to be auto generated. This could e.g. be scripts that set IP repo paths based on the Vivado system PATH.

Note

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

Parameters

kwargs – Will have all the create() parameters in it, as well as everything in the other_arguments argument to VivadoProject.__init__().

Returns

True if everything went well.

Return type

bool

project_file(project_path)

Parameters

project_path (pathlib.Path) – A path containing a Vivado project.

Returns

The project file of this project, in the given folder

Return type

pathlib.Path

tsfpga.vivado.project.copy_and_combine_dicts(dict_first, dict_second)

Will prefer values in the second dict, in case the same key occurs in both. Will return None if both are None.

tsfpga.vivado.simlib module

class tsfpga.vivado.simlib.VivadoSimlib

Bases: object

Factory class for getting a Vivado simlib API.

static init(output_path, vunit_proj, vivado_path=None)

Get a Vivado simlib API suitable for your current simulator. Uses VUnit mechanism for detecting the simulator currently in use.

Parameters

• output_path (pathlib.Path) – The compiled simlib will be placed here.

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

• vivado_path (pathlib.Path) – Path to Vivado executable. If left out, the default from system PATH will be used.

Returns

A VivadoSimlibCommon child object.

tsfpga.vivado.simlib_commercial module

class tsfpga.vivado.simlib_commercial.VivadoSimlibCommercial(output_path, vunit_proj, simulator_interface, vivado_path)

Bases: tsfpga.vivado.simlib_common.VivadoSimlibCommon

Handle Vivado simlib with a commercial simulator.

__init__(output_path, vunit_proj, simulator_interface, vivado_path)

Parameters

• output_path (pathlib.Path) – The compiled simlib will be placed here.

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

• simulator_interface – A VUnit SimulatorInterface class.

• vivado_path (pathlib.Path) – Path to Vivado executable.

library_names = ['unisim', 'secureip', 'unimacro', 'unifast', 'xpm']

tsfpga.vivado.simlib_common module

class tsfpga.vivado.simlib_common.VivadoSimlibCommon

Bases: object

Class for handling Vivado simlib used for simulation. Keeps track of when a (re)compile is needed.

This is a parent class that defines an interface and some common methods. See child classes for details: VivadoSimlibGhdl, VivadoSimlibCommercial.

add_to_vunit_project()

Add the compiled simlib to your VUnit project.

property artifact_name

The name of the folder where simlib is or will be compiled. Follows a format vivado-simlib-WW.XX.YY.ZZ suitable for storage and versioning in Artifactory.

Type

str

compile()

Compile simlib.

compile_if_needed()

Compile if needed (if compile_is_needed condition is not fulfilled).

property compile_is_needed

If there is compiled simlib available that matches

• Operating system

• Vivado version

• Simulator version

then there should not be a recompile.

Note

Child implementations might add further conditions.

Returns

True if compiled simlib is not available. False otherwise.

from_archive(archive)

Unpack compiled simlib from an existing archive.

Parameters

archive (pathlib.Path) – Path to a zip archive with previously compiled simlib.

library_names = None

output_path = None

to_archive()

Compress compiled simlib to an archive.

Returns

Path to the archive.

Return type

pathlib.Path

tsfpga.vivado.simlib_ghdl module

class tsfpga.vivado.simlib_ghdl.VivadoSimlibGhdl(output_path, vunit_proj, simulator_interface, vivado_path)

Bases: tsfpga.vivado.simlib_common.VivadoSimlibCommon

Handle Vivado simlib with GHDL.

__init__(output_path, vunit_proj, simulator_interface, vivado_path)

Parameters

• output_path (pathlib.Path) – The compiled simlib will be placed here.

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

• simulator_interface – A VUnit SimulatorInterface class.

• vivado_path (pathlib.Path) – Path to Vivado executable.

library_names = ['unisim', 'secureip', 'unimacro', 'unifast']

tsfpga.vivado.tcl module

class tsfpga.vivado.tcl.VivadoTcl(name)

Bases: object

Class with methods for translating a set of sources into Vivado TCL

__init__(name)

build(project_file, output_path, num_threads, run_index, generics=None, synth_only=False, from_impl=False, analyze_synthesis_timing=True)

create(project_folder, modules, part, top, run_index, generics=None, constraints=None, tcl_sources=None, build_step_hooks=None, ip_cache_path=None, disable_io_buffers=True, ip_cores_only=False, other_arguments=None)