VCS, Xcelium, and Questa Script Updates

Part IV · Module 10 · Chapter 10.1 · VCS, Xcelium, and Questa Script Updates

1. What a Run Script Looks Like

cat -n sim/run.sh

     1	#!/bin/sh
     2	# VCS
     3	vcs -full64 -sverilog -timescale=1ns/1ps -f filelists/top.f -o simv
     4	./simv +UVM_TESTNAME=old_test +UVM_VERBOSITY=UVM_LOW -l sim.log
     5	# Xcelium
     6	xrun -64bit -sv -f filelists/top.f +UVM_TESTNAME=old_test -l sim.log
     7	# a comment mentioning -l sim.log that must NOT change
     8	echo "logs go to sim.log by default"

Eight lines, and -l sim.log appears four times: on the VCS simulation line, on the Xcelium line, in a comment, and inside an echoed string. Only some of those are options.

This is the shape that makes run scripts worth their own chapter. Chapter 9.1's filelist had one kind of line; this has several, and they are not interchangeable.

2. Not Every Edit Needs an Anchor

Worth establishing before the cautions, or the chapter reads as blanket paranoia.

Swapping the test name is legitimately file-wide — every occurrence is a real invocation and all of them should change:

sed -n 's/+UVM_TESTNAME=old_test/+UVM_TESTNAME=new_test/p' sim/run.sh

./simv +UVM_TESTNAME=new_test +UVM_VERBOSITY=UVM_LOW -l sim.log
xrun -64bit -sv -f filelists/top.f +UVM_TESTNAME=new_test -l sim.log

Two lines, both correct. Count them first, as Chapter 7.2 requires:

sed -n 's/+UVM_TESTNAME=old_test/&/p' sim/run.sh | wc -l

       2

Two is the number you expected, so this edit needs no address. The pattern is specific enough to be its own anchor — +UVM_TESTNAME=old_test cannot plausibly appear anywhere it should not.

3. When the Anchor Is the Whole Point

Now retarget the log file. The registered command anchors to the Xcelium invocation:

sed -n '/^xrun /s|-l sim.log|-l logs/sim.log|p' sim/run.sh

xrun -64bit -sv -f filelists/top.f +UVM_TESTNAME=old_test -l logs/sim.log

One line. Now the same substitution with no address, shown against the whole file:

sed 's|-l sim.log|-l logs/sim.log|' sim/run.sh

#!/bin/sh
# VCS
vcs -full64 -sverilog -timescale=1ns/1ps -f filelists/top.f -o simv
./simv +UVM_TESTNAME=old_test +UVM_VERBOSITY=UVM_LOW -l logs/sim.log
# Xcelium
xrun -64bit -sv -f filelists/top.f +UVM_TESTNAME=old_test -l logs/sim.log
# a comment mentioning -l logs/sim.log that must NOT change
echo "logs go to sim.log by default"

Counted:

sed -n '/^xrun /s|-l sim.log|&|p' sim/run.sh | wc -l

       1

sed -n 's|-l sim.log|&|p' sim/run.sh | wc -l

       3

One versus three. The two extras are line 4 — a different tool's log option — and line 7, a comment.

Line 4 is the interesting one. If the task is "move Xcelium's log", changing VCS's too is wrong; if the task is "move both", the command should say so. Either way the unanchored version does not express an intention, it expresses a text match.

4. Adding an Option to an Existing One

The third registered example adds a Questa option after one that is already there:

cat -n sim/run.do

     1	vlog -sv -f filelists/top.f
     2	vsim -voptargs=+acc work.tb -do "run -all"
     3	quit -f

sed -n '/^vsim /s/-voptargs=+acc/-voptargs=+acc -onfinish stop/p' sim/run.do

vsim -voptargs=+acc -onfinish stop work.tb -do "run -all"

The new option landed immediately after the matched one, and work.tb and the -do string are untouched.

Two things about that command are deliberate. The /^vsim / address means a vlog line mentioning the same option would be left alone. And the replacement restates the matched text — which Chapter 3.3 showed can be written as & instead:

   sed '/^vsim /s/-voptargs=+acc/& -onfinish stop/' sim/run.do

Shorter, and the matched text exists once rather than twice, so the two copies cannot drift apart.

5. The + Trap, in Its Second Form

Simulator options are full of + — +UVM_TESTNAME, +acc, +UVM_VERBOSITY, +define+. Chapter 9.1 established that basic mode treats + as a literal, and that -E does not. What this chapter adds is that -E fails two different ways depending on where the + sits, and only one of them tells you.

Chapter 9.1's case was a leading +:

   sed -E -n '/+incdir+/p' filelists/top.f
   -> RE error: repetition-operator operand invalid, exit 1

