Understanding the Innovus Environment and Session: how a session starts

Why this chapter matters in a real project

Many common early failures in a physical design flow are not design problems. They are environment problems. The wrong release was started. A personal startup file changed a setting. The license was missing. The disk was full.

The failure shows up as a strange message in the middle of a flow, and the cause is far away from it. An engineer can lose a day chasing a "bug" that a two-minute check would have caught.

The opposite mistake is just as costly. A run ends with status zero and no error word, so the team calls it good. Later someone finds that a step never ran. A clean-looking run that proves nothing is a missed real failure.

A short, careful check of the environment catches many of these surprises. It costs minutes. It also gives you a record of how a session was started, so that someone else can repeat it. See Figure 1 for the whole chapter on one page.

Prerequisites

• A working knowledge of a Linux terminal: typing a command, reading its output, changing folders.
• For the lab (Part II): a 64-bit Linux host with Bash and a text editor. No design, no PDK (process design kit) and no download is needed.
• For Track B of the lab only: an Innovus that you are allowed to use. Without it you can still finish Track A, which proves your shell side.
• Your site administrator's answers on the install location, the license setup and your CPU allocation. This guide does not guess them.
• You do not need to know Tcl. The few Tcl rules we use are explained where they appear.
• You do not need to know any implementation step. No design is loaded in this chapter.

Learning objectives

1. Describe an Innovus session as a chain: you, the shell, an executable, a tool process and a Tcl interpreter.
2. Keep installation, environment and licensing apart, and say what each one proves.
3. Explain why the release and the user interface must be known before you trust any example.
4. Predict how the working folder, startup files and temporary storage change a session.
5. Read a CPU request, a scheduler allocation and a license as three different things.
6. Say what a log, a command record and an exit status can prove, and what they cannot.
7. Apply these ideas in a short lab, and record each result as PASS, FAIL, UNKNOWN or NOT PERFORMED.

Environment and session on one page

The chain from keyboard to Tcl, what the session depends on, and what it leaves behind

What to notice: Each panel answers a different question. The result bar states the limit: a clean start proves only that a session can start.

Come back to it whenever you lose your place.

Part I - Understanding the environment and the session

Part I teaches ideas. It asks you to run nothing. Where a short example helps, it is self-contained. Bash examples run in a Bash terminal. Examples at the Innovus prompt need a licensed tool. Part II is a separate lab that applies these ideas.

Output that only a licensed tool can print is marked as an example, because this guide cannot run Innovus for you. Tool behavior described here is for the Legacy UI of one release. Your installed release can differ. Check each option in your own installation with help before you trust it, from any guide, this one included.

1  Where this chapter fits

Before a design can be implemented, a tool session must start in a known state. If the state is unknown, every later result is open to doubt.

Let us begin with the question: what must be true before we load a design?

A chip design reaches physical implementation as a gate-level netlist. A netlist lists logic gates and the wires between them. It carries no positions. A tool must place the gates, build the clock network, route the wires and check the result. This family of tasks is called place and route, or PNR.

Innovus is the Cadence tool for this work. It reads design files and keeps the design in memory, in a database. You give it commands in Tcl, at a prompt or from a script file. The database lives only as long as the session. When the session ends, only the files it wrote remain.

Figure 2 shows where this chapter sits in the flow.

Where environment readiness sits

This chapter prepares the session; the next chapter loads a design

What to notice: Each box depends on the one before it. The dashed boxes are later stages. They are destinations here, not lessons.

1.1  Five kinds of "ready"

Thus, a session that starts cleanly has earned only the first row. It says nothing about the rows below it.

1.2  How Part I is organized

2  What happens when a session starts

When a start fails, the first question is "which layer failed?" The answer decides who can fix it and where to look.

Let us follow one command from your keyboard to the tool. There are five layers, and each has a different job. Figure 3 shows them, with the kind of message each layer prints.

Layers between you and the tool

Each layer has its own job and its own kind of message

What to notice: Three layers print their own kind of message, shown boxed on the right. The other two print nothing of their own; their notes are plain italic text. The wording of a message tells you which layer spoke.

2.1  The five layers

You. You type a line, or a scheduler runs the same line for you. An unattended batch job normally has no terminal attached. An interactive allocation can have one. Either way, the command runs through the same layers.

The shell. A shell is a program that reads a line and decides what it means. It expands variables, finds the program you named and starts it. Bash is one shell. The shell knows nothing about Tcl.

The executable. An executable is a file on disk that the system can run. The shell finds it by name. Finding a file is not the same as running it. Nothing has started yet.

The tool process. When the shell starts the file, the operating system creates a process. A process is a running program with its own memory and its own working folder. At this point the tool checks its licenses, reads its startup files and opens its log files.

The Tcl interpreter. Inside the tool process sits an interpreter for Tcl, a small scripting language. Every command you give the tool is a Tcl command. The interpreter reads it and runs it. Some commands only inspect. Some change a setting. Some change the design database. Some write a file.

2.2  Two languages, two interpreters

$ puts "hello"   # a Tcl command; the shell does not know it

bash: puts: command not found

innovus> getVersoin ;# misspelled on purpose; the Tcl interpreter does not know it

invalid command name "getVersoin"

The message text varies by release. The layer that speaks does not.

Both messages say "I do not know this command". They come from different layers. The first one tells you the tool never started. The second one tells you a Tcl interpreter answered. At an Innovus prompt, that interpreter belongs to the tool.

