CHAPTER TWO

Living in the Shell: Driving the Tool Without Guessing

By the end of this chapter you will be able to start a design planning session that configures itself the same way every time, ask the tool what its own commands and options do, prove what your numbers mean before you trust them, and use more than one core without wasting a licence — and you will be able to hand the whole session to a colleague as a set of files rather than a set of instructions.

Why this chapter matters in a real project

Chapter 1 was about decisions. This chapter is about the difference between an engineer who can make those decisions once and an engineer who can make them every day, on a design too large to hold in their head.

Almost every wasted week in physical design starts somewhere in this chapter. A number that was a thousand times too large because a unit had been changed and nobody noticed. An application option that was set yesterday, on a different block, and quietly did nothing. A script that failed at line 40 and kept going, producing a database that looked finished and was not. A run that took nine hours because it used one core out of thirty-two, or a run that took nine hours because it used thirty-two cores badly and queued behind itself. A result nobody could reproduce, because the only record of how it was made was a log file that the next run overwrote.

None of that is glamorous. All of it is preventable, with habits that cost minutes. This chapter teaches the habits and the commands behind them.

Prerequisites

Chapter 1: what design planning produces, what a block is, and what the readiness gates are for. You do not need any Tcl experience — the Tcl you need is introduced here. You do not need to have run the tool before.

Learning objectives

2.1 The beginner’s mental model

Start with a bench

A machinist who shares a workshop does four things before touching a workpiece. She checks that the tools are where they always are, because a habit that depends on hunting for a tool is not a habit. She checks which measuring set is on the bench, because a number without a unit is not a measurement. She writes what she does in the logbook, because next month somebody will ask why the part is 0.2 mm undersized. And if the job is big, she decides how many pairs of hands can usefully work on it, knowing that two people on a job that cannot be divided just get in each other's way.

A design planning session is that bench. The tools are the commands, and where they live is decided by your setup files. The measuring set is the unit system, and it can be changed without anything looking different. The logbook is the command log, which the tool writes whether or not you ever read it. And the extra hands are cores and machines, which help exactly as much as the work can be divided and not one bit more.

Now the engineering model

The tool operates in the X Window environment on UNIX or Linux and gives you two interfaces onto one session: a shell command-line interface called icc2_shell, and a graphical user interface. The shell is always available for the whole session; you can start or exit a session from either one, and you can open or close the graphical interface at any point without ending the session.

The command language is Tcl — the tool command language used across the electronic design automation industry — with extensions that add the tool's own commands. That single fact has a large consequence: everything you can do in Tcl, you can do here. Variables, conditionals, loops, procedures and script files are not add-ons; they are the language you are already typing in.

There is one more thing to know before anything else. Starting the shell with the design planning option puts it in a design planning mode that enables only the functionality, commands and operations related to design planning tasks, and restricts tool usage in other areas. That restriction is a feature: it is much harder to do the wrong thing at the wrong stage when the wrong thing is not available.

Do not confuse these

2.2 The concepts, built in dependency order

2.2.1 Two interfaces, one session

The shell command-line interface is a text-only environment in which you type commands at a prompt. It is what scripts, batch runs and push-button flows use, and it is the interface this book teaches. The graphical interface is a separate window onto the same session; you can open and close it at will, and Chapter 4 onwards will point at the places where looking at a floorplan is worth more than reading a report about it.

Two consequences matter now. First, anything you can do in one interface you are doing to the same session — there is no “GUI mode” with a separate state. Second, output goes to both: when you run a command, the tool echoes the output — processing messages, warnings and errors — in the shell and, if the graphical interface is open, in its console log view.

2.2.2 Starting a session, and leaving it

Before anything else, the directory containing the tool's executables must be on your PATH. Then, to start the shell in design planning mode:

% icc2_shell -dp_mode

Startup is a fixed sequence of four steps, and it is worth knowing because everything that surprises you later was decided in it. The tool creates a command log file; reads and executes the setup files; executes any script files or commands given with the launch options; and then displays the program header and the icc2_shell> prompt.

The launch options you will actually use are few:

% icc2_shell -help       # or -h, depending on your release

Leaving is simpler than starting. exit or quit ends the session at any time, and in an interactive session Ctrl+D does the same. There is one thing to be very clear about:

2.2.3 Typing commands, and stopping them

You interact with the tool by entering commands, which are Tcl-based with extensions for the tool's own functionality. The command language provides what a UNIX shell provides — variables, conditional execution, control flow — because it is a real programming language.

Four practical details save a surprising amount of time:

• Tab completion. Type enough characters of a command, option or file name to be unique and press Tab; the tool completes the rest. If what you typed matches more than one name, the tool lists the candidates and you choose with the arrow keys and Enter.
• Reusing output. To reuse a command from output, select the text, move the pointer to the command line and click the middle mouse button.
• Page mode. By default the tool does not page its output, so a long report scrolls past. To page it, set the sh_enable_page_mode variable to true.
• Interrupting. Ctrl+C interrupts or terminates the command currently running and leaves you in the shell. How long that takes depends on the design size and the command. Some commands and processes cannot be interrupted at all; ending those means terminating the shell at the system level, and nothing is saved when you do.

Two consequences of Ctrl+C are worth memorising because they surprise people at the worst moment. If a script is running and you interrupt one of its commands, script processing is interrupted and no further commands in that script are processed. And if you press Ctrl+C three times before the command responds to the interrupt, the shell itself is interrupted and exits with the message Information: Process terminated by interrupt.

2.2.4 Asking the tool instead of guessing

This is the single most valuable habit in the chapter, so it comes before the material it makes unnecessary. Any question of the form “what does this do?” or “what options does it take?” has an answer inside your installation, and that answer is authoritative in a way that no book — including this one — can be.

# One line about a command.
icc2_shell> help report_timing

# The options this release supports, from the command itself.
icc2_shell> report_timing -help

# The full reference page.
icc2_shell> man report_timing

# Which commands even exist, matching a pattern.
icc2_shell> help "report_*"

# The value of a variable, or of every variable.
icc2_shell> printvar search_path
icc2_shell> printvar *

The man command does three things beyond command pages that beginners rarely discover. It displays the page for an application variable. It displays the page for an error message — man CMD-025 is a legitimate command and often the fastest route out of a confusing failure. And it summarises application options three ways: by category, by subcategory, and by the command they affect.

