ext_tools.ext_tools module¶

class ext_tools.ext_tools.ExtTools(settings)¶

Bases: object

This class provides an interface for all stages to utilize external tools based on system configuration.

static abc_dprove(file_in)¶

Uses ABC’s dprove method to validate a circuit.

Parameters:	file_in (str) – An SQCC file with the CUT already in place in Verilog or BLIF format. If Verilog format is used, Yosys will be used to convert to BLIF. ABC does not support vectors and BLIF is a bit format.
Returns:	`True` if the circuit does not violate the specified quality constraints, otherwise `False`.
Raises:	`ValueError` – If the input file format is incorrect.

static abc_pdr(file_in)¶

Uses ABC’s pdr method to validate a circuit.

Parameters:	file_in (str) – Verilog or BLIF format. If Verilog format is used, Yosys will be used to convert to BLIF. ABC does not support vectors and BLIF is a bit format.
Returns:	`True` if the circuit does not violate the specified quality constraints, otherwise `False`.
Raises:	`ValueError` – If the input file format is incorrect.

static abc_if(file_in, file_out)¶

Uses ABC’s if method to generate statistics about a circuit.

A stat file is created and stored as file_out.

Parameters:	file_in (str) – The absolute path to the input circuit file in Verilog or BLIF format. If Verilog format is used, Yosys will be used to convert to BLIF. ABC does not support vectors and BLIF is a bit format. file_out (str) – The absolute path to the stat file in any writable format (use `*.stat` by convention).

static precisionScaling(file_in, file_out, mask, tool='abc')¶

Generates an approximated circuit using precision scaling.

The mask parameter specifies the number of output bits to lock and their values. Returns the number of changes.

Parameters:

file_in (str) – The absolute path to the circuit file to be approximated in Verilog or BLIF format. If Verilog format is used, Yosys will be used to convert to BLIF. ABC does not support vectors and BLIF is a bit format.
file_out (str) – The absolute path to the result circuit file in Verilog or BLIF format.
mask (str) – Specifies number and kind of output bits to lock as a string containing only 1s and 0s. The length of the string must equal the output size of the input circuit.
tool (str, optional) – Determines which external tool to use (abc or yosys). Default value is abc.

Note

Right now only ABC is supported for this function.

Returns:	The number of changes made for approximation as returned by the external tool.
Raises:	`ValueError` – If the specified `tool` is not supported.

static aigRewriting(qc_file, file_in, file_out, effort=2, tool='abc')¶

Generates an approximated circuit using AIG rewriting and returns the number of changes.

Parameters:

qc_file (str) – The absolute path to the circuit file that specifies the quality constraitns to be used for approximation in Verilog or BLIF format.If Verilog format is used, Yosys will be used to convert to BLIF. ABC does not support vectors and BLIF is a bit format.
file_in (str) – The absolute path to the circuit to be approximated in Verilog or BLIF format. If Verilog format is used, Yosys will be used to convert to BLIF. ABC does not support vectors and BLIF is a bit format.
file_out (str) – The absolute path to the result circuit file in Verilog or BLIF format.
effort (int, optional) – Effort parameter supplied to the external tool. For ABC, it specifies the number of critical paths that are checked: 0: 1 critical path 1: All cricital paths once 2: All critical paths as long as possible
tool (str, optional) – Determines which external tool to use (abc or yosys). Default value is abc.

Note

Right now only ABC is supported for this function.

Returns:	The number of changes made for approximation as returned by the external tool.
Raises:	`ValueError` – If the specified `tool` is not supported.

static synthesize(file_in, file_out, top_module, f_noattr=1, tool='yosys', cmd='techmap')¶

Synthesizes a circuit by mapping it to a specific technology and writes the resulting circuit to another file.

Parameters:

