A complete set of supported tools can be found in tools.

Integrating a New Tool#

To add support for a new EDA tool, you need to create a Python-based “driver” that teaches SiliconCompiler how to interact with it. Think of a driver as a universal adapter: it translates SiliconCompiler’s standardized hardware compilation flow into the specific commands, scripts, and file formats that a particular tool understands.

A complete driver consists of:

One or more Task classes: Defines a specific job that the tool can perform, such as synthesis (syn) or place-and-route (place). Each task specifies its inputs, outputs, and how to generate the command-line arguments.

A complete list of built-in tools can be found in the Tools reference.

The Structure of a Tool Driver#

A tool driver is a Python module that typically defines at least one Task class.

from siliconcompiler import Task

class MyTask(Task):
    """A task for running the tool in a specific way."""
    # Task-level implementation goes here.

    def setup(self):
        # This is the main configuration method.
        pass

    # Other required methods (runtime_options, post_process, etc.)

The setup() Method: Core Configuration#

The Task.setup() method is the heart of the driver. It’s called for each step in the flow and is responsible for configuring all aspects of the tool and task. Inside this method, you have access to the project object to define your settings.

Step 1: Basic Tool Configuration#

First, you tell SiliconCompiler about the tool’s executable and how to check its version.

def setup(self):
    # Get the tool and task name for the current step.
    tool = self.tool
    task = self.task

    # 1. Point to the executable.
    self.set_exe('my_tool_binary')

    # 2. Define how to check the version.
    #    'vswitch' is the command-line flag to print the version.
    #    'version' is a list of known-good version specifiers.
    self.add_vswitch('--version')
    self.add_version('>=2.1')

Step 2: Task-Specific Configuration#

Next, you define what the specific task needs to run and what it will produce.

def setup(self):
    # ... (tool setup from above)

    # 3. Define required inputs.
    #    This tells SC to expect a Verilog file from the 'input' node.
    self.add_input_file('verilog.v')

    # 4. Define expected outputs.
    #    This tells SC that this task will produce a new Verilog netlist.
    self.add_output_file('verilog.vg')

    # 5. Define required schema parameters.
    #    This ensures the flow will fail early if a critical setting is missing.
    self.add_required_key('asic', 'pdk')
    self.add_required_key('asic', 'logiclib')

    # 6. For script-based tools (like TCL), define the entry script.
    self.set_script('run_my_tool.tcl')

Execution Lifecycle Methods#

Beyond the initial setup, a Task class implements several methods that are called at different points during the Task.run() process.

runtime_options()#

This method generates the command-line options for the tool. It is called at execution time, which is critical for distributed systems where absolute file paths are only known on the execution machine.

Why is this separate from setup()? Task.setup() is run early to validate the entire flow, while Task.runtime_options() runs just-in-time to build the command, ensuring all paths are resolved correctly.

def runtime_options(self):
    '''
    Generates the command-line arguments for the tool.
    '''
    cmdlist = []

    # Get a list of all Verilog source files.
    cmdlist.append("verilog.v")

    # Add the output file path.
    cmdlist.append('-o verilog.vg')

    # Add the top module name.
    cmdlist.append(f'-top {self.design_topmodule}')

    return cmdlist

post_process()#

This method is called after the tool executable has finished. Its primary purpose is to parse log files and report metrics back to the SiliconCompiler database. It can also be used to modify or reformat output files.

def post_process(self):
    '''
    Parses tool output and reports metrics.
    '''
    # Get the path to the log file for this step.
    log_file = self.get_logpath("exe")

    # Example: Parse the log file for the final cell area.
    with open(log_file, 'r') as f:
        for line in f:
            if line.startswith('Final Area:'):
                area = float(line.split()[-1])
                # Record the metric in the SC database.
                self.record_metric('cellarea', area, 'um^2')

pre_process() and run()#

Task.pre_process(): A hook that runs immediately before the tool executable is launched. Useful for last-minute adjustments based on results from prior steps.
Task.pre_process(): For pure-Python tools. If this method is defined, SiliconCompiler will execute this Python function instead of an external command-line executable. It should return 0 on success.

Version Handling#

To ensure reproducible builds, SiliconCompiler has a robust version-checking system. You may need to implement these helper methods in your Tool class.

Task.parse_version(): The output of exe –version can be messy. This function parses the raw stdout string and returns a clean version number (e.g., “2.1.3”).
Task.normalize_version(): SC’s version checker uses the Python PEP-440 standard. If your tool uses a non-standard versioning scheme (e.g., 2.1+a4b8c1), this function should convert it to a compatible format (e.g., 2.1.post0.dev-a4b8c1).