# Every application option in the plan category.
icc2_shell> man plan_options

# The same, narrowed to one subcategory.
icc2_shell> man plan.place_options

# Every application option that affects one command.
icc2_shell> man report_timing

One note on where the answer appears: entering man on the shell command line displays the page in the shell, and in the console log view if the graphical interface is open. Entering it on the console command line in the graphical interface displays it in that interface's own man page viewer.

2.2.5 Application options — and the handful of variables

The tool controls its behaviour with application options rather than with variables. It does support user-defined Tcl variables and a minimal number of application variables — search_path being the one you will use constantly — and printvar lists what is available.

Application options are named in a fixed pattern:

category[.subcategory].option_name

The category is the name of the engine the option affects; some categories have subcategories that narrow the area further. So the name itself tells you which part of the tool you are about to change, which is a small kindness worth appreciating.

Scope is the part that causes arguments. Every application option has either global scope or block scope:

• Global-scoped options apply to all blocks, but only within the current session. They are not saved in the design library, so you must specify them in every session — which is exactly what a setup file is for.
• Block-scoped options apply only to the block they were set on. They are saved in the design library and persist across tool sessions.

There is one exception that catches everyone once. Setting a block-scoped option with -as_user_default makes it a user default for the session: it then behaves like a global option and is not persistent across sessions. That option is also mutually exclusive with -block, and it is simply ignored if you give it for a global-scoped option.

# Which options exist? Filter by pattern.
icc2_shell> get_app_options "plan.*"

# What do they mean? Names and help strings, by category.
icc2_shell> help_app_options -category link

# Set one, and read the confirmation the command returns.
icc2_shell> set_app_options -name time.enable_preset_clear_arcs -value true
time.enable_preset_clear_arcs true

# Set several at once — the list must have an even number of tokens.
icc2_shell> set_app_options \
   -list {shell.tmp_dir_path "/tmp" time.enable_preset_clear_arcs true}

# What is it right now, and what have I changed from the defaults?
icc2_shell> get_app_option_value -name time.enable_preset_clear_arcs
icc2_shell> report_app_options -non_default

# Put it back.
icc2_shell> reset_app_options time.enable_preset_clear_arcs

Two details from that block are worth calling out. If any name–value pair in a -list is invalid, the command fails with no effect — so a typo changes nothing rather than changing half of what you meant, which is the behaviour you want. And report_app_options is also how you find out whether a given option is global or block-scoped, which is the question behind most “but I set that yesterday” conversations.

2.2.6 Units, part one: the numbers you type and read

The tool keeps two sets of user units: one for input, meaning what a number you type or a file supplies is taken to mean, and one for output, meaning what a number in a report or an attribute value is expressed in. They are separate, and they can differ.

# What am I working in? Run this before you trust any number.
icc2_shell> report_user_units

Input Units (set to default)
----------------------------------------------
time                         : 1.00ns
resistance                   : 1.00kOhm
capacitance                  : 1.00pF
voltage                      : 1.00V
current                      : 1.00mA
power                        : 1.00mW

Output Units (set to default)
----------------------------------------------
... the same six quantities ...

Those six values are the defaults. To change one, name the type and the value:

# Both input and output, together.
icc2_shell> set_user_units -type time -value 10ps

# Input only — useful when a constraint file is written in picoseconds
# and you would rather read reports in nanoseconds.
icc2_shell> set_user_units -input -type time -value 1ps

# And to query one quantity programmatically:
icc2_shell> get_user_units -output -type time

Give neither -input nor -output and both sets change together. The types you can set are capacitance, current, length, power, resistance, time and voltage.

Here is why this section exists. Nimbus-8's fastest clock is 1.60 GHz, so its period is 625 ps. That single physical fact is written three different ways depending on the time unit in effect:

Notice that no line of that table involves a mistake by the tool. Every reading is correct. The error is always the same error: a number moved between two people, or between two files, without its unit.

That last rule deserves its own paragraph, because it is a second, independent unit system living inside the first. Many application options take a value that must be expressed in units of time, voltage and so on. For those, the unit goes into the value: a multiplier character such as p, n or k, or a unit specifier such as F, V or s. The case of the unit character matters — uppercase V for volts, lowercase s for seconds — and if the character does not specify the right type of unit, the command fails with no effect. Most importantly: these values do not use the user units currently in effect. What you write in the value is what you get.

2.2.7 Units, part two: length, and what the database can actually store

Length is missing from the six defaults for a reason: it is not primarily a reporting convention but a property of the library. Design data is stored in internal units, and a library's scale factor is the number of database units per micron. It sets the smallest distance that can be represented at all, and the tool converts what you type into those internal units.

The conversion is a multiply and a round. When the tool saves a floating-point number it multiplies by the scale factor and rounds to an integer; when it retrieves the number it divides by the scale factor. Follow one value through:

# Scale factor 1 000 — one database unit per nanometre.
you ask for   0.0032 um
stored as     0.0032 x 1000 = 3.2   ->  rounds to 3
read back as  3 / 1000              =   0.003 um
you lost      0.0002 um = 0.2 nm, silently

# Scale factor 10 000 — one database unit per angstrom.
you ask for   0.0032 um
stored as     0.0032 x 10000        =   32
read back as  32 / 10000            =   0.0032 um   # exact

If the scale factor is not large enough, the precision of the coordinates you specify is affected. A shape whose boundary is given as {{0.500 0.500} {0.5053 0.5053}} is stored as {500 500} {505 505} at a scale factor of 1 000, and as {5000 5000} {5053 5053} at 10 000. The design is legal either way. It is simply not the design you drew.

Four rules follow, and they are the whole of what a planning engineer needs:

1. The default for a new library is 10 000, which allows distances down to 1 Å to be represented.
2. Scale factors must be compatible. A design library's scale factor must be compatible with the session's, and it must be a multiple of the length precision of the technology file associated with the library.
3. Mixed reference libraries take their lowest common multiple. Create a library with reference libraries that all share a scale factor and the new library gets it; give it reference libraries with different scale factors — 2 000 and 4 000, say — and the new library gets 4 000.
4. The recommended setting is the technology length precision. To use it, set lib.setting.use_tech_scale_factor to true before creating the library.

# Ask, rather than assume.
icc2_shell> get_attribute [get_lib my_libA] scale_factor