Loud, because a + at the start of a pattern has nothing to repeat. Now the Questa option, where the + follows a character:

sed -n '/-voptargs=+acc/p' sim/run.do

vsim -voptargs=+acc work.tb -do "run -all"

Basic mode matches it. Under -E:

sed -E -n '/-voptargs=+acc/p' sim/run.do

Nothing. Exit status 0.

Here =+ is a perfectly valid quantifier — "one or more =" — so the pattern means "-voptargs, then one or more equals signs, then acc". The real line has = followed by +, not by acc, so there is no match and nothing is wrong as far as sed is concerned.

6. A Procedure for a Script Sweep

Run scripts usually exist in numbers — one per test, per block, per regression. The procedure is Chapter 7.2's with the anchoring rule folded in:

   1. grep -rn 'old_test' sim/              what exists, and where
   2. … | wc -l                             the number to verify against
   3. sed -n '/^tool /s|old|new|p' one.sh    dry run, on ONE file, anchored
   4. git status --short                     tree clean before writing
   5. grep -rl --null 'old_test' sim/ | xargs -0 sed -i '' '…'
   6. git diff                               read it — every line
   7. grep -rn 'old_test' sim/               expect nothing

Step 6 matters more for run scripts than for filelists, because a run script is executable. A filelist with a wrong path fails loudly at compile time; a run script with a wrong option may run, produce output, and be wrong in a way that only shows up in results.

The -i spelling is -i '' on BSD/macOS and -i on GNU — Chapter 7.1 — and --null is written in full because Chapter 8.3 measured -Z meaning something else on two of three greps.

7. Think It Through

1. When does an edit need an address and when is it fine without one?

When the pattern is specific enough to be its own anchor, no address is needed — +UVM_TESTNAME=old_test matched two lines and both were correct. When the same text appears on more than one kind of line, the address is what distinguishes them: -l sim.log matched three lines and only one was the target.

2. Your log retarget changed a comment. Does that matter?

Directly, no — a comment does not affect execution. Indirectly, yes: it is now documentation describing the old arrangement with a new path spliced into it, which is worse than either. Chapter 9.3 ranked this as the mildest of the silent boundaries, and the anchor prevents it for free.

3. sed -E -n '/-voptargs=+acc/p' run.do prints nothing but the option is there. Why?

Under -E, =+ means "one or more =" rather than the literal text =+. The pattern no longer describes the option. Drop -E — basic mode treats + literally and is the right default for run scripts — or escape it as =\+acc.

4. Write a command that adds -sv_lib ./dpi to the xrun line only, without retyping the existing options.

sed '/^xrun /s|$| -sv_lib ./dpi|' sim/run.sh appends at end of line, or anchor it to an existing option with &: sed '/^xrun /s|-64bit|& -sv_lib ./dpi|'. The second places it deterministically; the first is simpler but puts the option after whatever happens to be last, which can matter for tools that are order-sensitive about file arguments.

5. Why is step 6 of the procedure more important for a run script than for a filelist?

Because a run script is executed rather than parsed. A broken filelist fails at compile with a missing file; a run script with a subtly wrong option often runs to completion and produces results that are wrong rather than absent — a verbosity set too low, a log in the wrong place, a plusarg the tool silently ignores.

6. A tool release renames an option across 40 run scripts. What is the first command you run?

grep -rn 'old-option' sim/, to find out how many scripts and how many lines, and on which kinds of line. Chapter 7.2's count comes before anything else, and in this case it also tells you whether the option appears in comments or help text — which is what decides whether the substitution needs an address.

8. Summary

• A run script has several kinds of line — different tools' invocations, comments, echoed strings — and the same option text often appears in more than one.
• Anchor a substitution to the invocation line that owns it. /^xrun /s|-l sim.log|…| changed 1 line; the unanchored version changed 3, including a comment and another tool's option.
• Not every edit needs an address. +UVM_TESTNAME=old_test is specific enough to anchor itself — 2 lines, both correct.
• An echoed string survived by luck, not design: it said sim.log but not -l sim.log. An anchor removes the luck.
• Use & to add an option next to an existing one — s/-voptargs=+acc/& -onfinish stop/ states the matched text once.
• Stay in basic mode for run scripts. + is everywhere in simulator options, and -E breaks it two different ways: a leading + is an error (exit 1), while a + after a character is a valid quantifier that silently matches nothing (exit 0).
• Read the whole diff. A run script is executed, not parsed, so a wrong option can produce results rather than an error.

The script tells the simulator what to do. The next problem is what the simulator writes back — thousands of lines in which the handful you need are mixed with timestamps, hierarchy paths and file positions that differ on every run. Chapter 10.2 — UVM Log Filtering and Normalization reduces a log to the lines a triage needs and makes two runs comparable.