Interface for TCL-Based Tools#

For tools that are driven by TCL scripts, SiliconCompiler simplifies configuration by writing a manifest file (sc_manifest.tcl) in the work directory. Your TCL script should source this file. It provides a nested TCL dictionary called sc_cfg containing the entire project configuration.

Your TCL script is responsible for reading from this dictionary and applying the settings.

# In your run_my_tool.tcl script:

# Source the manifest to load the configuration
source sc_manifest.tcl

# Helper function to get the top-level module name
set sc_design [sc_top]

# Extract values from the configuration dictionary
set sc_asiclibs [sc_cfg_get asic asiclib]
set sc_pdk      [sc_cfg_get asic pdk]

# Now use these TCL variables to run tool-specific commands
read_liberty -lib $sc_asiclibs
...

API Quick Reference#

The Task class provides a rich API for defining and controlling how a tool operates. The methods are grouped below by their primary function.

Task init methods#

add_parameter

Adds a custom parameter ('var') to the task definition.

Core Implementation Methods#

These are the main methods you will implement in your Task subclass to define its behavior.

`tool`	str: The name of the tool associated with this task.
`task`	str: The name of this task.
`parse_version`	Parses the tool's version from its stdout.
`normalize_version`	Normalizes a version string to a standard format.
`setup`	A hook for setting up the task before execution.
`pre_process`	A hook for pre-processing before the main tool execution.
`runtime_options`	Constructs the default runtime options for the task.
`run`	The main execution logic for Python-based tasks.
`post_process`	A hook for post-processing after the main tool execution.

Configuration Methods#

These methods are called within your Task.setup() implementation to configure the task’s properties.

Tools settings#

`set_exe`	Sets the executable, version switch, and script format for a tool.
`set_path`	Sets the directory path where the tool's executable is located.
`add_version`	Adds a supported version specifier for the tool.
`add_vswitch`	Adds the command-line switch used to print the tool's version.
`add_licenseserver`	Configures a license server connection for the tool.
`add_sbom`	Adds a Software Bill of Materials (SBOM) file for a tool version.

Task settings#

`add_commandline_option`	Add to the command line options for the task
`add_input_file`	Add a required input file from the previous step in the flow.
`add_output_file`	Add an output file that this task will produce file and ext are mutually exclusive.
`add_parameter`	Adds a custom parameter ('var') to the task definition.
`add_postscript`	Adds a script to be executed after the main tool command.
`add_prescript`	Adds a script to be executed before the main tool command.
`add_regex`	Adds a regular expression for parsing the tool's log file.
`add_required_key`	Adds a required keypath to the task driver. If the key is valid relative to the task object
`add_warningoff`	Adds a warning message or code to be suppressed during log parsing.
`set_environmentalvariable`	Sets an environment variable for the tool's execution context.
`set_logdestination`	Configures the destination for log files.
`set_refdir`	Sets the reference directory for tool scripts and auxiliary files.
`set_script`	Sets the main entry script for a script-based tool (e.g., a TCL script).
`set_threads`	Sets the requested thread count for the task

Runtime Accessor Methods#

These methods are used to get information about the current state of the flow during execution (e.g., inside Task.runtime_options() or Task.post_process()).

`compute_input_file_node_name`	Generates a unique name for an input file based on its originating node.
`design_name`	The name of the design.
`design_topmodule`	The top module of the design for the current node.
`get_commandline_options`	Returns the command line options specified
`get_files_from_input_nodes`	Returns a dictionary of files from input nodes, mapped to the node they originated from.
`get_fileset_file_keys`	Collect a set of keys for a particular filetype.
`get_logpath`	Returns the relative path to a specified log file.
`get_output_files`	Gets the set of output files defined for this task.
`get_threads`	Returns the number of threads requested.
`has_breakpoint`	Checks if a breakpoint is set for this task.
`has_postscript`	Checks if any post-execution scripts are configured for the task.
`has_prescript`	Checks if any pre-execution scripts are configured for the task.
`index`	The index for the current runtime.
`nodeworkdir`	The path to the node's working directory.
`record_metric`	Records a metric and associates the source file with it.
`step`	The step for the current runtime.
`task`	str: The name of this task.
`tool`	str: The name of the tool associated with this task.

Tool post process methods#

record_metric

Records a metric and associates the source file with it.

Documentation methods#

These methods are used for auto-generating documentation for your tool.

make_docs

Generate the documentation representation for this schema.

Class Reference#

Task#

Class siliconcompiler.Task