# And prefer the technology's own precision when creating a library.
icc2_shell> set_app_options -name lib.setting.use_tech_scale_factor -value true
icc2_shell> create_lib nimbus8.dlib -technology nimbus8.tf -ref_libs {stdcell.ndm sram.ndm}

For the teaching design, the arithmetic is reassuringly boring — which is what a sane setup looks like. At a scale factor of 10 000, every dimension in Chapter 1 is a whole number of database units: the 3.44 mm die edge is 34 400 000 units, the 3.20 mm core edge is 32 000 000, the 0.576 µm row height is 5 760, and the 0.048 µm track pitch is 480. Nothing rounds, so nothing drifts.

2.2.8 Scripts, and what happens when one fails

A script is a text file containing a sequence of commands, and any command you can type can go in one. A # at the start of a line is a comment. There are three ways to run one: with the launch option when you start the tool, with source from the prompt, or from the graphical interface's script menu.

# Quietly, the default.
icc2_shell> source scripts/10_plan.tcl

# Echoing each command as it runs — the option to use while developing.
icc2_shell> source -echo scripts/10_plan.tcl

# Echoing the result of each command as well.
icc2_shell> source -echo -verbose scripts/10_plan.tcl

Now the important part. If an error occurs while a command in a script is running, the tool raises the TCL_ERROR condition, which immediately stops script execution. Nothing after the failing line runs. That is the correct default, and you should think twice before defeating it — but there are two legitimate ways to do so:

• Catch the specific command with the Tcl catch command, so that one command is allowed to fail and you decide what happens next.
• Tolerate errors for a whole script, either by setting the sh_continue_on_error variable to true in the script file, or by running that one script with source -continue_on_error.

Generating a script from a spreadsheet

One script-generation feature belongs to this chapter because it is a scripting facility rather than a planning step: a power–ground script can be generated from data held in a spreadsheet, provided the spreadsheet is a CSV file in the expected format. The commands written into the generated script are limited to the pattern and strategy commands used in power planning — composite patterns, special patterns, wire patterns, and the strategy and via-rule commands — and no other power–ground commands are supported.

# Generate a Tcl script from spreadsheet data.
icc2_shell> generate_pg_script -input special_pattern_spreadsheet.csv \
   -output test.tcl

2.2.9 Setup files: the session before the session

When the tool starts, it automatically executes the commands in the .synopsys_icc2.setup file. It looks in two places, in this order: your home directory, then the project directory — meaning the current working directory from which you started the tool.

The order is the whole design of the feature. Personal preferences go in the home-directory file, where they follow you between projects. Project- or block-specific settings that affect how a block is processed go in the project-directory file, where they follow the project — and, being read second, they take precedence over your personal ones.

# ./.synopsys_icc2.setup — the project's file, in version control.

# Where libraries are found, in search order.
set_app_var search_path {. ./libs ./ref_libs}

# Project-wide behaviour: global-scoped options are session-only,
# which is exactly why they belong here.
set_app_options -name lib.setting.use_tech_scale_factor -value true

# A farm configuration everyone on the project should share.
set_host_options -name farm -submit_command "/lsf/bin/bsub -q linux64" \
   -num_processes 12

2.2.10 The command log, and why it is not a log file

The command log records the commands the tool processed, including the commands from setup files and application option settings. By default it is written to icc2_command.log in the directory you invoked the shell from. You can change the name by setting the sh_command_log_file variable in your setup file — and that change has to be made before the tool starts, because the file is created during startup. If no setup file sets it, the default name is used.

What makes the command log valuable is that it is not prose: it is a sequence of commands, so it can be read as a script. Three uses follow directly. It can be turned into a script that reproduces a particular implementation strategy. It is a record of what was actually done to the design, as opposed to what the run script said. And it is the file to attach when you ask somebody for help, because it answers the first question they will ask.

2.2.11 Using more than one core

Several functions support multicore processing, through multithreading, distributed processing or parallel command execution. In most cases you configure it with one command, set_host_options, and the three modes are genuinely different things.

Multithreading — one machine

Multithreading performs tasks in parallel using multiple cores on the same machine, within a single process memory image; each parallel task is a thread. The total number of cores on a machine is the number of CPUs multiplied by the number of cores per CPU, and for best performance you limit the threads to the cores you actually have. So on a machine with two CPUs of three cores each:

icc2_shell> set_host_options -max_cores 6

By default every command uses a single thread. The number given by -max_cores applies to all commands that support multithreading, and the value is a maximum: a command may use fewer, never more. But note the sharp edge — when you enable multithreading, multithreaded commands create and use the number of threads you specified even if that is more than the number of available cores. Overthreading reduces performance, because the extra threads compete for the same resources.

Distributed processing — many machines

Distributed processing performs tasks in parallel using multiple machines, each process with its own memory image; each parallel task is a process. You can specify the job submission command, a list of host machines, and the maximum number of processes. Without a submission command, remote jobs are launched with rsh.

# A queueing system, named so it can be selected and removed later.
icc2_shell> set_host_options -name farm \
   -submit_command "/lsf/bin/bsub -q linux64" -num_processes 12

# Or a plain list of machines, with a per-host limit.
icc2_shell> set_host_options -name rshOpt -submit_command "rsh" \
   -num_processes 8 {sleepy:5 doc:4}

# What is configured, and how to take it away again.
icc2_shell> report_host_options
icc2_shell> remove_host_options -name farm

Three numbers govern this and they are easy to mix up. -num_processes is the level of parallelism for job submission: for a queue it is the maximum total number of jobs that can be submitted; for a collection of named hosts it is the maximum number of jobs per host. Its default is 1. -max_cores, when it is part of a host specification, controls how many cores each distributed job may use. And the licence rule sits on top of both: you need one tool licence for every eight parallel tasks, so sixteen parallel tasks need two licences.

Running the same task on many blocks

To run the same task on several blocks — the characteristic planning pattern — run_block_script takes a Tcl script and applies it to the blocks you name, using distributed processing:

icc2_shell> run_block_script -script scripts/per_block.tcl \
   -blocks {u_cpu_cluster u_npu_core u_isp u_soc_periph} \
   -run_order bottom_up -host_options farm

The run order matters in a multi-level hierarchy, because jobs for two blocks with an ancestor–descendant relation cannot run in parallel. With bottom_up — the default — a block does not start until its children have finished. With top_down, a block does not start until the blocks it is instantiated in have finished.

Local parallel work — no extra licences