Environment variables show the same split. A shell variable such as $HOME is read by the shell. Inside Tcl, the same value lives in an array named env, so you read it as $env(HOME). A value set in a shell is visible to the tool only if it was exported before the tool started.

2.3  Which layer reports a failure?

Figure 4 shows the same idea in time order. A start passes six stages, and each stage fails in its own way.

Startup sequence and failure boundaries

Six stages, each with its own failure and its own evidence

What to notice: Any exit status, zero included, only shows that stage 5 was reached. Stage 6, a correct task result, needs its own evidence.

Read the figure from top to bottom. Stages 1 and 2 can fail before any of your commands run. Stage 4 is where your own mistakes appear. Only the last stage tells you whether the work was worth doing.

3  Installation, environment and licensing

A tool can be installed and still refuse to start. Installation, environment and license are three separate facts. You check them separately, and each one has its own owner.

Figure 5 shows the three side by side, each with its own check.

Three separate requirements

Installation, environment and license each have their own check

What to notice: The check in one column says nothing about the others. The log and license summary of a started session confirm only what was granted at that moment.

3.1  What each observation proves

Thus, "Innovus starts on my machine" proves less than it sounds like. It proves that one license request succeeded once.

3.2  Kinds of license

• Base license. The tool needs one to start. It must be a full product license. An option license alone cannot start the tool.
• Option license. Some features need one. The tool usually checks these out only when a command needs them. A late checkout can pause a script, or end it, if the license is not available in time.
• Multi-CPU license. Extra CPUs for multithreaded or distributed work can need these. They are product licenses too. They are requested after the base license.

Innovus is sold in several packages, and sites buy different sets. Do not assume that your site has every package or option. Ask.

3.3  Looking at licenses from inside a session

innovus> getLicenseStatus ;# list every license this session holds now

The output is a summary of the licenses checked out now, with feature name and version. Do not assume a fixed layout or a count format. Read what your release and your site print.

These two forms only inspect. However, setLicenseCheck as a whole is not inspection-only. Its -⁠checkout, -⁠default, -⁠optionList and -⁠wait options change how licenses are checked out. Do not use them with values that did not come from your administrator.

setLicenseCheck does not manage multi-CPU licenses. Check those separately, for example with your administrator, before you raise a CPU count.

At launch, the option -⁠wait takes a number of minutes. It sets how long the tool waits for a license before it exits. The default is 0, so the tool does not wait. An instant exit with a license message may therefore be the default behavior, not a server problem.

Options such as -⁠lic_startup and -⁠lic_options choose license names and priority. Use values from your administrator only.

Never look for a way around a license limit. If a license is missing, the safe action is a request.

3.4  Questions to ask, and who answers

4  Finding the tool, its release and its UI

Several installations can share one program name. The wrong release or the wrong command set produces failures that look like script bugs.

Let us trace what happens when you type innovus.

4.1  How the shell finds a program

Your shell keeps a list of folders called the search path, stored in the variable PATH. When you type a bare name, the shell searches the folders from left to right. It runs the first executable file it finds with that name. Later folders are never looked at.

$ echo "$PATH" | tr ':' '\n'   # one folder per line, in search order

/opt/site/tools/bin
/opt/cadence/innovus_old/bin
/opt/cadence/innovus_new/bin
/usr/bin

Suppose both Innovus folders contain a file named innovus. The shell runs the one in innovus_old, because that folder comes first. The newer installation is never used, even though it is installed. Figure 6 draws this search.

How the shell picks one innovus

A left-to-right search that stops at the first match

What to notice: The search stops at innovus_old. The newer file in innovus_new exists but is never reached, so installing it changed nothing.

$ command -v innovus   # print what Bash would use: normally a path
$ type -a innovus      # list every match in order, with aliases and functions

/opt/cadence/innovus_old/bin/innovus
innovus is /opt/cadence/innovus_old/bin/innovus
innovus is /opt/cadence/innovus_new/bin/innovus

An alias or a function prints its own text instead of a path. More than one line from type -⁠a may mean more than one installation. If nothing prints, the tool is not on the search path.

4.2  Two ways to choose the tool

Many sites set the path with a module system or a site setup file. Ask your administrator which one you should use. Do not guess an install location.

Whichever method you use, record the full path that actually ran. A path in your notes is evidence. "I used the usual one" is not.

4.3  Why the release matters

$ innovus -version   # compare it with the release your project owner named

The output is one line naming the release your site installed. This guide cannot predict it.

Inside a session, the Tcl command getVersion returns the same kind of information. getVersion -⁠major returns the major version only.

4.4  Why the user interface matters

The two sets are not interchangeable. Some Tcl and some commands overlap, but you cannot tell which by looking. A script written for one UI is not safely portable to the other without checking each command in your release.

This guide uses the Legacy UI only. Every command it gives is a Legacy command. Do not translate syntax from one UI to the other by guessing.

The launch options -⁠legacy_ui and -⁠stylus exclude each other. Name the one you want every time. Do not rely on a default.

4.5  Where to find help

Inside Innovus, man finds its own pages without extra path setup. Use help and man in your installed release before you trust an option from any guide.

5  Working folders, startup files and temporary storage

A session behaves as its working folder and its startup files dictate. Two people running the same commands can get different results from these two things alone.

Let us start with the working folder. Every process has one. It is the folder the process is "standing in". When a path does not start with /, the system resolves it from the working folder. Such a path is called relative.

5.1  Relative paths and the working folder