`Task.active_dataroot`	Use this context to set the dataroot parameter on files and directory parameters.
`Task.add`	Adds item(s) to a schema parameter list.
`Task.add_commandline_option`	Add to the command line options for the task
`Task.add_input_file`	Add a required input file from the previous step in the flow.
`Task.add_licenseserver`	Configures a license server connection for the tool.
`Task.add_output_file`	Add an output file that this task will produce file and ext are mutually exclusive.
`Task.add_parameter`	Adds a custom parameter ('var') to the task definition.
`Task.add_postscript`	Adds a script to be executed after the main tool command.
`Task.add_prescript`	Adds a script to be executed before the main tool command.
`Task.add_regex`	Adds a regular expression for parsing the tool's log file.
`Task.add_required_key`	Adds a required keypath to the task driver. If the key is valid relative to the task object
`Task.add_sbom`	Adds a Software Bill of Materials (SBOM) file for a tool version.
`Task.add_version`	Adds a supported version specifier for the tool.
`Task.add_vswitch`	Adds the command-line switch used to print the tool's version.
`Task.add_warningoff`	Adds a warning message or code to be suppressed during log parsing.
`Task.check_exe_version`	Checks if the reported version of a tool satisfies the requirements specified in the schema.
`Task.check_filepaths`	Verifies that paths to all files in manifest are valid.
`Task.compute_input_file_node_name`	Generates a unique name for an input file based on its originating node.
`Task.find_files`	Returns absolute paths to files or directories based on the keypath provided.
`Task.find_task`	Finds registered task(s) in a project that match the calling class.
`Task.generate_replay_script`	Generates a shell script to replay the task's execution.
`Task.get`	Returns a parameter field from the schema.
`Task.get_commandline_options`	Returns the command line options specified
`Task.get_dataroot`	Returns absolute path to the data directory.
`Task.get_exe`	Determines the absolute path for the task's executable.
`Task.get_exe_version`	Gets the version of the task's executable by running it with a version switch.
`Task.get_files_from_input_nodes`	Returns a dictionary of files from input nodes, mapped to the node they originated from.
`Task.get_fileset_file_keys`	Collect a set of keys for a particular filetype.
`Task.get_logpath`	Returns the relative path to a specified log file.
`Task.get_output_files`	Gets the set of output files defined for this task.
`Task.get_runtime_arguments`	Constructs the command-line arguments needed to run the task.
`Task.get_runtime_environmental_variables`	Determines the environment variables needed for the task.
`Task.get_tcl_variables`	Gets a dictionary of variables to define for the task in a Tcl manifest.
`Task.get_threads`	Returns the number of threads requested.
`Task.has_breakpoint`	Checks if a breakpoint is set for this task.
`Task.has_postscript`	Checks if any post-execution scripts are configured for the task.
`Task.has_prescript`	Checks if any pre-execution scripts are configured for the task.
`Task.hash_files`	Generates hash values for a list of parameter files.
`Task.make_docs`	Generate the documentation representation for this schema.
`Task.normalize_version`	Normalizes a version string to a standard format.
`Task.parse_version`	Parses the tool's version from its stdout.
`Task.post_process`	A hook for post-processing after the main tool execution.
`Task.pre_process`	A hook for pre-processing before the main tool execution.
`Task.record_metric`	Records a metric and associates the source file with it.
`Task.run`	The main execution logic for Python-based tasks.
`Task.run_task`	Executes the task's main process.
`Task.runtime`	A context manager to set the runtime information for a task.
`Task.runtime_options`	Constructs the default runtime options for the task.
`Task.select_input_nodes`	Determines which preceding nodes are inputs to this task.
`Task.set`	Sets a schema parameter field.
`Task.set_dataroot`	Registers a data source by name, path, and optional version tag.
`Task.set_environmentalvariable`	Sets an environment variable for the tool's execution context.
`Task.set_exe`	Sets the executable, version switch, and script format for a tool.
`Task.set_logdestination`	Configures the destination for log files.
`Task.set_path`	Sets the directory path where the tool's executable is located.
`Task.set_refdir`	Sets the reference directory for tool scripts and auxiliary files.
`Task.set_script`	Sets the main entry script for a script-based tool (e.g., a TCL script).
`Task.set_threads`	Sets the requested thread count for the task
`Task.setup`	A hook for setting up the task before execution.
`Task.setup_work_directory`	Creates the runtime directories needed to execute a task.
`Task.task`	str: The name of this task.
`Task.tool`	str: The name of the tool associated with this task.
`Task.unset`	Unsets a schema parameter.
`Task.write_task_manifest`	Writes the manifest needed for the task in the format specified by the tool.