For checking and reporting commands there is a third way that needs neither distributed configuration nor extra licences: run them on your own machine, either in the background or in parallel.

# In the background: the prompt comes back immediately.
icc2_shell> set_host_options -max_cores 8
icc2_shell> redirect -bg -max_cores 3 -file logs/bg_report.log \
   {source scripts/reports.tcl}
Information: redirect -bg with max_cores 3 started. The maximum number of
 cores available in parent is reduced to 5. (BGE-004)

# What is running, and what has finished.
icc2_shell> report_background_jobs

# Which commands may be run this way at all.
icc2_shell> list_commands -bg

# Or in the foreground, waiting for the slowest one.
icc2_shell> update_timing
icc2_shell> parallel_execute {
   report_cmd1 log_file1
   report_cmd2 log_file2
}

Read the message in that block carefully, because it is the arithmetic of the whole feature: the cores given to a background job are taken from the parent. Eight cores, three to the background job, five left for the work you are still doing. At most two jobs run in the background; ask for more and they queue. And one piece of practical advice that saves both runtime and memory: run update_timing before launching a set of reporting commands in parallel, or each command that needs updated timing will run it independently.

2.2.12 Watching distributed work while it runs

A Distributed Processing Manager exists to let you monitor distributed tasks as they run. It communicates with distributed commands to provide up-to-date status, and when a task completes the display updates to show it finished. The workers periodically send updates showing the currently running command and their memory and processor use — though not every command reports this way.

# Start the monitor first. It returns the process id of the task it created.
icc2_shell> run_monitor_gui
10948

# Then start the distributed work; jobs appear as they are submitted.
icc2_shell> create_abstract -placement \
   -host_options block_script -all_blocks
Submitting job for block u_cpu_cluster ...
Submitting job for block u_npu_core ...
...

# Two windows is the maximum. To close them all and open nothing new:
icc2_shell> run_monitor_gui -kill -nolaunch

When every task is finished the manager shows COMPLETED for all job and task identifiers and moves the job history from not done to done. You may have at most two manager windows open at once; running the command a second time opens the second one, and -kill terminates existing instances before launching. If any manager tasks are still running when your session ends, they are terminated with it.

Six planning commands are followed by the manager when they run in distributed mode: abstract creation for all or named blocks, floorplan placement creation, timing estimation, abstract merging, virtual-flat floorplan global routing, and block shaping. Those are exactly the long-running steps of the flow in Chapter 1 — which is the point.

2.3 Inputs, outputs and readiness

What has to be true before a session is worth starting

Preflight checklist

What the session leaves behind

Four artefacts, and it is worth being precise about which of them survive. The command log is a replayable record of the commands the session processed — and is overwritten by the next session in that directory. A session log, if you asked for one at launch, holds the transcript including messages. The design library holds anything you saved, including block-scoped application options. And the scripts and setup files hold the only part of the session that is genuinely durable: the intent.

When a session's results are not trustworthy

2.4 The guided workflow

2.4.1 A session, from launch to exit

1. Check the release and the environment. Confirm the bin directory is on your PATH, and record the version.
2. Start in design planning mode. icc2_shell -dp_mode, from the project directory so that the project setup file is the one that runs.
3. Verify what the setup files did. printvar search_path, report_app_options -non_default, report_host_options. Three commands, five seconds, and no surprises later.
4. Verify the units. report_user_units, and set them explicitly if this project's convention differs from the defaults.
5. Open the library and the block you intend to work on, so that block-scoped settings land where you mean them to.
6. Run the work as a script, with source. Use -echo while you are developing it and drop it once it is stable.
7. Configure hosts before a long step, not after: set_host_options, then check with report_host_options.
8. Start the monitor before the distributed step, not while wondering whether anything is happening.
9. Save deliberately. Nothing is saved on exit.
10. Copy the command log to a dated file, then leave with exit.

2.4.2 Command reference for this chapter

Eight commands do the work of this chapter. Each is presented the same way as in Chapter 1: purpose, syntax in plain English, prerequisites, a small realistic example, what to expect, how to verify, what goes wrong, and how to find the rest.

icc2_shell — start a session that configures itself

Purpose. Runs the tool. The shell interprets and executes commands and is based on Tcl; it executes commands until terminated by quit or exit.

Syntax in plain English. -dp_mode starts in design planning mode, where a limited functionality set is available for planning only. -file runs a script before the first prompt; -x runs commands before the first prompt, and before the -file script if both are given. -gui opens the graphical interface at startup; -batch exits after the -file and -x work is done and sets the graphical batch display to offscreen, so no display is needed. -version prints the version and build date and exits. -no_init prevents any setup file from running; -no_local_init skips the local ones only. -no_motd suppresses the message of the day. -python switches the language to Python, in which case -x expects a Python statement.

Prerequisites. The tool's bin directory on your PATH; a project directory to start from, if you want the project setup file to apply.

# Interactive planning session, from the project directory.
% icc2_shell -dp_mode

# A batch run: two commands, then a script, then exit.
% icc2_shell -dp_mode -batch \
   -x "printvar search_path; report_user_units" \
   -file scripts/10_plan.tcl

# Replay a command log without letting setup files interfere.
% icc2_shell -dp_mode -no_init -file icc2_command_20260907.log

Expected result. The four startup steps run in order — command log created, setup files executed, -x then -file processed — and then either a prompt appears or, in a batch run, the shell exits.

Verification step. First three commands of every interactive session: printvar search_path, report_app_options -non_default, report_user_units. If any of the three surprises you, a setup file did something you did not know about, and you have found it before it cost anything.

Common mistakes. Starting from the wrong directory, so the project setup file never runs. Assuming -file runs before -x — it does not. Forgetting that a script whose last command is quit gives you no prompt, then wondering why the session ended. Using -no_init routinely rather than only for replaying a log, and then being puzzled that the project's settings are absent.

Finding the rest. The invocation help — icc2_shell -help, or -h on some releases — lists the options without starting the tool.

source — run a script, and see what it is doing

Purpose. Reads a file and evaluates it as a Tcl script. The result of source is the result of the last command executed from the file.

Syntax in plain English. -echo echoes each command as it is executed. -verbose displays the result of each command; error messages are displayed either way. -continue_on_error does not stop the script on errors — the same effect as setting the sh_continue_on_error variable to true, but limited to this one script. The file argument is the script to read.