$ D=/tmp/cwd_demo                            # one scratch folder keeps lines short
$ mkdir -p "$D/a/data" "$D/b/data"           # make two folders
$ echo "from a" > "$D/a/data/in.txt"         # same relative name, content "from a"
$ echo "from b" > "$D/b/data/in.txt"         # same relative name, content "from b"
$ (cd "$D/a" && cat ./data/in.txt)           # read from folder a; ( ) keeps your folder
$ (cd "$D/b" && cat ./data/in.txt)           # read the same relative path from folder b

from a
from b

The command text did not change. The working folder did. The answer changed with it. Figure 7 draws the same effect.

Same relative path, different working folder

The text ./data/in.txt resolves from wherever the process stands

What to notice: The command text is identical in both columns. Only the working folder differs, and so does the file that is read.

The Tcl commands pwd and cd show and change the working folder inside the tool. They do not change the folder of the shell that started it.

An absolute path starts with /. It means the same thing from any folder. For files that must be found reliably, an absolute path removes one source of doubt.

5.2  Startup files: what runs before your first command

The Common UI reads a different list of files. This guide does not cover it.

Any of these files can change settings before your commands run. The file in the current folder is easy to forget. A personal file can set a CPU count or change a default without leaving any trace in your own script.

$ ls -l ~/enc.tcl ./enc.tcl   # "No such file" is a good answer here

ls: cannot access '/home/you/enc.tcl': No such file or directory
ls: cannot access './enc.tcl': No such file or directory

What runs before your first command

Legacy UI startup files, in the order they are read

What to notice: The later files can change what the earlier ones set. The current-folder file is the easiest to forget, and none of them appears in your own script.

If a file exists, read it and note what it does before you trust the session. Do not delete or rename a file you did not write. Ask its owner.

The launch option -⁠disable_user_startup skips ~/enc.tcl and ./enc.tcl. The installation enc.tcl is still read. Whether to use it for a shared flow is a decision for the project owner. It trades flexibility for certainty.

5.3  Temporary storage

Each session creates its own temporary folder. Its name begins innovus_temp_, followed by the process number, host name, user name and a unique string. The tool uses it for scratch data while the session runs.

The tool makes the folder in the folder you launch from, and uses /tmp when that folder is not writable. Confirm this on your release. The tool removes it when the session ends normally, or after a signal it can catch. A hard kill gives the tool no chance to clean up.

The variables FE_TMPDIR and TMPDIR follow a separate rule, for the temporary files of parasitic extraction. The tool tries FE_TMPDIR, then TMPDIR, then the current folder, then /tmp. Figure 9 puts the two rules side by side.

Where do temporary files go?

Two separate rules: the session folder and the extraction files

What to notice: TMPDIR appears only in the right-hand rule. Setting it does not move the session folder; confirm on your release.

$ if [ -z "${TMPDIR+x}" ]; then echo "TMPDIR is unset"   # unset, empty or set?
> elif [ -z "$TMPDIR" ]; then echo "TMPDIR is set but empty"
> else echo "TMPDIR=$TMPDIR"; fi
$ df -Pk .     # free space, in kilobytes, for the current folder
$ ls -ld /tmp  # permissions of /tmp, the fallback if the launch folder is read-only

TMPDIR is unset
Filesystem     1024-blocks     Used Available Capacity Mounted on
/dev/sda1        102400000 61440000  40960000      60% /
drwxrwxrwt 12 root root 4096 Oct 12 09:30 /tmp

Inside a session, report_disk -⁠dir /tmp reports used and free space and the disk speed of a folder. Here /tmp is only an example folder; name the one you care about.

6  Interactive, batch and headless execution

The same tool can run with a prompt, with no prompt, with a window, or with no window. Each choice changes what the session needs and how it ends.

They are four different facts.

6.1  The words

• An interactive session shows a prompt and waits for you to type commands. It ends when you type exit, or when the process is killed.
• A batch session has no prompt. With the launch option -⁠batch, the tool processes the commands and files you gave it at launch, and then exits by itself.
• A GUI (graphical user interface) is the graphical window. Started with no options, innovus opens a GUI. The launch option -⁠no_gui turns the GUI off for the whole session. A session without a GUI needs no display.
• Headless means there is no display attached. A scheduler job on a compute host is usually headless.

Useful work does not need a GUI. A great deal of implementation work runs in sessions that never open a window.

6.2  What each mode needs

A batch run on a compute host needs neither a keyboard nor a screen. An interactive run in a job with no input attached may wait for input that never comes. It looks like a hang. Some schedulers can give a job a terminal, and then an interactive run can work. For unattended work, choose batch.

6.3  Four facts, four different pieces of evidence

A batch session that ended is not a batch session that succeeded. "It finished" and "it worked" are different sentences.

6.4  Ending on error

The launch option -⁠abort_on_error makes the process exit on a Tcl error that reaches the top level, or on any Error message. This stops a long script from continuing after a failure.

Which exit status your installation then returns is not stated here, and it may vary. Test it before you depend on it: force a Tcl error in a test session, and read the status. Step 7 of the lab does exactly this.

7  CPU requests and resource allocation

Extra CPUs (central processing units) can shorten long steps. They also need licenses, memory and an allocation that matches your request. A request alone proves none of these.

This guide treats one machine. Distributed processing and superthreading get an overview only, because they need real infrastructure.

7.1  The local CPU setting

The value max means the processor count that the machine reports. A value larger than the machine has gives a warning. Which count the run then uses is not known here, so read the log and do not assume. A thread count only caps how many threads may run at once. It does not make cores appear.

