tsfpga.yosys package

Submodules

tsfpga.yosys.build_result module

class tsfpga.yosys.build_result.YosysBuildResult(name: str)

Bases: BuildResult

The result of a Yosys netlist build.

Yosys builds are synthesis-only, so there are no implementation metrics and no timing information. Only BuildResult.synthesis_size is available.

tsfpga.yosys.common module

tsfpga.yosys.common.get_ghdl_library_prefix(ghdl_path: Path | None = None) → Path | None

Try to automatically find the GHDL “library prefix”, i.e. the location where the std/ieee standard libraries are installed, by parsing the output of ghdl --disp-config.

GHDL can normally find this on its own, by looking at the path of its own executable. This does however not work when GHDL is used as a library, e.g. via the ghdl-yosys-plugin module loaded into Yosys (see run_yosys()), since there is no ghdl executable path to derive the prefix from in that case. Calling this function against the standalone ghdl executable lets us find the prefix anyway, so it can be forwarded explicitly.

Parameters:: ghdl_path – Path to the GHDL executable. Can be set to None to use whatever version is in PATH.
Returns:: The library prefix, or None if it could not be determined.

tsfpga.yosys.common.get_ghdl_path(ghdl_path: Path | None = None) → Path

Wrapper to get a path to the GHDL executable.

Parameters:: ghdl_path – Path to the GHDL executable. Leave as None to use whatever is available in the system PATH.

tsfpga.yosys.common.get_yosys_path(yosys_path: Path | None = None) → Path

Wrapper to get a path to the Yosys executable.

Parameters:: yosys_path – Path to the Yosys executable. Leave as None to use whatever is available in the system PATH.

tsfpga.yosys.common.run_ghdl(ghdl_path: Path | None, arguments: list[str], cwd: Path) → bool

Run GHDL with the given arguments. Used for analyzing VHDL source files into an on-disk library, which can later be picked up by the ghdl-yosys-plugin when running run_yosys().

Setting cwd ensures that any files produced (e.g. GHDL library files) end up in a well-known location.

Parameters:

ghdl_path – Path to the GHDL executable. Can be set to None to use whatever version is in PATH.
arguments – Arguments that shall be passed on to GHDL.
cwd – The GHDL process will be executed with this as the working directory.

Returns:

True if everything went well.

tsfpga.yosys.common.run_yosys(script_file: Path, cwd: Path, yosys_path: Path | None = None, ghdl_plugin_path: Path | None = None, ghdl_path: Path | None = None, ghdl_prefix: Path | None = None) → bool

Run Yosys with the given script.

Setting cwd ensures that any files produced (e.g. reports, netlists) end up in a well-known location.

Parameters:

script_file – Path to a file containing the Yosys commands that shall be executed.
cwd – The Yosys process will be executed with this as the working directory.
yosys_path – Path to the Yosys executable. Can be set to None to use whatever version is in PATH.
ghdl_plugin_path – Path to the ghdl-yosys-plugin module (typically named ghdl.so). Can be set to None if the plugin is already available to Yosys without explicitly loading it (e.g. if it has been installed in the Yosys plugin directory).
ghdl_path – Path to the GHDL executable, used only to auto-detect ‘ghdl_prefix’ below when it is not given explicitly. Can be set to None to use whatever version is in PATH.
ghdl_prefix – Value to set the GHDL_PREFIX environment variable to for this process. The ghdl-yosys-plugin module is loaded as part of the Yosys process, and hence can not find the GHDL standard libraries (std, ieee, …) on its own the way the standalone ghdl executable can. Corresponds to the “library prefix” printed by ghdl --disp-config. If left as None, this method will try to find a value automatically by calling ghdl --disp-config (see ‘ghdl_path’ above) and parsing its output. Set explicitly to override the auto-detected value, or if auto-detection fails.

Returns:

True if everything went well.

tsfpga.yosys.common.to_yosys_path(path: Path) → str: Return a path string in a format suitable to embed in a Yosys command script.

tsfpga.yosys.project module