Prerequisites. A readable script file, and a session in the state the script expects — a script that assumes a block is open will fail on its first command if it is not.

# Quiet, the default, for a script you trust.
icc2_shell> source scripts/10_plan.tcl

# While developing: show each command, and each result.
icc2_shell> source -echo -verbose scripts/10_plan.tcl

# A report script, where continuing past a failure is acceptable.
icc2_shell> source -continue_on_error scripts/90_reports.tcl

Expected result. The commands run in order. On an error, the tool raises the TCL_ERROR condition and script execution stops immediately — unless you asked otherwise.

Verification step. Do not verify a script by watching it. Verify it by what it leaves behind: the reports it wrote, the checks it ran, and the last line of its log. A script that “looked fine” is not evidence.

Common mistakes. Using -continue_on_error on a script that changes the design. Interrupting one command in a script with Ctrl+C and expecting the rest to run — script processing stops. Leaving -echo on in production runs, which buries the messages that matter in the commands that do not.

Finding the rest. man source, and man sh_continue_on_error for the variable.

set_app_options — change how the tool behaves

Purpose. Sets application options to the specified value on the specified block. Application options are the normal way tool behaviour is controlled.

Syntax in plain English. -name and -value set one option and go together; -list sets several as name–value pairs and is mutually exclusive with them. -block names the block to set a block-scoped option on; without it, the current block is used. -category lets you give one or two levels of category once instead of repeating it in every name. -as_user_default sets the value as the session's user default — it applies to the current session only, is not saved, is ignored for global-scoped options, and cannot be combined with -block.

Prerequisites. For a block-scoped option, the block you intend to change must be open and either current or named with -block.

# One option; the command echoes back the name and value it set.
icc2_shell> set_app_options -name lib.setting.use_tech_scale_factor -value true
lib.setting.use_tech_scale_factor true

# Several at once. An invalid pair makes the whole command fail with no effect.
icc2_shell> set_app_options -list {shell.tmp_dir_path "/tmp" \
   time.enable_preset_clear_arcs true}

# On a named block rather than the current one.
icc2_shell> set_app_options -block [get_blocks u_isp] \
   -name time.enable_preset_clear_arcs -value true

Expected result. The command returns the name–value pair it set. Global settings apply everywhere in this session; block-level settings are saved with the block in the design library and persist across sessions — except when set with -as_user_default, in which case they behave like global options and do not persist.

Verification step. get_app_option_value -name option for one option; report_app_options -non_default for everything you have changed. Use the second one at the end of a setup file, so the log records the answer.

Common mistakes. Setting a block-scoped option with no block open or the wrong block current. Expecting a global option to be there tomorrow. Combining -as_user_default with -block. Writing a value that needs a unit without its unit character — and note that these values do not use the user units in effect, so the unit must be in the value.

Finding the rest. get_app_options pattern for names, help_app_options -category category for meanings, man category_options for a category summary, reset_app_options to undo.

printvar and set_app_var — the few variables that matter

Purpose. printvar prints the values of one or more variables; set_app_var sets an application variable. The tool modifies default behaviour through application options rather than variables, and supports only a minimal number of application variables — but the ones it does support are load-bearing.

Syntax in plain English. printvar takes an optional pattern, with * and ? as wildcards, and prints everything if no pattern is given; -user_defined and -application restrict the listing to one kind or the other and are mutually exclusive. set_app_var takes the variable name and its value.

Prerequisites. None beyond a session. Variables that affect startup — the command log file name among them — must be set in a setup file, because by the time you have a prompt it is too late.

# The variable you will use most: where libraries are found, in order.
icc2_shell> set_app_var search_path {. ./libs ./ref_libs}
. ./libs ./ref_libs

# Check it, and see what else exists.
icc2_shell> printvar search_path
icc2_shell> printvar -application

# Page long output instead of watching it scroll away.
icc2_shell> set_app_var sh_enable_page_mode true

Expected result. The variable's new value, echoed. printvar lists names and values.

Verification step. For search_path, the real verification is not the value but the resolution: open the library you expect and confirm you got the copy you expected rather than an older one with the same name.

Common mistakes. Setting sh_command_log_file after startup and expecting the log to move. Reordering search_path and forgetting that already-bound reference libraries stay bound until you rebind them. Using a variable where an application option exists — the option is the supported route.

Finding the rest. man variable_name works for variables, and get_app_var -details variable gives type, default and constraints.

set_user_units — decide what your numbers mean

Purpose. Sets the units used for user input and output. The tool maintains separate units for input and for output.

Syntax in plain English. -type names the quantity — capacitance, current, length, power, resistance, time or voltage. -value gives the unit, written as a number and a unit string: 1ps, 1.0ps, 10ps, 1kOhm. -input changes only what typed and read-in numbers mean; -output changes only what reported numbers mean; giving neither changes both.

Prerequisites. None — but doing it before reading constraints is the entire point, because a constraint file's own unit statement will not change your input units.

# The habit: print first, so the log records what the numbers meant.
icc2_shell> report_user_units

# This project quotes timing in picoseconds. Say so, explicitly.
icc2_shell> set_user_units -type time -value 1ps

# Or: read a picosecond constraint file, but report in nanoseconds.
icc2_shell> set_user_units -input  -type time -value 1ps
icc2_shell> set_user_units -output -type time -value 1ns

# Query one quantity from a script.
icc2_shell> get_user_units -output -type time

Expected result. The unit string is returned, and every subsequent number you type or read in that quantity is interpreted accordingly.

Verification step. report_user_units again, and then a sanity check on a number you already know: on Nimbus-8, clk_cpu has a 625 ps period, so it should read 625 with a 1 ps unit and 0.625 with a 1 ns unit. If it does not, stop and find out why before doing anything else.

Common mistakes. Using set_units, which has no effect. Changing units halfway through a session, so that the first half of the log means something different from the second. Assuming application-option values follow these units — they do not. Assuming length is covered here: the settable types include it, but the finest length the database can hold is fixed by the library scale factor, and the query command's documented quantity list covers the six electrical and time quantities, so confirm the behaviour you need for your release with man get_user_units.

Finding the rest. man set_user_units, man report_user_units, man get_user_units.

set_host_options — decide how much machine to use

Purpose. Specifies settings for multithreaded and distributed processing. In its simplest form it controls the number of cores a multicore command may use; at the other extreme it describes a queueing system and a fallback strategy.

