3. CLI apps#
3.1. sc-config#
usage: sc-config [-h] <command> ...
-----------------------------------------------------------
SC app to view and change this machine's SiliconCompiler
configuration.
To list every setting and its value:
sc-config settings list
To change a setting, or put it back to its default:
sc-config settings set cache cleanupdays 30
sc-config settings unset cache cleanupdays
To add entries to a list, or remove them:
sc-config settings add scheduler-slurm sharedpaths /nfs/tools
sc-config settings remove scheduler-slurm sharedpaths /nfs/tools
To make an option a default for every project:
sc-config settings set schema-options scheduler,name slurm
To set the server job emails are sent through, and check it:
sc-config email set
sc-config email test [email protected]
To see where the cache is and how big, or collect what has gone unused:
sc-config cache show
sc-config cache clean -days 30 -dryrun
To print where SiliconCompiler keeps its settings, credentials and cache:
sc-config paths
-----------------------------------------------------------
positional arguments:
<command>
settings settings kept in ~/.sc/settings.json
email the SMTP server job emails are sent through
cache the cache of downloaded data sources and of tool data
paths print where SiliconCompiler keeps its settings, credentials and
cache
options:
-h, --help show this help message and exit
3.1.1. sc-config settings#
usage: sc-config settings [-h] <action> ...
View and change the settings kept in ~/.sc/settings.json. An administrator's system settings file supplies defaults, and can fix a setting so it cannot be changed here.
positional arguments:
<action>
list print every setting and its value
get print a setting's value
set change a setting
add add entries to a list setting
remove remove entries from a list setting
unset put a setting back to its default
options:
-h, --help show this help message and exit
Settings:
cache cleanupdays days a cache entry goes unused before the automatic sweep collects it; 0 turns the sweep off (default 90)
cache cleanupinterval fewest days between two automatic sweeps of a cache (default 7)
record region the region recorded in every run's manifest (default local)
scheduler-slurm sharedpaths path prefixes every Slurm node can read, so files under them are not copied (default [])
schema-options <keypath> the default of an option for every project, such as scheduler,name
showtask <extension> the tool, or tool/task, sc-show views a file with
opentask <extension> the interactive tool, or tool/task, a file is opened in
3.1.2. sc-config email#
usage: sc-config email [-h] <action> ...
Set the SMTP server job emails are sent through. The settings are kept in
~/.sc/email.json, readable only by you.
positional arguments:
<action>
set ask for each setting; Enter keeps the value shown, and the
password is never echoed
show print the settings, the password hidden
test send one message, to check the settings
options:
-h, --help show this help message and exit
3.1.3. sc-config cache#
usage: sc-config cache [-h] <action> ...
Show the cache of downloaded data sources and of tool data, and collect what
has gone unused. A sweep also runs on its own; sc-config settings changes how
often, and what it takes.
positional arguments:
<action>
show print where the cache is, how big, and when it was swept
clean remove the data sources unused for a number of days, and lock
files left behind
options:
-h, --help show this help message and exit
3.1.4. sc-config paths#
usage: sc-config paths [-h]
Print where SiliconCompiler keeps its settings, credentials and cache by
default, and which of them exist. A project's [option,cachedir] or
[option,credentials] can point elsewhere.
options:
-h, --help show this help message and exit
3.2. sc-install#
usage: sc-install [-h]
[-group {asic,asic-hls,asic-soda,fpga,digital-simulation,analog-simulation} [{asic,asic-hls,asic-soda,fpga,digital-simulation,analog-simulation} ...]]
[-prefix <path>] [-build_dir <path>] [-jobs <int>] [-force]
[-show] [-debug_machine]
[{bambu,bluespec,chisel,ghdl,gtkwave,icarus,icepack,keplerformal,klayout,magic,mlir,montage,netgen,nextpnr,openroad,opensta,sby,slurm,soda,surelog,surfer,sv2v,vcd2fst,verible,verilator,vpr,wildebeest,xdm,xyce,yosys,yosys-moosic} ...]
-----------------------------------------------------------
SC app install supported tools.
To install a single tool:
sc-install openroad
To install multiple tools:
sc-install openroad yosys klayout
To install a group of tools:
sc-install -group asic
To install tools in a different location:
sc-install -prefix /usr/local yosys
To build tools in a different location:
sc-install -build_dir /tmp yosys
To limit parallel build jobs (useful for memory-constrained systems):
sc-install yosys -jobs 4
To combine options (custom location with limited parallelism):
sc-install -prefix /opt/tools -jobs 8 openroad yosys
To force a rebuild even if the tool is already up to date:
sc-install -force yosys
To show the install script:
sc-install -show openroad
To system debugging information (this should only be used to debug):
sc-install -debug_machine
-----------------------------------------------------------
Tool groups:
asic: sv2v, yosys, openroad, klayout, opensta
asic-hls: bambu, yosys, openroad, klayout, opensta
asic-soda: mlir, soda, bambu, yosys, openroad, klayout, opensta
fpga: sv2v, yosys, wildebeest, vpr, opensta
digital-simulation: verilator, icarus, surfer
analog-simulation: xyce
-----------------------------------------------------------
positional arguments:
{bambu,bluespec,chisel,ghdl,gtkwave,icarus,icepack,keplerformal,klayout,magic,mlir,montage,netgen,nextpnr,openroad,opensta,sby,slurm,soda,surelog,surfer,sv2v,vcd2fst,verible,verilator,vpr,wildebeest,xdm,xyce,yosys,yosys-moosic}
tool to install (default: None)
options:
-h, --help show this help message and exit
-group {asic,asic-hls,asic-soda,fpga,digital-simulation,analog-simulation} [{asic,asic-hls,asic-soda,fpga,digital-simulation,analog-simulation} ...]
tool group to install (default: None)
-prefix <path> Prefix to use when installing tool (default:
/home/docs/.local)
-build_dir <path> Directory to build the tool in (default:
/home/docs/.sc/tool_build)
-jobs <int> Maximum number of parallel build jobs (default: number
of CPU cores) (default: None)
-force Force a rebuild even if the tool is already up to date
(default: False)
-show Show the install script and exit (default: False)
-debug_machine Show information about this machine and exit (default:
False)
3.3. sc-issue#
usage: sc-issue [-h] [-arg_index <str>] [-arg_step <str>] [-add_library <str>]
[-cfg <file>] [-exclude_libraries [<bool>]] [-file <file>]
[-hash_files [<bool>]] [-run [<bool>]] [-version]
[source ...]
-----------------------------------------------------------
Restricted SC app that generates a sharable testcase from a
failed flow or runs an issue generated with this program.
To generate a testcase, use:
sc-issue <design>.pkg.json
or with explicit flag:
sc-issue -cfg <stepdir>/outputs/<design>.pkg.json
or include a different step/index than what the cfg_file is pointing to:
sc-issue <design>.pkg.json -arg_step <step> -arg_index <index>
or include specific libraries while excluding others:
sc-issue <design>.pkg.json -exclude_libraries -add_library sram -add_library gpio
To run a testcase, use:
sc-issue -run sc_issue_<...>.tar.gz
or with explicit flag:
sc-issue -run -file sc_issue_<...>.tar.gz
-----------------------------------------------------------
positional arguments:
source Input files
options:
-h, --help show this help message and exit
-arg_index <str> ARG: index argument
-arg_step <str> ARG: step argument
-add_library <str> library to include in the testcase, if not provided
all libraries will be added according to the
-exclude_libraries flag
-cfg <file> configuration manifest
-exclude_libraries [<bool>]
flag to ensure libraries are excluded in the testcase
-file <file> filename for the generated testcase
-hash_files [<bool>] flag to hash the files in the schema before generating
the manifest
-run [<bool>] run a provided testcase
-version show program's version number and exit
3.4. sc-remote#
usage: sc-remote [-h] [-add <dir>] [-cancel [<bool>]] [-cfg <file>]
[-configure [<bool>]] [-delete [<bool>]] [-list [<bool>]]
[-reconnect [<bool>]] [-remove <dir>] [-server <str>]
[-credentials <file>] [-version]
-----------------------------------------------------------
SC app that provides an entry point to common remote / server
interactions.
To generate a configuration file, use:
sc-remote -configure
or to specify a specific server and/or port:
sc-remote -configure -server https://example.com
sc-remote -configure -server https://example.com:1234
to add or remove directories from upload whitelist, these
also support globbing:
sc-remote -configure -add ./fine_to_upload
sc-remote -configure -remove ./no_longer_okay_to_upload
to display the full configuration of the credentials file
sc-remote -configure -list
To check an ongoing job's progress, use:
sc-remote -cfg <stepdir>/outputs/<design>.pkg.json
To cancel an ongoing job, use:
sc-remote -cancel -cfg <stepdir>/outputs/<design>.pkg.json
To reconnect an ongoing job, use:
sc-remote -reconnect -cfg <stepdir>/outputs/<design>.pkg.json
To delete a job, use:
sc-remote -delete -cfg <stepdir>/outputs/<design>.pkg.json
-----------------------------------------------------------
options:
-h, --help show this help message and exit
-add <dir> path to add to the upload whitelist (only valid with
-configure)
-cancel [<bool>] cancel a running job on the remote
-cfg <file> configuration manifest
-configure [<bool>] create configuration file for the remote
-delete [<bool>] delete a job on the remote
-list [<bool>] print the current configuration (only valid with
-configure)
-reconnect [<bool>] reconnect to a running job on the remote
-remove <dir> path to remove from the upload whitelist (only valid
with -configure)
-server <str> address of server for configure (only valid with
-configure)
-credentials <file> Option: user credentials file
-version show program's version number and exit
3.5. sc-server#
python3 -m siliconcompiler.remote.server
usage: python3 -m siliconcompiler.remote.server [-h] [-cfg <file>]
[-auth [<bool>]]
[-checkinterval <int>]
[-cluster <str>]
[-maxuploadsize <int>]
[-nfsmount <dir>]
[-port <int>]
[-schemaversion <str>]
[-version]
---------------------------------------------------------
Silicon Compiler Collection Remote Job Server (sc-server)
---------------------------------------------------------
options:
-h, --help show this help message and exit
-cfg <file> configuration manifest
-auth [<bool>] Flag determining whether to enable authenticated and
encrypted jobs.
-checkinterval <int> Interval for client checks
-cluster <str> Type of compute cluster to use.
-maxuploadsize <int> Maximum size in MB of an uploaded job.
-nfsmount <dir> Directory of mounted shared NFS storage.
-port <int> Port number to run the server on.
-schemaversion <str> Schema version number
-version show program's version number and exit
3.6. sc-show#
usage: sc-show [-h] [-arg_index <str>] [-arg_step <str>] [-cfg <file>]
[-ext <str>] [-list [<bool>]] [-open [<bool>]]
[-screenshot [<bool>]] [-tool <str>] [-design <str>]
[-jobname <str>] [-version]
[source ...]
--------------------------------------------------------------
Restricted SC app that displays the layout of a design
based on a file provided or tries to display the final
layout based on loading the json manifest from:
build/<design>/job0/<design>.pkg.json
Examples:
sc-show
(displays build/adder/job0/write.views/0/outputs/adder.odb)
sc-show -design adder
(displays build/adder/job0/write.views/0/outputs/adder.odb)
sc-show -design adder -arg_step floorplan
(displays build/adder/job0/floorplan/0/outputs/adder.odb)
sc-show -design adder -arg_step place -arg_index 1
(displays build/adder/job0/place/1/outputs/adder.odb)
sc-show -design adder -jobname rtl2gds
(displays build/adder/rtl2gds/write.views/0/outputs/adder.odb)
sc-show build/adder/rtl2gds/adder.pkg.json
(displays build/adder/rtl2gds/write.views/0/outputs/adder.odb)
sc-show -design adder -ext odb
(displays build/adder/job0/write.views/0/outputs/adder.odb)
sc-show -design adder -tool klayout
(displays build/adder/job0/write.gds/0/outputs/adder.gds using klayout)
sc-show -design adder -ext odb -tool openroad
(displays build/adder/job0/write.views/0/outputs/adder.odb using openroad)
sc-show -design adder -tool klayout/show
(displays build/adder/job0/write.gds/0/outputs/adder.gds using klayout in show mode)
sc-show -design adder -ext def -tool openroad/show
(displays build/adder/job0/write.views/0/outputs/adder.def using openroad in show mode)
sc-show build/adder/job0/route/1/outputs/adder.def
(displays build/adder/job0/route/1/outputs/adder.def)
sc-show -list
(lists all registered show tools and their supported extensions)
sc-show -list -screenshot
(lists all registered screenshot tools and their supported extensions)
sc-show -list -open
(lists all registered open tools and their supported extensions)
sc-show -list -tool klayout
(lists only klayout show tasks and their supported extensions)
sc-show -list -tool openroad/show
(lists only the openroad/show task and its supported extensions)
sc-show -design adder -open
(opens build/adder/job0/write.views/0/outputs/adder.odb in an interactive open tool)
positional arguments:
source Input files
options:
-h, --help show this help message and exit
-arg_index <str> ARG: index argument
-arg_step <str> ARG: step argument
-cfg <file> configuration manifest
-ext <str> Specify the extension of the file to show.
-list [<bool>] List all registered show/screenshot/open tools and
their supported extensions.
-open [<bool>] Open the file with an interactive open tool instead of
a viewer.
-screenshot [<bool>] Generate a screenshot and exit.
-tool <str> Tool to use for showing the file.
-design <str> Option: Design library name
-jobname <str> Option: job name
-version show program's version number and exit
3.7. smake#
usage: smake [-h] [--file <file>] [--directory <directory>] [--version]
<target> ...
-----------------------------------------------------------
SC app that provides a Makefile-like interface to Python
configuration files. This utility app will analyze a file
named "make.py" (or the file specified with --file) to
determine the available targets.
To view the help, use:
smake --help
To view the help for a specific target, use:
smake <target> --help
To run a target, use:
smake <target>
To run a target from a different file, use:
smake --file <file> <target>
To run a target in a different directory, use:
smake -C <directory> <target>
To run a target with arguments, use:
smake <target> --arg1 value1 --arg2 value2
-----------------------------------------------------------
positional arguments:
<target> Target to execute
options:
-h, --help show this help message and exit
--file <file>, -f <file>
Use file as makefile, default is make.py
--directory <directory>, -C <directory>
Change to directory <directory> before reading the
makefile.
--version, -v show program's version number and exit
3.8. Support apps#
3.8.1. dashboard#
python3 -m siliconcompiler.apps.utils.dashboard
usage: dashboard [-h] [-arg_index <str>] [-arg_step <str>] [-cfg <file>]
[-graph_cfg <str>] [-port <int>] [-design <str>]
[-jobname <str>] [-version]
-----------------------------------------------------------
SC app to open a dashboard for a given manifest.
To open and allow the dashboard to autoload manifest:
python3 -m siliconcompiler.apps.utils.dashboard
To open by specifying manifest:
python3 -m siliconcompiler.apps.utils.dashboard -cfg <path to manifest>
To open by specifying design and optionally jobname:
python3 -m siliconcompiler.apps.utils.dashboard -design <name>
python3 -m siliconcompiler.apps.utils.dashboard -design <name> -jobname <jobname>
To specify a different port than the default:
python3 -m siliconcompiler.apps.utils.dashboard -cfg <path to manifest> -port 10000
To include another project object to compare to:
python3 -m siliconcompiler.apps.utils.dashboard -cfg <path to manifest>
-graph_cfg <name of manifest> <path to other manifest>
-graph_cfg <path to other manifest> ...
-----------------------------------------------------------
options:
-h, --help show this help message and exit
-arg_index <str> ARG: index argument
-arg_step <str> ARG: step argument
-cfg <file> configuration manifest
-graph_cfg <str> project name - optional, path to project manifest (json)
-port <int> port to open the dashboard app on
-design <str> Option: Design library name
-jobname <str> Option: job name
-version show program's version number and exit
3.8.2. summarize#
python3 -m siliconcompiler.apps.utils.summarize
usage: summarize [-h] [-cfg <file>] [-jobname <str>] [-version]
------------------------------------------------------------
Utility script to print job summary from a manifest
------------------------------------------------------------
options:
-h, --help show this help message and exit
-cfg <file> configuration manifest
-jobname <str> Option: job name
-version show program's version number and exit
3.8.3. replay#
python3 -m siliconcompiler.apps.utils.replay
usage: replay [-h] [-cfg <file>] [-file <file>] [-jobname <str>] [-version]
------------------------------------------------------------
Utility script to generate a replay script from a previous run.
------------------------------------------------------------
options:
-h, --help show this help message and exit
-cfg <file> configuration manifest
-file <file> Path to generate replay file to.
-jobname <str> Option: job name
-version show program's version number and exit
3.8.4. OpenROAD OpenRCX Merge Utility#
python3 -m siliconcompiler.tools.openroad.utils.rcx_merge
usage: rcx_merge.py [-h] [-o FILE] [-c NAME[,NAME...]] RULES [RULES ...]
Merge per-corner OpenRCX .rules files into a single multi-corner rules file.
positional arguments:
RULES per-corner OpenRCX .rules files, in corner order
options:
-h, --help show this help message and exit
-o FILE, --output FILE
output file (defaults to stdout)
-c NAME[,NAME...], --corner-names NAME[,NAME...]
optional comma-separated corner names for a
documentation-only 'Corners' line; must match the
number of inputs
example:
python -m siliconcompiler.tools.openroad.utils.rcx_merge \
-o ext_pattern.rules.3corners \
corner_min.rules corner_typ.rules corner_max.rules
The order of the input files defines the corner indices (DensityModel 0, 1,
...) in the merged output.
3.8.5. OpenROAD PEX Estimate Calibration Utility#
python3 -m siliconcompiler.tools.openroad.utils.pex_calibrate
usage: pex_calibrate.py [-h] [-o DIR] [--design DIR] [--rerun] [--score]
[--print]
target
Calibrate OpenROAD's pre-route parasitic estimate for a PDK and emit the add_openroad_rclayer / add_openroad_rccorrection lines for its setup.
positional arguments:
target target setup function: a bare name under
siliconcompiler.targets (e.g. 'freepdk45_demo'), or a
'module:function' / 'module.function' path
options:
-h, --help show this help message and exit
-o DIR, --outdir DIR directory for the <pdk>.rclayer.csv / <pdk>.rccorr.csv
data files (default: ./pex)
--design DIR survey design directory holding <name>.v (and optional
<name>.sdc); repeatable. Defaults to the bundled demo
suite.
--rerun recompute even if the data files already exist
--score after calibrating, re-route the survey with the
calibration applied and report the per-net estimate
error before vs after (extra runtime)
--print only print the PDK setup lines from existing data
files (never run)
examples:
# calibrate FreePDK45 on the bundled demo survey (writes ./pex/<pdk>.*.csv)
python -m siliconcompiler.tools.openroad.utils.pex_calibrate freepdk45_demo
# force a recompute
python -m siliconcompiler.tools.openroad.utils.pex_calibrate freepdk45_demo --rerun
# also quantify the win: re-route uncorrected vs calibrated and print the
# per-net estimate error before/after (extra runtime)
python -m siliconcompiler.tools.openroad.utils.pex_calibrate freepdk45_demo --score
# use your own survey designs (each DIR holds <name>.v [and <name>.sdc])
python -m siliconcompiler.tools.openroad.utils.pex_calibrate freepdk45_demo \
--design designs/aes --design designs/jpeg