Efficient Design Analysis with Linux Command-Line Utilities

Hello! Last lesson distinguished PVT and RC corners, modes, and the scenarios that combine them. In practice, you often first encounter those choices as filenames, log messages, and report headers. Today you’ll use the Linux command line to locate design inputs, inspect a run’s progress, and check which scenario a report describes. Allow about 40 minutes, including the short videos and a small terminal walkthrough.

First, establish where the files are

A physical-design workspace might contain inputs/ for a netlist and SDC, logs/ for tool output, and reports/ for timing or congestion results. These are useful conventions, not guaranteed directory names. Before interpreting a file, establish its path, type, and run context. A report with the right name but from an older run can be more misleading than no report at all.

The Software Carpentry reading below covers the minimum navigation vocabulary. You do not need its example dataset; translate the commands to your own workspace.

In a project directory, this is a sensible first look:

pwd
ls -F
ls -lh inputs/ logs/ reports/

pwd identifies the current directory. ls -F marks directories with a trailing /; ls -lh also shows sizes. A zero-byte report, or a surprisingly small log, deserves investigation. To check modification times, use ls -lt reports/. A recent timestamp is a clue, not proof that a run finished successfully.

If you have a Linux terminal, the following creates illustrative files, not tool-generated signoff results. Run it only in a scratch location where pd-inspect-demo does not already contain work you need: > overwrites files of the same name.

mkdir -p pd-inspect-demo/inputs pd-inspect-demo/logs \
  pd-inspect-demo/reports/func_slow pd-inspect-demo/reports/func_fast
cd pd-inspect-demo

cat > inputs/top.sdc <<'EOF'
create_clock -name core_clk -period 1.0 [get_ports clk]
EOF

cat > logs/place.log <<'EOF'
INFO: Reading inputs/top.sdc
INFO: Scenario func_slow active
WARNING: 1 unconstrained input port
INFO: Placement completed
ERROR: Could not save checkpoint
INFO: Check output directory permissions
EOF

cat > reports/func_slow/timing.rpt <<'EOF'
Scenario: func_slow
Mode: functional
Corner: SS_lowV_RCmax
Startpoint: u_launch_reg/Q
Endpoint: u_capture_reg/D
slack (VIOLATED) -0.12
EOF

cat > reports/func_fast/timing.rpt <<'EOF'
Scenario: func_fast
Mode: functional
Corner: FF_highV_RCmin
Startpoint: u_launch_reg/Q
Endpoint: u_capture_reg/D
slack (MET) 0.05
EOF

From inside pd-inspect-demo, inputs/top.sdc is a relative path. Commands using it will refer to this scratch file, not to an SDC elsewhere on the machine.

Inspect a file without flooding the terminal

The best viewing command depends on your question. head -n 5 inputs/top.sdc shows the beginning of a file; tail -n 10 logs/place.log shows its end. wc -l logs/place.log reports/*/timing.rpt gives line counts and, because it receives several files, a total. Line count can reveal an unexpectedly empty output, but cannot establish whether its contents are correct.

For a long log, use less logs/place.log. It displays one screen at a time: press Space to move forward, b to move back, type /checkpoint and press Enter to search, and press q to exit. The selected BlueMonkey 4n6 video demonstrates less, head, and tail on a long system log; use your design log instead of the system path shown.

For a currently growing text log, tail -f logs/place.log follows new lines; press Ctrl+C to stop. Do not confuse a line saying “Placement completed” with completion of the whole run: the example log subsequently reports that it could not save a checkpoint.

The Software Carpentry reading shows how to combine small inspection commands. Read its discussion of redirection carefully before using > on project files.

For example, head -n 5 logs/place.log | tail -n 2 prints lines four and five of the five-line output from head. The source log is unchanged. You can assemble such pipelines one command at a time and inspect each intermediate result rather than guessing what a long pipeline does.

Find the relevant line—and keep its context

grep searches inside text, printing lines that match a pattern. That makes it useful for locating warnings, instance names, scenario labels, and slack lines. Corey Schafer’s demonstration introduces the options you will use most often.

Try these searches in the scratch workspace:

grep -nF 'create_clock' inputs/top.sdc
grep -nEi 'warning|error|unresolved' logs/place.log
grep -n -C 2 -E 'WARNING|ERROR' logs/place.log

The first command finds literal text and prefixes its line number. -F is valuable when searching for an exact net, cell, or filename: characters such as . and [ can have special meanings in regular-expression patterns. The second command ignores case (-i) and uses -E to treat | as “or.” The third includes two lines on either side of each match (-C 2). Here that context shows that placement completed but checkpoint saving failed. A bare count of errors would not convey that sequence.

A search yielding no printed lines means no match in the files you searched. It does not prove there are no problems: you may have the wrong path, different message wording, or a problem recorded only in another report. In scripts, grep also uses a nonzero exit status when it finds no match, which is distinct from judging an entire design run successful.

Find the right reports before interpreting them

find locates file paths; grep locates matching lines within files. Read the focused part of Software Carpentry’s “Finding Things” for that distinction and for the important quoting rule around *.rpt.

Now locate the sample reports and inspect their identifying lines:

find reports -type f -name '*.rpt'
grep -nH -E '^[[:space:]]*(Scenario|Mode|Corner|Startpoint|Endpoint|slack)' \
  reports/*/timing.rpt

find searches beneath reports/; -type f excludes directories. The quoted '*.rpt' is a filename pattern for find. In the second command, reports/*/timing.rpt is deliberately unquoted: the shell expands it into the two report paths before grep runs. -H prints each filename, while -n prints line numbers. The pattern selects the headers and slack lines in these simple sample reports; real tool reports may indent or label them differently, so adapt the search to the format you actually see.

The output should make an important distinction visible. The func_slow report identifies a functional mode and an SS_lowV_RCmax corner and shows negative slack. The func_fast report describes a different corner and shows positive slack. Positive slack in one scenario does not cancel negative slack in another. Conversely, the scenario name alone is not enough: inspect the report header and the run log to check what was actually analyzed.

For a large project, narrow searches to the appropriate directory or known text-file pattern. Recursively searching an entire workspace may crawl through binary databases as well as logs. Commands such as grep and less are for text; an extension alone does not guarantee that a file is readable text. When unsure, file path/to/file can offer a first indication. If a text log is gzip-compressed as .log.gz, use a gzip-aware viewer or search command rather than treating it as an ordinary log.

Key takeaways

A reliable inspection habit is to locate the file, check its identity, inspect its beginning or end, then search for specific lines with enough context to interpret them. Use pwd, ls, and find for paths; less, head, tail, and wc for initial inspection; and grep for targeted text searches. Keep the filename and scenario attached to any timing result, and treat a log message or timestamp as evidence to investigate—not as automatic proof of a clean run.

Next, you’ll move inside ICC2 and query design objects—cells, pins, ports, and nets—rather than only the files and reports surrounding the tool.