Syntax in plain English. -max_cores on its own controls the maximum cores multicore commands may use in the current job; inside a host or pool specification it controls the cores each distributed job may use. -num_processes controls job-submission parallelism — for a pool it is the maximum total number of jobs, for named hosts it is the maximum per host — and defaults to 1. -submit_command gives the full path of the submission program with its options; without it, rsh is used. -submit_protocol chooses the submission protocol; values are lowercased. -timeout is a job-submission timeout in seconds: jobs that have not started within it are killed, which prevents jobs hanging in a queue — and it applies only to rsh and ssh, not to queueing systems. -work_dir is where distributed jobs keep their run files, defaulting to ./work_dir. -name names the set of options so that it can be selected by a command's -host_options and removed later; -target stores the configuration for a particular tool. -allocated_mem and -alternate_options together provide a fallback to higher-memory queues. The trailing argument is a list of host names, optionally with a per-host limit.

Prerequisites. Knowing how many cores your machine really has, and what your queue and licences allow.

# Multithreading on this machine: 2 CPUs x 3 cores = 6.
icc2_shell> set_host_options -max_cores 6

# A named farm configuration — 12 jobs maximum, one named queue.
icc2_shell> set_host_options -name farm \
   -submit_command "/lsf/bin/bsub -q linux64" -num_processes 12

# Named hosts instead of a queue, with a per-host cap.
icc2_shell> set_host_options -name rshOpt -submit_command "rsh" \
   -num_processes 8 {sleepy:5 doc:4}

# What is configured now, and how to remove one set.
icc2_shell> report_host_options
icc2_shell> remove_host_options -name rshOpt

Expected result. A named or global configuration that distributed and multicore commands will use. Nothing runs faster yet; you have only described what is allowed.

Verification step. report_host_options, then a short distributed step with the monitor open. Confirm that the number of workers you see matches the number you asked for — and that it matches the licences you have, at one licence per eight parallel tasks.

Common mistakes. Setting -max_cores higher than the machine has cores: the threads are still created and compete. Expecting -timeout to protect a queue submission — it applies only to rsh and ssh. Setting -allocated_mem and expecting the tool to size jobs from it: the values are used only for relative comparison with -alternate_options, no memory estimation is done, and on its own the option has no effect. Confusing per-pool and per-host meanings of -num_processes. Typing the configuration by hand each day instead of putting it in the project setup file.

Finding the rest. man set_host_options — its examples run from a single-machine case to a multi-queue fallback and are worth reading once in full.

run_block_script — the same work on every block

Purpose. Runs a specified Tcl script on a set of blocks, using distributed processing, so that the same task is performed on several blocks in parallel.

Syntax in plain English. -script names the script to run for each block; -read_only_scripts names scripts to run in read-only mode instead and is mutually exclusive with it. -blocks names the blocks; -cells gives cells instead, and only one instance of a multiply instantiated block is executed. -run_order is bottom_up (the default) or top_down; jobs for two blocks in an ancestor–descendant relation cannot run in parallel, so one of the two orders must apply. -host_options selects a named host configuration. -var_list passes variable–value pairs into the jobs; -work_dir chooses where run files go; -name names the job; -reuse_processes and -force control process reuse and forcing.

Prerequisites. A host configuration; a script that is safe to run on any of the named blocks; and blocks that are actually independent, unless you have set the run order deliberately.

# One report script, four blocks, bottom-up, on the named farm.
icc2_shell> run_block_script -script scripts/per_block_check.tcl \
   -blocks {u_cpu_cluster u_npu_core u_isp u_soc_periph} \
   -run_order bottom_up -host_options farm -name ch02_checks

Expected result. One job per block, submitted according to the host configuration and the run order, each running the same script.

Verification step. Open the monitor before you start, then check each block's own log afterwards. A job that finished is not a job that succeeded.

Common mistakes. A per-block script that assumes a particular block is current. Ignoring run order in a multi-level hierarchy. Submitting more parallel jobs than your licences cover. Running a script that writes to one shared output file from every job at once.

Finding the rest. man run_block_script; and report_host_options to confirm which configuration the -host_options name refers to.

run_monitor_gui — watch the farm

Purpose. Starts the Distributed Processing Monitor, which watches the progress of distributed tasks. It returns the process identifier of the task it created.

Syntax in plain English. -kill terminates any existing monitor instances before launching. -nolaunch prevents a new window from being started; used together with -kill it closes all running instances without opening a new one.

Prerequisites. Distributed processing actually configured with set_host_options — otherwise there is nothing to watch — and a display for the window.

# Start the monitor, note the returned process id.
icc2_shell> run_monitor_gui
10948

# Then start distributed work. Here block_script is the NAME of a host
# option set defined earlier with set_host_options -name block_script.
icc2_shell> create_abstract -placement \
   -host_options block_script -all_blocks

# Close everything and open nothing new.
icc2_shell> run_monitor_gui -kill -nolaunch

Expected result. A window listing jobs with their command, status and resource use, updating as workers report. At most two instances may run at once, and the shell enforces that limit.

Verification step. Every job reaches COMPLETED and the job history moves from not done to done. If nothing appears at all, the likely causes are, in order: no host configuration; the command is not one that reports progress this way; or an instance from another session has connected instead of yours.

Common mistakes. Starting the monitor after the work. Expecting every distributed command to report progress — not all do. Opening more than two windows. Treating the monitor as a record: when the session ends, any monitor tasks still running are terminated with it, and nothing is written down.

Finding the rest. man run_monitor_gui.

2.5 Worked example: making the Nimbus-8 session reproducible

The situation

You are back on Nimbus-8, the design from Chapter 1. The partition is agreed and the die is 3.44 mm square. Three engineers are now working on it, and something is wrong with the way they work rather than with the design: two of them get slightly different reports from what should be the same run, one of them cannot run the distributed steps at all, and nobody can say what produced last Thursday's budget numbers.

Nothing in this section changes the design. Everything in it changes whether the design work can be trusted — which is why it is worth an afternoon.

Step 1 — Audit the session you actually have

Start the shell from the project directory, and ask three questions before doing anything else.

% icc2_shell -dp_mode

icc2_shell> printvar search_path
search_path   ". /home/asha/libs ./ref_libs"

icc2_shell> report_app_options -non_default
... one option changed, set by somebody's home setup file ...