# A startup file may have set another value, so state it.
innovus> setMultiCpuUsage -localCpu 4 ;# ask for four local CPUs
innovus> getMultiCpuUsage -localCpu ;# print the setting so the log shows it

You can also request CPUs at launch with -⁠cpus and a number. That option may need extra multi-CPU licenses. Setting the value in a Tcl command instead has one advantage: the command appears in the log.

7.2  A request is not an allocation

Let us consider a host with eight cores. Your scheduler gives your job four. Figure 10 draws what happens when you request four, and when you request eight.

A CPU request is not a CPU allocation

Eight cores on the machine, four allocated to your job

What to notice: In the last row, the four extra threads (red) squeeze onto the four allocated cores. They do not get cores 5 to 8. Whether other jobs suffer depends on how the site enforces limits.

If you request eight, four of those threads share cores with your own other threads. Depending on how the site enforces limits, they may also take time from other jobs. Your run may not get faster, and the scheduler or the site may stop it. The rule is simple: request what you were allocated, no more.

$ nproc   # honors some limits, such as a processor affinity list

8

nproc may not show every limit, for example a time-share quota. Ask the scheduler owner.

7.3  What else a CPU request touches

By default, CPU licenses stay held until the session ends. Two options of setMultiCpuUsage control this. -⁠keepLicense (default true) holds the licenses until the session ends. -⁠releaseLicense gives them back at once. Your site policy decides.

7.4  More CPUs are not proportionally faster

Doubling the threads does not halve the run time. Some work is serial. Threads share memory and disk.

Let us use a simple illustration. Suppose one tenth of a run cannot be parallel. With four CPUs, the best possible speedup is about 3.1 times. With eight CPUs, it is about 4.7 times. Figure 11 plots this.

These numbers come from a textbook formula, not from a measurement of Innovus. They only show the shape: each extra CPU buys less.

Multithreaded timing reports can also change their order between runs. When two paths have equal slack, the tool may list them differently. Compare slack values, not list positions.

Each extra CPU buys less

Best-case speedup when one tenth of the run is serial

What to notice: Going from 4 to 8 CPUs doubles the request but raises the best case only from 3.1 to 4.7 times. The gap to the ideal bars grows with every CPU.

7.5  Looking at resource use

The option setMultiCpuUsage -⁠threadInfo takes 0, 1 or 2. It sets how much thread detail goes in the log. Level 0 is the default and prints none.

7.6  Distributed processing, in short

checkMultiCpuUsage tests the setup. Among other things it checks that the clients can reach the working folder. This matters because the folder must be visible from every machine.

setDistributeHost takes site-specific queue and resource strings. Get them from your administrator. Do not invent them. If you have no such infrastructure, skip this part.

8  Logs, command records and exit status

After a run, you cannot see what happened. You can only read what it left behind. Knowing what each trace can and cannot prove protects you from false confidence.

Let us list the evidence a run can leave. For each trace we ask one thing: what question does it answer? Figure 12 pairs each trace with its question.

8.1  The three log files

If a .log file with that name exists, the tool adds a number to all three names. Only the .log file is tested for this. The option -⁠overwrite replaces existing files instead. The options -⁠no_cmd and -⁠no_logv skip the other two files. If you choose -⁠overwrite, you choose to lose earlier evidence.

Evidence sources and the questions they answer

Six traces, six different questions

What to notice: Different sources fail in different ways. A trace you cannot find is a missing answer, not a "yes".

8.2  How complete is the command record?

Thus, treat the command record as helpful, not complete. Printed text is a different matter. A puts command that runs writes its text to the console output, which the .log file captures.

8.3  Reading a log safely

$ grep -n -B3 -A3 "Error" run.log   # 3 lines of context; add -i to ignore case
$ tail -n 30 run.log                # last thirty lines: a stop leaves its last words

Here run.log is an example name; use your own log. For a message with an identifier, help or man followed by the message ID inside Innovus gives a summary. The man form can add causes and fixes for messages that have them.

8.4  Exit status

Every program ends with a number called its exit status. By convention, zero means success and other numbers mean something else. Each command defines its own meanings. For example, grep returns 1 when nothing matched, and that can be an expected answer. The shell stores the status of the last command in the variable $?.

$ ls /no/such/folder; echo "exit status: $?"   # run, then print its status at once

ls: cannot access '/no/such/folder': No such file or directory
exit status: 2

A status is a single number. It tells you how the process ended. It does not tell you why, and it does not tell you whether the work was right.

8.5  Three places a run can fail, and what no status can see

A zero exit status therefore proves one thing: the process ended with zero. It does not prove that the inputs were right or that reports exist. It does not prove that a step you meant to run was reached.

8.6  How a status gets lost

Between you and the tool there may be several programs, such as a build tool and a wrapper script. Each one has its own exit status. If any link discards the child's status, a failure looks like success. Figure 13 shows the most common case, a pipe.

$ false | cat; echo "status: $?"                         # reports the last command only
$ ( set -o pipefail; false | cat; echo "status: $?" )   # pipefail reports the failure

status: 0
status: 1

The parentheses run the second line in a subshell, so your own shell's options stay as they were.

How a pipe loses a status

The same failing command, with and without pipefail

What to notice: The failing command is the same in both rows. Only the shell option changes which status reaches you.

A careful wrapper saves the child's status on the very next line and returns it unchanged. The saving matters because $? describes only the most recent command: the next command replaces it. A variable such as rc, set by rc=$?, keeps its value until you assign it again.

