tsfpga.vivado package
Submodules
tsfpga.vivado.build_result module
- class tsfpga.vivado.build_result.BuildResult(name: str)
Bases:
object
- 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
- logic_level_distribution
A table with logic level distribution as reported by Vivado. Will be
None
for non-netlist builds. Will beNone
if synthesis failed or did not run.- Type:
- property maximum_logic_level: None | int
The maximum level in the the
BuildResult.logic_level_distribution
. Will beNone
for non-netlist builds. Will beNone
if synthesis failed or did not run.- Returns:
The maximum logic level.
tsfpga.vivado.build_result_checker module
- class tsfpga.vivado.build_result_checker.BuildResultChecker(limit: Limit)
Bases:
ABC
Base class for build result checkers that check a certain build result value against a limit.
Overload in subclass and implement the
check
method according to the resource you want to check.- __init__(limit: Limit)
- Parameters:
limit – The limit that the specified resource shall be checked against.
- abstract check(build_result: BuildResult) bool
- Parameters:
build_result – Build result that shall be checked. Should come from a successful build.
- Returns:
True if check passed, false otherwise.
- class tsfpga.vivado.build_result_checker.DspBlocks(limit: Limit)
Bases:
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: BuildResult) bool
Same as super class, but checks for the legacy name as well as the current name.
- class tsfpga.vivado.build_result_checker.EqualTo(value: int)
Bases:
Limit
Limit to be used with a checker to see that a figure is equal to the specified value.
- class tsfpga.vivado.build_result_checker.Ffs(limit: Limit)
Bases:
SizeChecker
- class tsfpga.vivado.build_result_checker.GreaterThan(value: int)
Bases:
Limit
Limit to be used with a checker to see that a figure is greater than the specified value.
- class tsfpga.vivado.build_result_checker.LessThan(value: int)
Bases:
Limit
Limit to be used with a checker to see that a figure is less than the specified value.
- class tsfpga.vivado.build_result_checker.Limit(value: int)
Bases:
ABC
Base class for limit checks. Inherit and implement the check in subclass.
- class tsfpga.vivado.build_result_checker.LogicLuts(limit: Limit)
Bases:
SizeChecker
- class tsfpga.vivado.build_result_checker.LutRams(limit: Limit)
Bases:
SizeChecker
- class tsfpga.vivado.build_result_checker.MaximumLogicLevel(limit: Limit)
Bases:
BuildResultChecker
Check the maximum logic level of a build result against a limit.
- check(build_result: BuildResult) bool
- Parameters:
build_result – Build result that shall be checked. Should come from a successful build.
- Returns:
True if check passed, false otherwise.
- name = 'Maximum logic level'
- class tsfpga.vivado.build_result_checker.Ramb(limit: Limit)
Bases:
SizeChecker
Combined checker for RAMB36 and RAMB18 count. Each RAMB18 counts as half a RAMB36.
- check(build_result: BuildResult) bool
Similar to super class, but takes out two result values.
- class tsfpga.vivado.build_result_checker.Ramb18(limit: Limit)
Bases:
SizeChecker
- class tsfpga.vivado.build_result_checker.Ramb36(limit: Limit)
Bases:
SizeChecker
- class tsfpga.vivado.build_result_checker.SizeChecker(limit: Limit)
Bases:
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: BuildResult) bool
- Parameters:
build_result – Build result that shall be checked. Should come from a successful build.
- Returns:
True if check passed, false otherwise.
- class tsfpga.vivado.build_result_checker.Srls(limit: Limit)
Bases:
SizeChecker
- class tsfpga.vivado.build_result_checker.TotalLuts(limit: Limit)
Bases:
SizeChecker
- class tsfpga.vivado.build_result_checker.Uram(limit: Limit)
Bases:
SizeChecker
tsfpga.vivado.common module
- tsfpga.vivado.common.get_git_sha_slv(git_directory: Path) tuple[str, str]
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 binary strings.
- Parameters:
directory – 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.
- tsfpga.vivado.common.get_vivado_path(vivado_path: Path | None = None) Path
Wrapper to get a path to Vivado executable.
- Parameters:
vivado_path – Path to vivado executable. Leave as
None
to use whatever is available in the systemPATH
.
- tsfpga.vivado.common.get_vivado_version(vivado_path: Path | None = None) str
Get the version number of the Vivado installation.
- Parameters:
vivado_path – Path to vivado executable. Leave as
None
to use whatever is available in the systemPATH
.- Returns:
The version, e.g.
"2021.2"
.
- tsfpga.vivado.common.run_vivado_gui(vivado_path: Path | None, project_file: Path) bool
Setting cwd ensures that any .log or .jou files produced are placed in the same directory as the project.
- Parameters:
vivado_path – Path to Vivado executable. Leave as
None
to use whatever is available in the systemPATH
.project_file – Path to a project .xpr file.
- Returns:
True if everything went well.
- tsfpga.vivado.common.run_vivado_tcl(vivado_path: Path | None, tcl_file: Path, no_log_file: bool = False) bool
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 – Path to Vivado executable. Can set to
None
to use whatever version is inPATH
.tcl_file – Path to TCL file.
no_log_file – Optionally set Vivado flags to not create log and journal files.
- Returns:
True if everything went well.
tsfpga.vivado.generics module
- class tsfpga.vivado.generics.BitVectorGenericValue(value: str)
Bases:
object
Use this type for generic values of type
std_logic_vector
.
- class tsfpga.vivado.generics.StringGenericValue(value: str)
Bases:
object
Use this type for generic values of type
string
.
- tsfpga.vivado.generics.get_vivado_tcl_generic_value(value: bool | int | float | StringGenericValue | BitVectorGenericValue) str
Convert generic values of different types to the format recognized by Vivado TCL: https://www.xilinx.com/support/answers/52217.html
- Parameters:
value – A generic value of native Python type..
- Returns:
The
value
formatted as TCL.
tsfpga.vivado.hierarchical_utilization_parser module
tsfpga.vivado.ip_cores module
- class tsfpga.vivado.ip_cores.VivadoIpCores(modules: ModuleList, output_path: Path, part_name: str, vivado_project_class: type[VivadoIpCoreProject] | None = 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: ModuleList, output_path: Path, part_name: str, vivado_project_class: type[VivadoIpCoreProject] | None = None) None
- Parameters:
modules – IP cores from these modules will be included.
output_path – The Vivado project will be placed here.
part_name – 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.
- create_vivado_project_if_needed() bool
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'
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: str) int
Returns the maximum logic level in the table.
- Parameters:
table – The table as returned by
get_table()
.- Returns:
The maximum logic level.
tsfpga.vivado.project module
- class tsfpga.vivado.project.VivadoIpCoreProject(**kwargs: Any)
Bases:
VivadoProject
A Vivado project that is only used to generate simulation models of IP cores.
- __init__(**kwargs: Any) None
- Parameters:
kwargs – Arguments as accepted by
VivadoProject.__init__()
.
- ip_cores_only = True
- class tsfpga.vivado.project.VivadoNetlistProject(analyze_synthesis_timing: bool = False, build_result_checkers: list[SizeChecker | MaximumLogicLevel] | None = None, **kwargs: Any)
Bases:
VivadoProject
Used for handling Vivado build of a module without top level pinning.
- __init__(analyze_synthesis_timing: bool = False, build_result_checkers: list[SizeChecker | MaximumLogicLevel] | None = None, **kwargs: Any) None
- Parameters:
analyze_synthesis_timing – 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 – 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: Any) BuildResult
Build the project.
- Parameters:
kwargs – All arguments as accepted by
VivadoProject.build()
.
- class tsfpga.vivado.project.VivadoProject(name: str, modules: ModuleList, part: str, top: str | None = None, generics: dict[str, Any] | None = None, constraints: list[Constraint] | None = None, tcl_sources: list[Path] | None = None, build_step_hooks: list[BuildStepTclHook] | None = None, vivado_path: Path | None = None, default_run_index: int = 1, impl_explore: bool = False, defined_at: Path | None = None, **other_arguments: Any)
Bases:
object
Used for handling a Xilinx Vivado HDL project
- __init__(name: str, modules: ModuleList, part: str, top: str | None = None, generics: dict[str, Any] | None = None, constraints: list[Constraint] | None = None, tcl_sources: list[Path] | None = None, build_step_hooks: list[BuildStepTclHook] | None = None, vivado_path: Path | None = None, default_run_index: int = 1, impl_explore: bool = False, defined_at: Path | None = None, **other_arguments: Any)
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 – Project name.
modules – Modules that shall be included in the project.
part – Part identification.
top – Name of top level entity. If left out, the top level name will be inferred from the
name
.generics –
A dict with generics values (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 typeboolean
andstd_logic
),int
(suitable for VHDL typeinteger
,natural
, etc.),float
(suitable for VHDL typereal
),BitVectorGenericValue
(suitable for VHDL typestd_logic_vector
,unsigned
, etc.), orStringGenericValue
(suitable for VHDL typestring
).
constraints – Constraints that will be applied to the project.
tcl_sources – A list of TCL files. Use for e.g. block design, pinning, settings, etc.
build_step_hooks – Build step hooks that will be applied to the project.
vivado_path – A path to the Vivado executable. If omitted, the default location from the system PATH will be used.
default_run_index – 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 – Optional path to the file where you defined this project. To get a useful
build_fpga.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
along with further arguments supplied at build-time to
create()
andbuild()
.Note
This is a “kwargs” style argument. You can pass any number of named arguments.
- build(project_path: Path, output_path: Path | None = None, run_index: int | None = None, generics: dict[str, Any] | None = None, synth_only: bool = False, from_impl: bool = False, num_threads: int = 12, **pre_and_post_build_parameters: Any) BuildResult
Build a Vivado project
- Parameters:
project_path – A path containing a Vivado project.
output_path – Results (bit file, …) will be placed here.
run_index – 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 – Run synthesis and then stop.
from_impl – Run the
impl
steps and onward on an existing synthesized design.num_threads – 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
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.
- create(project_path: Path, ip_cache_path: Path | None = None, **other_arguments: Any) bool
Create a Vivado project
- Parameters:
project_path – Path where the project shall be placed.
ip_cache_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
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.
- open(project_path: Path) bool
Open the project in Vivado GUI.
- Parameters:
project_path – A path containing a Vivado project.
- Returns:
True if everything went well.
- post_build(**kwargs: Any) bool
Override this function in a subclass 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 includebuild_result
with implemented/synthesized size, which can be used for asserting the expected resource utilization.- Returns:
True if everything went well.
- pre_build(**kwargs: Any) bool
Override this function in a subclass 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.
- pre_create(**kwargs: Any) bool
Override this function in a subclass 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 theother_arguments
argument toVivadoProject.__init__()
.- Returns:
True if everything went well.
tsfpga.vivado.simlib module
- class tsfpga.vivado.simlib.VivadoSimlib
Bases:
object
Factory class for getting a Vivado simlib API.
- static init(output_path: Path, vunit_proj: VUnit, vivado_path: Path | None = None) VivadoSimlibCommon
Get a Vivado simlib API suitable for your current simulator. Uses VUnit mechanism for detecting the simulator currently in use.
Will return a
VivadoSimlibCommon
subclass object.- Parameters:
output_path – The compiled simlib will be placed here.
vunit_proj – The VUnit project that is used to run simulation.
vivado_path – Path to Vivado executable. If left out, the default from system
PATH
will be used.
tsfpga.vivado.simlib_commercial module
- class tsfpga.vivado.simlib_commercial.VivadoSimlibCommercial(vivado_path: Path | None, output_path: Path, vunit_proj: Any, simulator_interface: Any)
Bases:
VivadoSimlibCommon
Handle Vivado simlib with a commercial simulator.
- __init__(vivado_path: Path | None, output_path: Path, vunit_proj: Any, simulator_interface: Any)
- Parameters:
output_path – The compiled simlib will be placed here.
vunit_proj – The VUnit project that is used to run simulation.
simulator_interface – A VUnit SimulatorInterface object.
vivado_path – Path to Vivado executable.
tsfpga.vivado.simlib_common module
- class tsfpga.vivado.simlib_common.VivadoSimlibCommon(vivado_path: Path | None, output_path: Path)
Bases:
ABC
Class for handling Vivado simlib used for simulation. Keeps track of when a (re)compile is needed.
This is a base class that defines an interface and some common methods. See subclasses for details:
VivadoSimlibGhdl
,VivadoSimlibCommercial
.- __init__(vivado_path: Path | None, output_path: Path) None
Call from subclass. Do not instantiate this class directly.
- property artifact_name: str
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.
- compile_if_needed() bool
Compile if needed (if
compile_is_needed
condition is not fulfilled).
- property compile_is_needed: bool
If there is compiled simlib available that matches
Operating system
Vivado version
Simulator version
then there should not be a recompile.
Note
Subclass implementations might add further conditions.
- Returns:
True if compiled simlib is not available. False otherwise.
tsfpga.vivado.simlib_ghdl module
- class tsfpga.vivado.simlib_ghdl.VivadoSimlibGhdl(vivado_path: Path | None, output_path: Path, vunit_proj: Any, simulator_interface: Any)
Bases:
VivadoSimlibCommon
Handle Vivado simlib with GHDL.
- __init__(vivado_path: Path | None, output_path: Path, vunit_proj: Any, simulator_interface: Any) None
- Parameters:
output_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 – Path to Vivado executable.
tsfpga.vivado.tcl module
- class tsfpga.vivado.tcl.VivadoTcl(name: str)
Bases:
object
Class with methods for translating a set of sources into Vivado TCL
- build(project_file: Path, output_path: Path, num_threads: int, run_index: int, generics: dict[str, Any] | None = None, synth_only: bool = False, from_impl: bool = False, impl_explore: bool = False, analyze_synthesis_timing: bool = True) str
- create(project_folder: Path, modules: ModuleList, part: str, top: str, run_index: int, generics: dict[str, str] | None = None, constraints: list[Constraint] | None = None, tcl_sources: list[Path] | None = None, build_step_hooks: list[BuildStepTclHook] | None = None, ip_cache_path: Path | None = None, disable_io_buffers: bool = True, ip_cores_only: bool = False, other_arguments: dict[str, Any] | None = None) str