icc2_shell> report_user_units
Input Units (set to default)
time                         : 1.00ns
... and the project's constraint files are written in picoseconds ...

icc2_shell> report_host_options
... nothing configured: every command will use one core ...

Four findings in about twenty seconds, and every one of them is a defect:

• The search path contains one engineer's home directory. Her runs find a library that nobody else can see. This is the “works on my machine” bug, in its purest form.
• An application option is set from a home setup file, so it applies to her sessions and to nobody else's — and it is not written down anywhere in the project.
• The input time unit is 1 ns while the constraints are quoted in picoseconds. Nothing has failed yet. Every number typed at the prompt so far has meant a thousand times what its author intended.
• No host options at all, so the long steps have been running on a single core on a machine with more than thirty.

Step 2 — Move the project's facts into the project's setup file

The rule from §2.2.9 decides where each line goes: facts about the project belong in the project's setup file, in version control, where a colleague inherits them without being told.

#=============================================================
# ./.synopsys_icc2.setup   —   Nimbus-8, in version control
#=============================================================

# 1. Where libraries are found, in search order. Project-relative
#    only: no home directories, ever.
set_app_var search_path {. ./libs ./ref_libs}

# 2. Keep the command log out of the way of the next session.
#    This variable must be set before startup, which is why it
#    lives here and not at the prompt.
set_app_var sh_command_log_file "logs/icc2_command.log"

# 3. Library precision: take the technology file's own length
#    precision rather than a number somebody liked.
set_app_options -name lib.setting.use_tech_scale_factor -value true

# 4. The farm, described once for everyone. Sizing is in Step 4.
set_host_options -name farm \
   -submit_command "/lsf/bin/bsub -q linux64" \
   -num_processes 12 -max_cores 4 -work_dir ./work_dir

# 5. Say what we changed, so the log records it.
report_app_options -non_default

Step 3 — Make the units explicit, and check them against something known

The project quotes timing in picoseconds, so say so — and then verify it against a number you already know rather than trusting that it worked.

#=============================================================
# ./scripts/00_units.tcl
#=============================================================

# What are we starting from? Recorded in the log, always.
report_user_units

# Nimbus-8 convention: picoseconds in, picoseconds out.
set_user_units -type time -value 1ps

# And prove it: clk_cpu is 1.60 GHz, so its period must read 625.
report_user_units

The check is the point. clk_cpu runs at 1.60 GHz, so its period is 625 ps — one divided by 1.60 GHz. With a 1 ps unit in effect it must read 625; with the default 1 ns unit it would read 0.625. If a report shows either number and you cannot say which unit produced it, you do not yet know what the design is doing.

Two independent checks on that table, both of which you should be able to do without a calculator. The three budgets sum to the usable period: 190 + 150 + 210 = 550 ps. And the usable period is the full period minus the uncertainty and the setup requirement: 625 − 45 − 30 = 550 ps. If either identity fails after a unit change, the unit change is where to look.

Step 4 — Size the farm, in cores and in licences

The project has four compute machines, each with two CPUs of eight cores. Before configuring anything, do the arithmetic; the configuration is then a transcription rather than a guess.

# Cores available
per machine   = 2 CPUs x 8 cores per CPU        =  16 cores
farm total    = 4 machines x 16 cores           =  64 cores

# A distributed step over the five planning blocks: choose the
# parallelism first, then check it fits.
processes     = 12                              (-num_processes 12)
cores per job = 4                               (-max_cores 4)
demand        = 12 x 4                          =  48 cores  <= 64  OK

# Licences: one tool licence covers eight parallel tasks.
licences      = 12 tasks / 8 tasks per licence  =  1.5  ->  2 licences

# And for the local machine, when running multithreaded steps there:
local machine = 2 CPUs x 6 cores per CPU        =  12 cores  (-max_cores 12)

Now transcribe it — and read back what the tool thinks you said:

icc2_shell> set_host_options -name farm \
   -submit_command "/lsf/bin/bsub -q linux64" \
   -num_processes 12 -max_cores 4 -work_dir ./work_dir

icc2_shell> report_host_options

Step 5 — Run one step distributed, with the monitor open first

# Monitor first. It returns the process id of the monitor task.
icc2_shell> run_monitor_gui
10948

# The same check script on four blocks, bottom-up, on the named farm.
icc2_shell> run_block_script -script scripts/per_block_check.tcl \
   -blocks {u_cpu_cluster u_npu_core u_isp u_soc_periph} \
   -run_order bottom_up -host_options farm -name ch02_block_checks

# When it is done, close the monitor and open nothing new.
icc2_shell> run_monitor_gui -kill -nolaunch

The bottom-up order is not decoration. u_cpu_cluster is a parent of two committed children, and jobs for two blocks in an ancestor–descendant relation cannot run in parallel — so one of the two orders has to apply, and bottom-up is the default because children usually have to be finished before their parent is worth processing.

Step 6 — Keep the evidence

# The last lines of every run script.
report_app_options -non_default
report_user_units
report_host_options

# Then, outside the tool, keep the log instead of losing it:
% cp logs/icc2_command.log logs/icc2_command_$(date +%Y%m%d_%H%M).log

That copy is the entire difference between “we ran the flow on Thursday” and “here is exactly what ran on Thursday”. It costs one line.

Step 7 — What a senior engineer looks at next

1. Is anything still coming from a home directory? Grep the setup files for /home. One absolute path is enough to make a project unreproducible.
2. Does the log show the unit report near the top? If not, no number in that log can be quoted with confidence.
3. Are the block-scoped options where you think? report_app_options -non_default on each block, not just on the one that happens to be current.
4. Does the core demand fit the farm? 48 of 64 cores leaves headroom for somebody else's job; 64 of 64 means you are the reason their run is slow.
5. Do the licences cover the parallelism? Twelve tasks need two licences; if the project owns one, the honest configuration is eight tasks.
6. Is the scale factor right, and recorded? It can only be chosen at library creation. Check it once, write it in the project notes, and never wonder again.
7. Could a new joiner reproduce Thursday? Give them the project directory and nothing else. If they cannot, the gap you find is the next thing to fix.

2.6 Failure modes and debugging

Each entry follows the same five-part shape: symptom, likely cause, diagnostic check, correction, prevention.

The misleading one, in detail