class tsfpga.yosys.project.YosysIntelNetlistBuild(family: str | None = None, **kwargs: Any)

Bases: YosysNetlistBuild

Used for handling a Yosys netlist build that targets Intel (Altera) primitives (*_lcell_comb, dffeas, altsyncram, …), using the Yosys synth_intel command.

Note

Targets the MAX10, Cyclone IV, Cyclone IV E and Cyclone 10 LP families. For ALM-based Intel devices (Cyclone V, Cyclone 10 GX) the synth_intel_alm command shall be used instead, which is not covered by this class. Subclass YosysNetlistBuild and set its _synth_command to "synth_intel_alm" for that, though note that no aggregated resource counts will be available in that case.

Since the produced utilization report uses the resource names "Total LUTs", "FFs", "Block RAMs" and "DSP Blocks", the corresponding checkers in vivado.build_result_checker can be used directly.

__init__(family: str | None = None, **kwargs: Any) → None

Parameters:

family – Optionally target a specific Intel device family (e.g. "cycloneiv"). See the Yosys synth_intel command documentation for valid values.
kwargs – Further arguments accepted by YosysNetlistBuild.__init__().

class tsfpga.yosys.project.YosysMicrochipNetlistBuild(family: str | None = None, discard_ffinit: bool = False, **kwargs: Any)

Bases: YosysNetlistBuild

Used for handling a Yosys netlist build that targets Microchip primitives (CFG*, SLE, RAM1K20, MACC_PA, …), using the Yosys synth_microchip command.

Note

Targets the PolarFire family, which is the only one currently supported by the Yosys synth_microchip command.

Since the produced utilization report uses the resource names "Total LUTs", "FFs", "Block RAMs" and "DSP Blocks", the corresponding checkers in vivado.build_result_checker can be used directly.

__init__(family: str | None = None, discard_ffinit: bool = False, **kwargs: Any) → None

Parameters:

family – Optionally target a specific Microchip device family. See the Yosys synth_microchip command documentation for valid values.
discard_ffinit – The Yosys synth_microchip command will raise an error if the design contains a flip-flop with an initial value that can not be legalized to a supported flip-flop type (which is a common occurrence, since e.g. VHDL signals initialized to a default value result in flip-flops with an initial value). Set this to True to instead discard the initial value and let synthesis proceed. Corresponds to the Yosys -discard-ffinit flag.
kwargs – Further arguments accepted by YosysNetlistBuild.__init__().

class tsfpga.yosys.project.YosysNetlistBuild(name: str, modules: ModuleList, top: str | None = None, vhdl_entities: list[str] | None = None, generics: GenericValues | None = None, build_result_checkers: list[SizeChecker] | None = None, vhdl_standard: str = '08', ghdl_path: Path | None = None, yosys_path: Path | None = None, ghdl_plugin_path: Path | None = None, ghdl_prefix: Path | None = None, defined_at: Path | None = None, **other_arguments: Any)

Bases: object

Used for handling a synthesis-only (netlist) build of a design, using Yosys with the ghdl-yosys-plugin as the VHDL front end.

Since this is a netlist build, there is no implementation (place & route) step, and hence no bitstream is produced. This is a great tool for getting quick feedback on the resource utilization of a design, or a sub-component of a design, during development.

The top is typically a VHDL entity, in which case all of its VHDL dependencies are found automatically via the compile order. It can also be a Verilog/SystemVerilog module (or the design can have no VHDL at all), in which case any VHDL entities that shall be instantiated from it (or from other VHDL entities) must be explicitly listed using the vhdl_entities argument.

Note

Requires GHDL, Yosys, and the ghdl-yosys-plugin module to be installed and available. See the ghdl-yosys-plugin documentation for installation instructions.