The examples in this guide assume an interactive Bash terminal with the option errexit off. With it on, a deliberate failure could end the shell before you read the status.

8.7  Why "no ERROR in the log" does not prove success

Real evidence combines several traces: the exit status, the expected reports, and a read of the end of the log. A missing report is a failed check. The absence of an error word is not a passed check.

9  Reproducibility and readiness

A run you cannot repeat or explain is a one-off. Reproducible execution turns "it worked once" into evidence another engineer can check.

If you cannot, the run was a one-off. If you can, someone else can repeat it, compare it, and trust or question it.

9.1  Four habits that make a run reproducible

• Known settings. Choose settings on purpose, and state them, even when they equal the default. A default that comes from a startup file you forgot is not a known setting.
• Identifiable runs. Give every run its own identity, such as a date and time or a counter, and its own folder. Never reuse an identity. A reused identity overwrites the evidence of the earlier run.
• Preserved evidence. Keep the logs, the exit status, the reports and a record of what you asked for. Keep failed runs as well. A failed run next to a fixed run shows exactly what the fix changed.
• Explicit unresolved issues. Write down what you do not know. "Unknown" is a valid status. "Unknown" is not "pass". A gap you wrote down can be closed later. A gap you forgot becomes a surprise.

9.2  General principles and one team's choices

9.3  What a successful startup establishes

9.4  Recovering safely

When something fails, change one thing at a time. Record the cause before you fix it. Run again with a new identity so the failed run stays on disk.

9.5  Check your understanding

Try each question before you read the answer. The questions need no files and no tool.

Part II - Lab: applying the concepts

Part II applies the ideas of Part I in a short, separate lab. You do not need it to understand Part I, but Part I makes the lab easier. The lab needs this guide, an interactive Bash terminal and a text editor. Nothing else comes with it. The lab teaches no new idea. It asks you to watch the ideas of Part I behave, and to write down what you saw. Each step points back to the section it applies.

10  Lab overview

Ideas stay abstract until you see them behave. A small lab turns "a request is not an allocation" and "status zero is not a verdict" into things you have seen.

10.1  Lab at a glance

10.2  Two tracks, and exactly what each one runs

Track A has no licensed tool. You inspect your shell and folders, you may write the Tcl file as text, and you run the missing-executable check. You never start Innovus. So you never run the Tcl file, and you do not claim that it was validated.

10.3  Where each idea shows up

Table 20 maps each idea to a step. Figure 14, after the next table, shows the seven steps and their evidence.

10.4  Three kinds of check, kept apart

Lab flow and the evidence each step leaves

Seven steps; Track A runs steps 1, 3 and 6

What to notice: Track A runs steps 1, 3 and 6, the green cards marked "Tracks A and B" or "A: text only". Track B runs all of them. Every run gets a folder of its own.

11  Lab steps

Now we do it. For each step we say why we need it, we run it, and we check what we see.

Every block below says which track runs it. A Track A reader who sees "Track B only" simply moves to the next heading. Skipping is not failing.

# Report whether errexit is on in this shell. A fresh terminal is off.
case "$-" in
  *e*) echo "errexit is ON: open a fresh terminal before you go on" ;;
  *)   echo "errexit is off: OK" ;;
esac

11.1  Step 1: a lab folder, and a look at your setup (both tracks)

# Choose the lab folder. LAB stays set only if the folder is ready.
LAB="$HOME/innovus_lab1"
if mkdir -p "$LAB" && cd "$LAB"; then
  LAB="$PWD"
  echo "lab folder ready: $LAB"
else
  unset LAB
  echo "STOP: could not create or enter the lab folder."
  echo "Fix that before you run any later block."
fi

# Do the inspection only if the lab folder is ready.
if [ -n "${LAB:-}" ] && [ -d "$LAB" ]; then
  # Show the search path, one folder per line, in search order.
  echo "$PATH" | tr ':' '\n'
  # Say whether TMPDIR is unset, empty or set.
  if [ -z "${TMPDIR+x}" ]; then echo "TMPDIR is unset"
  elif [ -z "$TMPDIR" ]; then echo "TMPDIR is set but empty"
  else echo "TMPDIR=$TMPDIR"; fi
  # Show free space, in kilobytes, for the lab folder.
  df -Pk "$LAB"
  # Look for a personal startup file in your home folder.
  if [ -e "$HOME/enc.tcl" ]; then
    ls -l "$HOME/enc.tcl"; echo "read it before you trust a session"
  else
    echo "no personal startup file in your home folder"
  fi
  # Count the processors this shell may use. This is not an allocation.
  nproc
else
  echo "STOP: the lab folder is not ready. Run the previous block."
fi

# Show what Bash would run for the name. It prints nothing if none.
if command -v innovus; then
  # Show every match in order, including aliases and functions.
  type -a innovus
else
  echo "no innovus on this shell's search path: record it as found-none"
fi

11.2  Step 2: choose the executable and test it (Track B only)

Track A: skip to Step 3. Track B: now we need to know which Innovus we will run. We name the file with its full path and test it before we use it. If your site needs a module or a setup script first, do that in this terminal and write down which one. This step applies the license and search-path sections.

# Replace the text in quotes with the full path from your administrator.
INNOVUS_BIN="/replace/with/full/path/to/innovus"