Here is the failure that looks like a floorplan bug and is not. A colleague reports that shapes in a block are “slightly off”: a boundary given as 0.5053 µm comes back as 0.505 µm, a keepout appears 0.2 nm narrower than requested, and a spacing check complains about a value nobody typed. The obvious reading is that something in the floorplan editing is wrong, and the obvious response is to look at the floorplan commands.

The floorplan commands are fine. The library's scale factor is 1 000, so the finest length the database can hold is 0.001 µm, and every coordinate you give is multiplied by 1 000 and rounded to an integer. 0.5053 µm becomes 505 database units, which reads back as 0.505 µm. Nothing was edited incorrectly; the number could not be stored in the first place.

The diagnostic is two attribute queries, and the fix is not available at the prompt at all:

# What can this library actually represent?
icc2_shell> get_attribute [get_lib nimbus8.dlib] scale_factor
1000

# And what does the technology file support?
# (the lengthPrecision attribute of the technology file)

The correction is to create the library with the technology file's own length precision — lib.setting.use_tech_scale_factor set to true before create_lib — because the scale factor is chosen when the library is created, not afterwards. Which makes the prevention obvious and slightly uncomfortable: this is a decision made on the first day of a project, by whoever set up the libraries, and it is worth checking on day two rather than in month four.

2.7 Hands-on mini lab

Goal

Turn a session you typed into a session you can hand over. Working on a small synthetic design called Lyra-3, you will audit a session, write a project setup file and a units script, size a farm in cores and licences, and prove the arithmetic twice. No real design data is needed.

Supplied assumptions — Lyra-3

Steps

1. Audit. Start a session and run the four audit commands. Write down what each one tells you, and mark anything that is a fact about you rather than about the project.
2. Units, computed by hand first. Work out the period of clk_dsp in picoseconds, then write down what that period reads as with a 1 ps unit, a 1 ns unit and a 10 ps unit. Only then write scripts/00_units.tcl, which reports the units, sets them, and reports them again.
3. Length precision. For a scale factor of 2 000, compute the smallest representable step in µm and in nm. Then work out what 0.0032 µm is stored as, what it reads back as, and how much is lost.
4. Setup file. Write ./.synopsys_icc2.setup containing a project-relative search_path, the command-log variable, one application option of your choice, and a named host configuration. Finish it with a report command.
5. Farm sizing. Compute the cores on your workstation, the cores in the farm, a process count and cores-per-job that fit the farm, and the licences that parallelism needs. Then check the licence count against what you have and adjust the parallelism, not the licence count.
6. Distributed run. Write the run_block_script command line for the four blocks, with a run order and your named host configuration. Say in one sentence why the run order matters here.
7. Evidence. Write the two lines that keep the command log, and say where the file will end up.
8. Second pass — the review nobody does. Re-read every number you wrote and check it a different way: by inverting the arithmetic, or by checking that a sum still adds up. Note anything that changed.

Expected observations

• clk_dsp at 800 MHz has a period of 1 250 ps (1 ÷ 800 MHz = 1.25 ns). It reads as 1 250 at a 1 ps unit, 1.25 at 1 ns, and 125 at 10 ps.
• Scale factor 2 000 gives a smallest step of 0.0005 µm = 0.5 nm. 0.0032 µm × 2 000 = 6.4, which rounds to 6, reads back as 0.003 µm, and loses 0.0002 µm = 0.2 nm.
• Workstation: 2 × 6 = 12 cores. Farm: 3 × (2 × 8) = 48 cores.
• Two licences cover 16 parallel tasks at one licence per eight — so a process count of 16 is the licence ceiling, and any figure above it is a promise you cannot keep.
• A sensible fit: -num_processes 12 with -max_cores 4 demands 48 cores, exactly the farm — so on a shared farm, 8 processes × 4 cores = 32 cores is the more collegial choice, and it needs only one licence.
• u_dsp_core has two instances; a script run on the same block twice is work done twice, so the block list, not the instance list, is what you want.

Stretch task

Repeat steps 2 and 3 for a project whose constraints are quoted in nanoseconds and whose library scale factor is 10 000, and write two sentences on which of the two projects is more likely to produce a number nobody can explain, and why. Then do the harder version of the same question: your project reports in picoseconds and a vendor delivers a timing model quoted in nanoseconds. Which units do you set for input, which for output, and what do you put in the log so that the next engineer can tell what happened?

2.8 Interview preparation

Sixteen questions, grouped by level. Answer each one out loud before reading the model answer; the gap between the two is the part worth studying. Interviewers ask about this material for a specific reason: it separates the candidates who have run a flow from the candidates who have watched one.

Beginner

Intermediate

Scenario and debugging

2.9 Chapter close

Sign-off checklist for a working environment

Key-concept flashcards

Compact glossary

Five-question self-check

1. A design's fastest clock is 1.25 GHz. What is its period in picoseconds, and what does that period read as with a 1 ns time unit and with a 10 ps time unit?
2. A library has a scale factor of 2 000. What is the smallest length step it can represent, in µm and in nm? What is 0.0007 µm stored as, and what does it read back as?
3. You set a block-scoped application option with -as_user_default and save the block. Is the setting there tomorrow? Why?
4. Your farm has three machines with two CPUs of eight cores each. You configure -num_processes 10 and -max_cores 6. How many cores does that demand, does it fit, and how many licences does it need?
5. A script sets sh_continue_on_error to true and finishes with no visible errors, but the resulting database has no routing tracks. What happened, and which two files would you look at?

One-page recap

Where the next chapter goes, and why

You can now start a session that configures itself, ask the tool about its own behaviour, prove what your numbers mean, and use the machines you are entitled to. That is the whole of “how to drive the tool”. What remains is the work itself.

Chapter 3 takes the first step of it, and it follows directly from two things in this chapter. Chapter 1 established that a hierarchical plan hands each block team its own piece of the problem; this chapter established that a session's units, options and scripts have to be identical for everyone or nothing is reproducible. Put those together and a question appears immediately: the top-level design has one set of timing constraints, describing clocks, modes and corners for the whole chip — so how does each block get the part of those constraints that belongs to it, in a form its own session can read?

That is constraint splitting, and it is the subject of Chapter 3: the flow that divides a top-level constraint set across the physical hierarchy, the files it generates, how blocks are mapped to their constraint and power-intent files, and what clocks, modes, corners and scenarios mean once a design has more than one of each. It is the last piece of preparation before the floorplan itself.