__init__(name: str, modules: ModuleList, top: str | None = None, vhdl_entities: list[str] | None = None, generics: GenericValues | None = None, build_result_checkers: list[SizeChecker] | None = None, vhdl_standard: str = '08', ghdl_path: Path | None = None, yosys_path: Path | None = None, ghdl_plugin_path: Path | None = None, ghdl_prefix: Path | None = None, defined_at: Path | None = None, **other_arguments: Any) → None

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 build. Only VHDL source files are considered, since the build uses the GHDL front end.
top – Name of top level entity. If left out, the top level name will be inferred from the name. Is typically a VHDL entity, but can also be a Verilog/SystemVerilog module – see vhdl_entities below.
vhdl_entities – Only used if top is not a VHDL entity (i.e. if it is a Verilog/SystemVerilog module, or if the design has no VHDL at all). A list of the names of the VHDL entities that shall be made available for instantiation from the non-VHDL top level (or from other VHDL entities), since there is in that case no single VHDL top level to automatically find these dependencies from. Not used, and shall be left as None, if top is a VHDL entity, since in that case all of its VHDL dependencies are found automatically via the compile order.
generics –
A dict with generics values (name: value). Use this parameter for “static” generics that do not change between multiple builds of this project.

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

The generic value shall be of type GenericValue.
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.
vhdl_standard – The VHDL standard that shall be used by GHDL when analyzing the source files (e.g. "93" or "08").
ghdl_path – Path to the GHDL executable. If omitted, the default location from the system PATH will be used.
yosys_path – Path to the Yosys executable. If omitted, the default location from the system PATH will be used.
ghdl_plugin_path – Path to the ghdl-yosys-plugin module (typically named ghdl.so). Can be left out if the plugin is already available to Yosys without explicitly loading it (e.g. if it has been installed in the Yosys plugin directory).
ghdl_prefix – Value to set the GHDL_PREFIX environment variable to when running Yosys with the ghdl-yosys-plugin. The plugin is loaded as part of the Yosys process, and can not find the GHDL standard libraries (std, ieee, …) on its own the way the standalone ghdl executable can. Corresponds to the “library prefix” printed by ghdl --disp-config. If left out, this is auto-detected by calling ghdl --disp-config against the executable given by ghdl_path above. Set explicitly to override the auto-detected value, or if auto-detection fails.
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() and build().

Note

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

Synthesize the design with Yosys.

Parameters:

project_path – A path containing the result of a call to create().
output_path – The utilization report, and any other artifacts, will be placed here. Will default to project_path if not set.
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__().
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, **other_arguments: Any) → bool

Analyze all the VHDL source files with GHDL, so that the design is ready to be elaborated and synthesized by build().

Parameters:

project_path – Path where the GHDL analysis result shall be placed.
other_arguments –
Optional further arguments. Will not be used by tsfpga, but will instead be sent to
- BaseModule.get_synthesis_files()
- YosysNetlistBuild.pre_create()
along with further other_arguments supplied to __init__().

Returns:

True if everything went well.

is_netlist_build = True: Will always be True for this class, since it is a netlist build.

open(project_path: Path) → NoReturn: Not implemented. A Yosys netlist build has no GUI to open.

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

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

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 GHDL analysis is started.

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 YosysNetlistBuild.__init__().
Returns:: True if everything went well.

project_file(project_path: Path) → Path

Parameters:: project_path – A path containing a Yosys netlist build.
Returns:: The Yosys command script of this build, in the given folder.

class tsfpga.yosys.project.YosysXilinxNetlistBuild(family: str | None = None, **kwargs: Any)

Bases: YosysNetlistBuild

Used for handling a Yosys netlist build that targets Xilinx primitives (LUTs, FDs, RAMBs, DSP48s, …), using the Yosys synth_xilinx command.

Since the produced utilization report uses the same resource naming convention as the Vivado utilization report, the checkers in vivado.build_result_checker can be used directly to check e.g. the LUT or RAMB count of the design.

__init__(family: str | None = None, **kwargs: Any) → None

Parameters:

family – Optionally target a specific Xilinx device family (e.g. "xc7"). See the Yosys synth_xilinx command documentation for valid values.
kwargs – Further arguments accepted by YosysNetlistBuild.__init__().

tsfpga.yosys.utilization_parser module

class tsfpga.yosys.utilization_parser.YosysIntelUtilizationParser

