Torii Tool Interface¶

Warning

The following module is internal implementation details for Torii and should not be considered stable or for external use.

torii.tools.has_tool(name: str) → bool¶

Check to see if the tool or executable is available.

This method follows the same logic as require_tool() when doing the lookup for the tool itself, the only difference is no exceptions are thrown if the tool is not found.

Parameters:: name (str) – The tool/executable name.
Return type:: bool
Returns:: bool – If the tool/executable was found in the current system PATH.

torii.tools.require_tool(name: str) → str¶

Return the fully resolved path to the requested tool or executable if found, otherwise throw a ToolNotFound exception.

The logic for this check is as follows:

Compute expected environment variable name via tool_env_var
Check to see if the environment variable is set, if so, use that value, otherwise use name
Use which to search the system PATH for the tool

If the tool is found, return the resulting path, otherwise raise an error.

Parameters:: name (str) – The name of the tool/executable.
Return type:: str
Returns:: str – The fully qualified path to the tool/executable.
Raises:: torii.diagnostics.ToolNotFound – If we are unable to locate the requested tool.

Yosys¶

class torii.tools.yosys.YosysVersion(major: int, minor: int, distance: int)¶

A 3-tuple that contains the Yosys version in the form of (major, minor, distance)

major: int¶: Alias for field number 0

minor: int¶: Alias for field number 1

distance: int¶: Alias for field number 2

class torii.tools.yosys.YosysBinary¶

Represents a Yosys binary that lives somewhere on the system.

classmethod available() → bool¶

Check to see if we can find a Yosys binary on the system via the PATH or alternative lookup methods. See has_tool for more information on the lookup preformed.

Return type:: bool
Returns:: bool – True if Yosys is installed, False otherwise. Installed binary may still not be runnable, or might be too old to be useful.

classmethod version() → YosysVersion | None¶

Return the version of the Yosys binary installed on the system.

Return type:: YosysVersion | None
Returns:: YosysVersion | None – The version of Yosys found, otherwise None if we are unable to determine the version.

classmethod data_dir() → Path¶

Return the path to the data directory for the Yosys installed on the system.

Return type:: Path
Returns:: pathlib.Path – The path to the Yosys data directory.
Raises:: torii.diagnostics.YosysError – If the invocation of Yosys failed for any reason. The error message will be the contents of standard error.

classmethod run(args: list[str], stdin: str = '', *, ignore_warnings: bool = False, src_loc_at: int = 0) → str¶

Run Yosys with the given arguments, and standard input.

Parameters:

args (list[str]) – Arguments to pass to the invocation of the Yosys process.
stdin (str) – Commands or other information to be fed to the standard input of the Yosys process.
ignore_warnings (bool) – Ignore any warnings that Yosys generates.
src_loc_at (int) – The source location to adjust the warning context to so Yosys warnings do not originate at the call site for run.

Return type:

str

Returns:

str – The contents of stdout from the Yosys process.

Raises:

torii.diagnostics.YosysError – Raised if Yosys returns a non-zero code. The exception message is the standard error output.

torii.tools.yosys.min_yosys_version(version: YosysVersion) → bool¶

Returns if the yosys version is greater than or equal to the minimum required version for Torii.

Note

The current Version requirement for Yosys is >=0.30,!=0.37.

Parameters:: version (YosysVersion) – The version of Yosys found on the system
Return type:: bool
Returns:: bool – If the version meets the minimum requirement.

torii.tools.yosys.find_yosys(requirement: ~collections.abc.Callable[[~torii.tools.yosys.YosysVersion], bool] = <function min_yosys_version>) → type[YosysBinary]¶

Attempt to find a valid Yosys install on the host system that matches the given version requirement.

Parameters:: requirement (collections.abc.Callable[[YosysVersion], bool]) – The method used to check to make sure the found version of Yosys is valid. Should return True if it is, otherwise False.
Return type:: type[YosysBinary]
Returns:: type[YosysBinary] – Proxy for running the requested version of Yosys.
Raises:: torii.diagnostics.YosysError – Raised if required Yosys version is not found.

C++ Compilation Helper¶

class torii.tools.cxx.ObjectType(value)¶

Type of object we want to build

EXEC = 1¶: Output type is an executable binary

LIB = 2¶: Output type is a static library

SHLIB = 3¶: Output type is a shared library

Build a binary object from the provided source files and compiler options.

Parameters:

name (str) – The name of the output object without its suffix.
output_dir (str | pathlib.Path) – The output directory used for the intermediate and final build products.
source_files (collections.abc.Iterable[str | pathlib.Path] | None) –
A list of C++ source files to build.

This can be used to include extra or externally generated source files from tooling, this allows you to not need to read the file in to pass to the source_listings argument which expects the full source of the file.
include_paths (collections.abc.Iterable[str | pathlib.Path] | None) – A list of extra include paths to pass to the compiler.
library_paths (collections.abc.Iterable[str | pathlib.Path] | None) – A list of extra library search paths to pass to the compiler.
defines (dict[str, str] | None) – A collection of preprocessor definitions to pass to the compiler.
output_type (ObjectType) – The type of object to build.
source_listings (dict[str, str] | None) –
A collection of filename: source listing pairs to include in the build. They will be written out to the build directory for inclusion in the build.

If the file already exists on the filesystem, then it is recommended to pass the path of the file via the source_files parameter rather than reading the file into memory to pass here.
extra_libs (collections.abc.Iterable[str | pathlib.Path] | None) – A list of extra libraries to link against.
extra_objs (collections.abc.Iterable[str | pathlib.Path] | None) – A list of extra object files to link with.
extra_cxx_opts (collections.abc.Iterable[str] | None) – A list of extra options to pass to the compiler.
extra_ld_opts (collections.abc.Iterable[str] | None) – A list of extra options to pass to the linker.
verbose (bool) – Enable verbose compiler output.
debug (bool) – Build in debug mode.

Return type:

Path

Returns:

pathlib.Path – The path to the final output file from the compilation process.

Raises:

RuntimeError – If we are not able to find any of the tools needed to build C++ binaries on this platform.
distutils.errors.CompileError – If the compilation of any of the source files fail.
distutils.errors.LinkError – If we are unable to link the final output binary.