file_in (str) – The absolute path to the input circuit file in Verilog or BLIF format.
file_out (str) – The absolute path to the result circuit file in Verilog or BLIF format.
top_module (str) – The name of the input circuit’s top level module.
f_noattr (int, optional) – Flag specifying whether the noattr flag should be used for Yosys (1) or not (0). Default value is 1.
tool (str, optional) – Determines which external tool to use (yosys or abc). Default value is yosys.
cmd (str, optional) – The command to be used by the used tool. Default value (for Yosys) is techmap.

Note

Right now only Yosys with techmap command is supported for this function.

Raises:	`ValueError` – If the specified `tool` is not supported.

static extractAndWriteModule(file_in, file_out, top_module, module, f_noattr=1, tool='yosys')¶

Writes a new circuit file containing a module from the input circuit using the given tool.

Parameters:

file_in (str) – The absolute path to the circuit file from which to extract the module in Verilog or BLIF format.
file_out (str) – The absolute path to the result circuit file in Verilog or BLIF format.
top_module (str) – The name of the top level module of the input circuit.
module (str) – The name of the module to extract.
f_noattr (int, optional) – Flag specifying whether the noattr flag should be used for writing the result file with Yosys (1) or not (0). Default value is 1.
tool (str, optional) – Determines which external tool to use (yosys or abc). Default value is yosys.

Note

Right now only Yosys is supported for this function.

Raises:	`ValueError` – If the specified `tool` is not supported.

static findCandidates(file_in, top_module, file_separated_design, file_solutions, solution_name, pattern, tool='yosys')¶

Searches for PGSL pattern in the input circuit and extracts all matches to separate files.

Each match is encapsulated in a Verilog module and written to a solutions file. The modified input design is written to its own file.

Parameters:

file_in (str) – The absolute path to the input circuit file in Verilog or BLIF format.
top_module (str) – The name of the top level module of the input circuit.
file_separated_design (str) – The absolute path to the file in which the modified input design will be stored in Verilog format.
file_solutions (str) – The absolute path to the file in which the found solutions are stored in Verilog format.
solution_name (str) – TODO: Add arg description
pattern (str) – The PGSL pattern used for the search.
tool (str, optional) – Determines which external tool to use (yosys or abc). Default value is yosys.

Note

Right now only Yosys is supported for this function.

Note

There is currently no Yosys implementation available.

static flattenDesign(file_in, file_out, top_module, f_techmap=1, f_noattr=1, tool='yosys')¶

Removes hierarchical structures from a circuit design, i.e. removes modules and subcircuits.

Parameters:

file_in (str) – The absolute path to the circuit file to be flattened in Verilog or BLIF format.
file_out (str) – The absolute path to the result circuit file in Verilog or BLIF format.
top_module (str) – The name of the input circuit’s top level module.
f_techmap (int, optional) – Flag specifying whether the techmap command of Yosys should be executed before flattening (1) or not (0). Default value is 1.
f_noattr (int, optional) – Flag specifying whether the noattr flag should be used for writing the result circuit when using Yosys (1) or not (0). Default value is 1.
tool (str, optional) – Determines which external tool to use (yosys or abc). Default value is yosys.

Note

Right now only Yosys is supported for this function.

Raises:	`ValueError` – If the specified `tool` is not supported.

static listModules(file_in, top_module, select_pattern='', tool='yosys')¶

Return a list with all module names occurring in a circuit design.

The module names can be selected using a string pattern.

Parameters:

file_in (str) – The absolute path to the input circuit file in Verilog or BLIF format.
top_module (str) – The name of the input circuit’s top level module.
select_pattern (str, optional) – Specifies the pattern by which module names are selected. If not empty, only names matching the pattern will be included in the result. Default value is "".
tool (str, optional) – Determines which external tool to use (yosys or abc). Default value is yosys.

Note

Right now only Yosys is supported for this function.

Returns:	A list containing all module names in the given circuit design matching the specified pattern.
Return type:	list of str
Raises:	`ValueError` – If the specified `tool` is not supported.