Bases: YosysUtilizationParser

Utilization parser for a design synthesized with the Yosys synth_intel command, i.e. targeting the MAX10, Cyclone IV, Cyclone IV E or Cyclone 10 LP families.

Note

The "DSP Blocks" count is only meaningful for the MAX10 family. Of the families supported by synth_intel, only that one maps multiplications to DSP cells. The others implement them in soft logic, so their reports contain no DSP cells at all and the count is always zero. Observed with Yosys 0.68, on a design with a single 18x18 multiplication.

resource_name_patterns: ClassVar[dict[str, str]] = {'Block RAMs': 'altsyncram$', 'DSP Blocks': '.*_mac_mult$', 'FFs': 'dffeas$', 'Total LUTs': '.*_lcell_comb$'}: Mapping of aggregated resource name (e.g. "Total LUTs") to a regular expression that is matched, using re.match(), against the raw primitive cell names to decide which cells shall be summed up to get that number. Shall be set by subclasses. The aggregated names are chosen to match the ones used in the Vivado utilization report (see vivado.build_result_checker) where applicable, so that the same build result checkers can be reused for Yosys builds.

class tsfpga.yosys.utilization_parser.YosysMicrochipUtilizationParser

Bases: YosysUtilizationParser

Utilization parser for a design synthesized with the Yosys synth_microchip command, i.e. targeting the PolarFire family.

resource_name_patterns: ClassVar[dict[str, str]] = {'Block RAMs': 'RAM(1K20|64[xX]12)$', 'DSP Blocks': 'MACC_PA$', 'FFs': 'SLE$', 'Total LUTs': 'CFG\\d$'}: Mapping of aggregated resource name (e.g. "Total LUTs") to a regular expression that is matched, using re.match(), against the raw primitive cell names to decide which cells shall be summed up to get that number. Shall be set by subclasses. The aggregated names are chosen to match the ones used in the Vivado utilization report (see vivado.build_result_checker) where applicable, so that the same build result checkers can be reused for Yosys builds.

class tsfpga.yosys.utilization_parser.YosysUtilizationParser

Bases: object

Used for parsing the resource utilization report produced by the Yosys stat command.

This base class reports only the raw Yosys primitive cell counts, which depend entirely on which synth_* command was used. Use one of the architecture-specific subclasses to also get aggregated, architecture-independent resource counts (e.g. "Total LUTs").

classmethod get_size(report: str) → dict[str, int]

Parameters:: report – The text printed to the console (or a log file) by the Yosys stat command.
Returns:: A dictionary with the resource utilization of the design. Contains the raw count of each cell primitive used in the design, as well as the aggregated counts (e.g. "Total LUTs") given by resource_name_patterns, if any.

resource_name_patterns: ClassVar[dict[str, str]] = {}: Mapping of aggregated resource name (e.g. "Total LUTs") to a regular expression that is matched, using re.match(), against the raw primitive cell names to decide which cells shall be summed up to get that number. Shall be set by subclasses. The aggregated names are chosen to match the ones used in the Vivado utilization report (see vivado.build_result_checker) where applicable, so that the same build result checkers can be reused for Yosys builds.

class tsfpga.yosys.utilization_parser.YosysXilinxUtilizationParser

Bases: YosysUtilizationParser

Utilization parser for a design synthesized with the Yosys synth_xilinx command.

resource_name_patterns: ClassVar[dict[str, str]] = {'Block RAMs': 'RAMB', 'DSP Blocks': 'DSP', 'FFs': 'FD', 'RAMB18': 'RAMB18', 'RAMB36': 'RAMB36', 'SRLs': 'SRL', 'Total LUTs': 'LUT'}: Mapping of aggregated resource name (e.g. "Total LUTs") to a regular expression that is matched, using re.match(), against the raw primitive cell names to decide which cells shall be summed up to get that number. Shall be set by subclasses. The aggregated names are chosen to match the ones used in the Vivado utilization report (see vivado.build_result_checker) where applicable, so that the same build result checkers can be reused for Yosys builds.