# Accept the path only if every test passes. INNOVUS_OK records it.
INNOVUS_OK=no
case "${INNOVUS_BIN:-}" in
  "")
    echo "STOP: INNOVUS_BIN is empty or not set" ;;
  /replace/*)
    echo "STOP: the placeholder is unchanged. Replace it." ;;
  /*)
    if [ -d "$INNOVUS_BIN" ]; then echo "STOP: that is a directory"
    elif [ ! -e "$INNOVUS_BIN" ]; then echo "STOP: no such file"
    elif [ ! -f "$INNOVUS_BIN" ]; then echo "STOP: not a regular file"
    elif [ ! -x "$INNOVUS_BIN" ]; then echo "STOP: you cannot run it"
    else INNOVUS_OK=yes; echo "executable accepted: $INNOVUS_BIN"
    fi ;;
  *)
    echo "STOP: not an absolute path. It must start with /" ;;
esac

# Ask the chosen file for its version, only if it was accepted.
if [ "${INNOVUS_OK:-no}" = yes ] && cd "${LAB:-/nonexistent}"; then
  # Prove the evidence file can be written before the program starts.
  if : > "$LAB/version_output.txt"; then
    "$INNOVUS_BIN" -version > "$LAB/version_output.txt" 2>&1
    version_status=$?
    echo "version command status: $version_status"
    cat "$LAB/version_output.txt"
  else
    echo "STOP: cannot write $LAB/version_output.txt"
  fi
else
  echo "STOP: no accepted executable, or no lab folder. Skipped."
fi

11.3  Step 3: write one short Tcl file (both tracks)

Now we need something for the tool to run. One short file asks the session who it is, requests a CPU count, and prints what the session reports. A request and an observation stay on separate lines. This step applies the CPU section. Table 22 summarizes the file before we write it.

# Choose a whole number. Track B: use your scheduler allocation.
CPUS=2
# Accept digits only, one or more. Reject empty, zero, leading zero.
case "$CPUS" in
  ''|*[!0-9]*|0|0[0-9]*)
    CPUS_OK=no; echo "STOP: CPUS must be a whole number, 1 or more" ;;
  *)
    CPUS_OK=yes; export CPUS; echo "CPUS=$CPUS accepted" ;;
esac

Track A: you create this file as text only. You cannot run it, because it uses Innovus commands that a standard Tcl interpreter does not have. Do not call it validated.

# Write the Tcl file only if CPUS and the lab folder are good.
# The quoted EOF stops the shell from changing the Tcl text.
if [ "${CPUS_OK:-no}" = yes ] && cd "${LAB:-/nonexistent}" &&
    cat > startup_check.tcl <<'EOF'
# startup_check.tcl -- Innovus Tcl, Legacy UI.
puts "STARTUP_MARKER_1 begin"
puts "STARTUP_MARKER_2 version: [getVersion]"
puts "STARTUP_MARKER_3 working folder: [pwd]"
set cpus 1
if {[info exists ::env(CPUS)]} { set cpus $::env(CPUS) }
puts "STARTUP_MARKER_4 requested CPUs: $cpus"
setMultiCpuUsage -localCpu $cpus
puts "STARTUP_MARKER_5 reported CPU setting:"
getMultiCpuUsage -localCpu
puts "STARTUP_MARKER_6 licenses held now:"
getLicenseStatus
if {[info exists ::env(TMPDIR)]} {
  puts "STARTUP_MARKER_7 TMPDIR: $::env(TMPDIR)"
} else {
  puts "STARTUP_MARKER_7 TMPDIR: unset"
}
puts "STARTUP_MARKER_8 end"
EOF
then
  echo "wrote $LAB/startup_check.tcl"
  wc -l startup_check.tcl
else
  echo "STOP: the Tcl file was not written."
  echo "Check Step 1 (LAB) and the CPUS block, then paste this again."
fi

11.4  Step 4: start one session (Track B only)

Track A: skip to Step 6.

# Make a new run folder and copy the Tcl file into it. Check each step.
RUN_OK=no
if [ "${INNOVUS_OK:-no}" = yes ] && [ "${CPUS_OK:-no}" = yes ] &&
   [ -f "${LAB:-/nonexistent}/startup_check.tcl" ]; then
  RUN="$LAB/run_$(date +%Y%m%d_%H%M%S)"
  if mkdir "$RUN" && cp "$LAB/startup_check.tcl" "$RUN/" && cd "$RUN"; then
    RUN_OK=yes
    echo "run folder ready: $RUN"
  else
    echo "STOP: could not prepare $RUN. Keep it, and try again."
  fi
else
  echo "STOP: Steps 1 to 3 are not complete. Nothing was started."
fi

The two personal files are not the whole list. You cannot inspect the installation file unless you know where it is, so ask your CAD owner.

# Check the launch folder itself, the one the tool will start in.
if [ "${RUN_OK:-no}" = yes ] && cd "$RUN"; then
  echo "launch folder: $PWD"
  if [ -e ./enc.tcl ]; then ls -l ./enc.tcl; echo "READ it first"
  else echo "no ./enc.tcl in the launch folder (normal for a fresh one)"
  fi
  if [ -e "$HOME/enc.tcl" ]; then echo "home enc.tcl exists: see Step 1"
  else echo "no enc.tcl in the home folder"
  fi
else
  echo "STOP: the run folder is not ready."
fi

# Launch the copy inside the run folder, not the original.
if [ "${RUN_OK:-no}" = yes ] && cd "$RUN" &&
   [ -f startup_check.tcl ]; then
  # Build the launch line as a list, so every argument stays whole.
  cmd=( "$INNOVUS_BIN" -legacy_ui -no_gui -batch -log startup
        -files "$RUN/startup_check.tcl" )
  # Save the exact line first. If that fails, do not start the tool.
  line="CPUS=$CPUS $(printf '%q ' "${cmd[@]}")"
  if echo "$line" > command_line.txt; then
    echo "command line saved"
    # Start the tool. It reads the file, then ends by itself.
    "${cmd[@]}"
    rc=$?
    if echo "tool_status=$rc" > exit_status.txt; then
      echo "attempt finished; saved tool_status=$rc"
    else
      echo "WARNING: exit_status.txt NOT written; the status was $rc"
    fi
  else
    echo "STOP: could not save the command line. Tool not started."
  fi
else
  echo "STOP: the run folder is not ready. Tool not started."
fi

The saved line starts with CPUS= and your value, so it replays the environment too. We chose none of -⁠abort_on_error, -⁠cpus or -⁠overwrite, so this run does not depend on them.

The variable rc holds the status until you assign it again. $? does not wait: the next command changes it, which is why we copy it on the very next line. A failed save stops the launch. A failed tool does not stop the saving of its status.

11.5  Step 5: read the evidence (Track B only)

Track A: skip to Step 6.

Now we read what the run left behind. We ask each file one question and keep four answers apart: matched, read with no match, missing or unreadable, and search failed.

Only a file we have actually read can support "marker absent". A small helper keeps the four answers apart, as Figure 15 shows. First we define it.

Four verdicts from one search

How check_pattern keeps "absent" apart from "unknown"

What to notice: UNKNOWN comes before any search. A grep status other than 0 or 1 becomes SEARCH ERROR, never NO MATCH.

# check_pattern FILE REGEX searches FILE and prints one of four verdicts.
# Return value: 0 readable and matched   1 readable, no match
#               2 missing or unreadable 3 the search itself failed
check_pattern () {
  local s
  if [ ! -f "$1" ] || [ ! -r "$1" ]; then
    echo "UNKNOWN: $1 is missing or unreadable"
    return 2
  fi
  grep -n -- "$2" "$1"
  s=$?
  case "$s" in
    0) echo "MATCH: found in $1"; return 0 ;;
    1) echo "NO MATCH: $1 was read and has none"; return 1 ;;
    *) echo "SEARCH ERROR: grep status $s on $1"; return 3 ;;
  esac
}

# Read the evidence in the run folder.
if [ "${RUN_OK:-no}" = yes ] && cd "$RUN"; then
  ls
  echo "--- saved command and status"
  cat command_line.txt exit_status.txt
  echo "--- emitted markers in the console log"
  if check_pattern startup.log '^STARTUP_MARKER_[0-9]'; then
    n=$(grep -o '^STARTUP_MARKER_[0-9]' startup.log | sort -u | wc -l)
    echo "distinct emitted markers: $n of 8"
  fi
  echo "--- error lines"
  check_pattern startup.log '[Ee][Rr][Rr][Oo][Rr]'
  echo "--- the last lines of the log"
  if [ -r startup.log ]; then tail -n 25 startup.log
  else echo "UNKNOWN: startup.log is missing"; fi
  echo "--- the command record"
  check_pattern startup.cmd 'STARTUP_MARKER'
  echo "--- a temporary folder left in the launch folder"
  ls -d innovus_temp_* 2>/dev/null || echo "none left"
else
  echo "STOP: the run folder is not ready."
fi

11.6  Step 6: the missing-executable check (both tracks, required for Track B)

# Do the check only in a fresh folder, and only if the name is unused.
if [ -n "${LAB:-}" ] && cd "$LAB"; then
  DRILL="$LAB/drill_$(date +%Y%m%d_%H%M%S)"
  BAD="/no/such/folder/innovus"
  if [ -e "$BAD" ]; then
    echo "STOP: $BAD exists here. Set BAD to a path that does not."
  elif mkdir "$DRILL" && cd "$DRILL"; then
    # Start the missing program as in Step 4. The shell answers.
    "$BAD" -legacy_ui -no_gui -batch -log startup
    shell_status=$?
    if echo "shell_status=$shell_status" > drill_status.txt; then
      echo "saved shell_status=$shell_status"
    else
      echo "WARNING: drill_status.txt NOT written; status $shell_status"
    fi
    # List the folder. No tool log should be there.
    ls
  else
    echo "STOP: could not create the check folder."
  fi
else
  echo "STOP: the lab folder is not ready."
fi

bash: /no/such/folder/innovus: No such file or directory
saved shell_status=127
drill_status.txt

Thus, the shell spoke. No Innovus process started, and no startup.log was written; only our status file is in the folder. Status 127 comes from the shell, not from a tool. This check tests a refused launch. It does not test what Innovus does with a Tcl error, which is Step 7.

11.7  Step 7: an intentional Tcl error (optional, Track B only)

Track A: skip to the evidence worksheet.

Now we ask a different question: what happens when a command inside a running tool fails? A tool that starts and then meets a bad command is a process. A missing executable never was one.

We run one bad Tcl file twice, once with -⁠abort_on_error and once without. For each run we record three things separately, as the callout below lists. This step applies the execution-mode and exit-status sections.

# Write a tiny Tcl file with one command that does not exist.
if cd "${LAB:-/nonexistent}" &&
    cat > bad_command.tcl <<'EOF'
puts "ERRDRILL_MARKER_1 before the error"
thisIsNotAnInnovusCommand
puts "ERRDRILL_MARKER_2 after the error"
EOF
then echo "wrote bad_command.tcl"
else echo "STOP: bad_command.tcl was not written"; fi

# err_run LABEL [tool options] runs the bad file once in a new folder.
# Return value: 0 the tool ran and its status was saved;
#   3 the tool ran, but its status could not be saved; 1 setup failed, tool NOT started
# The tool's own status is saved in tool_status.txt, never returned.
err_run () {
  local label="$1" d rc line result=0
  shift
  if [ "${INNOVUS_OK:-no}" != yes ] ||
     [ ! -f "${LAB:-/x}/bad_command.tcl" ]; then
    echo "setup incomplete: tool not started"; return 1
  fi
  d="$LAB/err_${label}_$(date +%Y%m%d_%H%M%S)"
  if ! mkdir "$d" || ! cp "$LAB/bad_command.tcl" "$d/"; then
    echo "could not prepare $d: tool not started"; return 1
  fi
  if ! pushd "$d" > /dev/null; then
    echo "could not enter $d: tool not started"; return 1
  fi
  local args=( "$INNOVUS_BIN" -legacy_ui -no_gui -batch "$@"
               -log errdrill -files "$d/bad_command.tcl" )
  line=$(printf '%q ' "${args[@]}")
  if ! echo "$line" > command_line.txt; then
    echo "could not save the command line: tool not started"
    popd > /dev/null; return 1
  fi
  "${args[@]}" > console.txt 2>&1
  rc=$?
  if echo "tool_status=$rc" > tool_status.txt; then
    echo "$label: tool_status=$rc (saved in $d)"
  else
    echo "$label: tool_status=$rc (NOT saved: write failed)"; result=3
  fi
  popd > /dev/null
  return $result
}

# Run once with the option that ends the run on an error, once without.
err_run abort -abort_on_error; echo "helper status: $?"
err_run plain; echo "helper status: $?"

# Read both runs. This uses check_pattern from Step 5.
for d in "$LAB"/err_abort_* "$LAB"/err_plain_*; do
  if [ -d "$d" ]; then
    echo "=== $d"
    cat "$d/tool_status.txt" 2>/dev/null || echo "UNKNOWN: no saved status"
    check_pattern "$d/errdrill.log" '^ERRDRILL_MARKER_[0-9]'
  fi
done

12  Evidence worksheet and completion

12.1  Part A: shell-side rows (both tracks)

12.2  Part B: licensed-tool rows (Track B only)

12.3  Completion

Three completion levels

Each level needs more evidence than the one below

What to notice: A failed startup can still reach level 1. "Every row has some status" is level 1, not level 3.

The level 3 criteria are:

• the executable accepted;
• the command line and status saved;
• the .log readable, with markers 1 to 8 emitted;
• a release line reported;
• a CPU setting printed that matches the request, or a difference you can explain;
• license output present, and no unexplained error lines in the log;
• the scheduler allocation compared, or marked NOT PERFORMED with a reason.

12.4  What this lab does not prove

• It does not show timing closure, routability, power connectivity or signoff.
• It does not show that a real design imports. That is the next chapter.
• A stand-in run of these commands is not Innovus. Do not report it as such.
• The Ctrl-C and scheduler-kill behavior of a real session was not tested here.
• Release and license details are site-specific. Ask your administrator.

13  Troubleshooting and evidence classes

Most startup failures have a short list of causes. Look first, then change one thing at a time, and ask the right owner. In Table 26, the first-check column only observes. The recovery column changes something, so do it after you have written the first check down.

When something fails: record the cause, change one thing, run again in a new folder, and keep the failed folder.

13.1  What kind of evidence supports each claim

Five classes of evidence are kept apart in this chapter. A claim carries only the class it earned, as Table 27 shows. Where a statement here differs from your release, your release is right. Check the same topics with -⁠help and help in your own installation, and note any difference in the worksheet.

14  Interview preparation

15  Chapter close

Compact glossary

Environment and session on one page

Figure 1, at the start of the chapter, is the picture of this summary.

Purpose. This chapter teaches how an Innovus session starts, what can fail at each layer, and what the evidence proves. It prepares a session that starts as intended. It imports no design.

Workflow map. You, then the shell, the executable, the tool process and the Tcl interpreter, then files that outlive the session.

Key concepts.

• Installation, environment and licensing are three separate requirements.
• The layer that speaks tells you where a failure happened.
• The release and the UI must be known before an example is trusted. Legacy UI and Common UI are not interchangeable.
• The working folder decides what a relative path means. Startup files change a session before your first command.
• The session's temporary folder goes in the launch folder, or /tmp if that is not writable. TMPDIR applies to extraction files. Confirm on your release.
• A CPU request is not an allocation. More CPUs are not proportionally faster.
• A log, a command record and an exit status each answer one question. None proves a correct result.

Evidence to keep. The command line that started the session, the full path of the executable, the release string, and the logs. Also the exit status, the reports the session wrote, and a written list of unresolved items.

Command cheat sheet

# Needs INNOVUS_BIN and RUN. Start it from the run folder.
cmd=( "$INNOVUS_BIN" -legacy_ui -no_gui -batch -log startup
      -files "$RUN/startup_check.tcl" )
cd "$RUN" && "${cmd[@]}"
rc=$?

Where the next chapter goes, and why

We now have a session we can prove. It has the right executable, a known release, UI and folder, a stated CPU request and evidence on disk. That is startup readiness, the first row of Table 1.

The next chapter, Design Data Preparation, Import, Sanity Checks and Export, earns the second row. It loads and checks the design inputs in a session like this one, with the same habits.