static renameModule(file_in, file_out, module, new_module, f_noattr=1, tool='yosys')¶

Change sthe name of a module in a circuit design and writes the result into another file.

Parameters:

file_in (str) – The absolute path to the input circuit file in Verilog or BLIF format.
file_out (str) – The absolute path to the result circuit file in Verilog or BLIF format.
module (str) – The name of the module to be renamed.
new_module (str) – The new name for the module.
f_noattr (int, optional) – Flag specifying whether the noattr flag should be used for writing the result circuit when using Yosys (1) or not (0). Default value is 1.
tool (str, optional) – Determines which external tool to use (yosys or abc). Default value is yosys.

Note

Right now only Yosys is supported for this function.

Raises:	`ValueError` – If the specified `tool` is not supported.

static replaceModules(file_in, file_out, top_module, files_modules, f_noattr=1, tool='yosys')¶

Deletes modules from a circuit design, replaces them with circuits from other files and writes the resulting circuit to another file.

Parameters:

file_in (str) – The absolute path to the input circuit file in Verilog or BLIF format.
file_out (str) – The absolute path to the output circuit file in Verilog or BLIF format.
top_module (str) – The name of the top level module in the input circuit.
files_modules (list of tuple) – A list containing tuples (file, module) where module is the name of a module in the input circuit to be replaced and file is the absolute path to a circut file containing the replacement module.
f_noattr (int, optional) – Flag specifying whether the noattr flag should be used for writing the resulting circuit when using Yosys (1) or not (0). Default value is 1.
tool (str) – Determines which external tool to use (yosys or abc). Default value is yosys.

Note

Right now only Yosys is supported for this function.

Raises:	`ValueError` – If the specified `tool` is not supported.

static readFiles(files, file_out, top_module, tool='yosys', f_check_hierarchy=False, f_flatten=False, f_noattr=True, f_opt=False)¶

Reads a number of circuits and writes them into a single file.

Parameters:

files (list of str) – List containing absolute paths to the circuit files to read in Verilog or BLIF format.
file_out (str) – The absolute path to the result circuit file in Verilog or BLIF format.
top_module (str) – The name of the result circuit’s top level module. If f_check_hierarchy is set to True, all input files must have this top module.
tool (str, optional) – Determines which external tool to use (yosys or abc). Default value is yosys.
f_check_hierarchy (bool, optional) – Flag specifying whether each input circuit should be checked for the correct top level module (True) or not (False). Default value is False.
f_flatten (bool, optional) – Flag specifying whether the result circuit should be flattened (True) or not (False). Default value is False.
f_noattr (bool, optional) – Flag specifying whether the noattr flag should be used for writing circuits with Yosys (True) or not (False). Default value is True.
f_opt (bool, optional) – Flag specifying whether the result circuit should be optimized (True) or not (False). Default value is False.

Note

Right now only Yosys is supported for this function.

Raises:	`ValueError` – If the specified `tool` is not supported.

static verilogToBlif(file_in, file_out, top_module, tool='yosys', f_flatten=False)¶

Converts a Verilog file to BLIF format.

Parameters:

file_in (str) – The absolute path to the input circuit file in Verilog format.
file_out (str) – The absolute path to the result circuit file in BLIF format.
top_module (str) – The name of the top-level module of the input circuit.
tool (str, optional) – Determines which external tool to use (yosys or abc). Default value is yosys.
f_flatten (bool, optional) – Flag specifying whether the result circuit should be flattened (True) or not (False). Default value is False.

Raises:

ValueError – If the specified tool is not supported.

static blifToVerilog(file_in, file_out, top_module, tool='yosys', f_flatten=False, f_wideports=True, f_noattr=True)¶

Converts a BLIF file to Verilog format.

Parameters:

file_in (str) – The absolute path to the input circuit file in BLIF format.
file_out (str) – The absolute path to the result circuit file in Verilog format.
top_module (str) – The name of the top-level module of the input circuit.
tool (str, optional) – Determines which external tool to use (yosys or abc). Default value is yosys.
f_flatten (bool, optional) – Flag specifying whether the result circuit should be flattened (True) or not (False). Default value is False.
f_wideports (bool, optional) – Flag specifying whether it should be attempted to restore busses in the result circuit when using Yosys (True) or not (False). Default value is True.
f_noattr (bool, optional) – Flag specifying whether the noattr flag should be used for writing the result circuit using Yosys (True) or not (False). Default value is True.

Raises:

ValueError – If the input or output file format is incorrect or the specified tool is not supported.

static ic3(file_in, top_module, name_q, f_seq)¶

Performs circuit validation using Yosys’ sat command.

Parameters:	file_in (str) – The absolute path to the input circuit file containing an SQCC in Verilog or BLIF format. top_module (str) – The name of the input circuit’s top level module. name_q (str) – The parameter to be added after the `-prove` flag of the `sat` command. TODO: Add proper description here f_seq (bool) – Flag specifying whether the input circuit is sequential (`True`) or not (`False`).
Returns:	`True` if the validation was successful, `False` otherwise.
Return type:	bool

static compileVerilog(source_files, compiled_file, top_module='')¶

Compiles a list of Verilog files to an executable simulation file.

The files must be in Verilog format and include all modules that are instantiated. The name of the root module can be specified. It must be specified if the design hierarchy does not have a unique top level module.

Parameters:

source_files (list of str) – A list containing the absolute paths to all Verilog source files.
compiled_file (str) – The absolute path to the compiled and executable simulation file. Standard format is *.vvp.
top_module (str, optional) – The name of the module to use as root module to execute. Only this module will be simulated when running the compiled simulation file.

Raises:

ValueError – If no source files are specified.
RuntimeError – If the iverilog command exits with an error.

static compileVerilogFileList(source_list_file, compiled_file, top_module='')¶

Compiles a list of Verilog files specified in a separate file to an executable simulation file.

The files must be in Verilog format and include all modules that are instantiated. The name of the root module can be specified. It must be specified if the design hierarchy does not have a unique top level module.

Parameters:

source_list_file (str) – The absolute path to the file in which the Verilog source files are listed. This file must be a readable text file that specifies one source file per line and ends with a blank line (!).
compiled_file (str) – The absolute path to the compiled and executable simulation file. Standard format is *.vvp.
top_module (str, optional) – The name of the module to use as root module to execute. Only this module will be simulated when running the compiled simulation file.

Raises:

RuntimeError – If the iverilog command exits with an error.

static compileVerilogMixed(source_files, source_list_file, compiled_file, top_module='')¶

Compiles a list of Verilog files specified explicitly or in a separate file to an executable simulation file.

Source file names can be specified explicitly or by a file containing one source file name per line. The files must be in Verilog format and include all modules that are instantiated. The name of the root module can be specified. It must be specified if the design hierarchy does not have a unique top level module.

Parameters:

source_files (list of str) – A list containing the absolute paths to Verilog source files.
source_list_file (str) – The absolute path to the file in which other Verilog source files are listed. This file must be a readable text file that specifies one source file per line and ends with a blank line (!).
compiled_file (str) – The absolute path to the compiled and executable simulation file. Standard format is *.vvp.
top_module (str, optional) – The name of the module to use as root module to execute. Only this module will be simulated when running the compiled simulation file.

Raises:

RuntimeError – If the iverilog command exits with an error.

static runCompiledVerilog(compiled_file, remove_file=False)¶

Runs a compiled Verilog simulation file.

Parameters:	compiled_file (str) – The absolute path to the compiled simulation file. By convention, simulation files have the format `.vvp`. remove_file* (bool) – Flag specifying whether the compiled file should be removed after the simulation was executed. Default value is `False`.
Raises:	`RuntimeError` – If the `vvp` command exits with an error.