Tcl · Module 25

Waveform Setup Scripts

A waveform you have to assemble by clicking is a waveform you assemble differently every time. Script it from the design's own signal list, and make every exclusion a reason you wrote down.

Intermediate20 min readtcledapart-iisimulationwaveformdebug

Part II · Module 25 · Chapter 25.3 · Waveform Setup Scripts

A test fails at three in the morning. Someone opens the waveform, and then spends ten minutes finding the signals that matter, in an order that makes sense, with radixes that are readable.

They do that every time, slightly differently, and the setup is gone when the window closes.

1. Why this is a scripting problem

The obvious objection is that a GUI remembers your layout. Sometimes it does — and the layout is still the wrong artefact, for three reasons.

It is per-person. Your grouping is not in the repository, so the next engineer starts from nothing.

It does not travel with the design. Add a port, rename a block, and a saved layout silently refers to signals that no longer exist.

It cannot be generated. The useful waveform for a FIFO is "every port, grouped by role, plus the pointers" — a rule, applied to whatever signals the design currently has. A rule is a script. A saved layout is the output of running one by hand, once.

2. Start from what the simulation actually has

This chapter does not invent a signal list. It reads the one a real run produced.

Icarus is installed on the machine these chapters were verified on (Chapter 25.1 §1), so the FIFO testbench was run with $dumpvars(0, fifo_tb) and the resulting VCD header carries the real hierarchy the simulator saw. The add wave side of the chapter uses the same mock shell as Chapter 25.2 — but the signals below are real.

A VCD header is a small nested format: $scope descends, $upscope ascends, $var declares a signal.

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

proc vcd_signals {path} {
    set fh [open $path r]
    set scope {} ; set sigs {}
    while {[gets $fh line] >= 0} {
        set line [string trim $line]
        if {[regexp {^\$scope\s+\w+\s+(\S+)\s+\$end} $line -> name]} {
            lappend scope $name ; continue
        }
        if {[string match {$upscope*} $line]} {
            set scope [lrange $scope 0 end-1] ; continue
        }
        if {[regexp {^\$var\s+(\S+)\s+(\d+)\s+\S+\s+(\S+)(?:\s+\[[^\]]*\])?\s+\$end} \
                 $line -> kind width name]} {
            lappend sigs [list "/[join $scope /]/$name" $kind $width]
            continue
        }
        if {[string match {$enddefinitions*} $line]} { break }
    }
    close $fh
    return $sigs
}

That is Chapter 24.1 §4's stateful parser in a different costume: a line-at-a-time loop where $scope and $upscope maintain a stack rather than a flat set of accumulators. lrange $scope 0 end-1 is how you pop in Tcl — there is no lpop in 8.5.

Note the (?:\s+\[[^\]]*\])? group: a vector's declaration carries its range ([7:0]) after the name, and a scalar's does not. Non-capturing so it does not shift the positional captures, and a negated class rather than a quantifier preference, for Chapter 24.3 §5's reason.

3. What dumping everything gives you

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

=== signals the simulation actually dumped ===
    31 signal(s) in the VCD header
    PATH                               KIND       WIDTH
    /fifo_tb/full                      wire       1
    /fifo_tb/empty                     wire       1
    /fifo_tb/dout                      wire       8
    /fifo_tb/count                     wire       3
    /fifo_tb/clk                       reg        1
    /fifo_tb/din                       reg        8
    /fifo_tb/pop                       reg        1
    /fifo_tb/push                      reg        1
    /fifo_tb/rst_n                     reg        1
    /fifo_tb/testname                  reg        256
    /fifo_tb/checks                    integer    32
    /fifo_tb/errors                    integer    32
    /fifo_tb/i                         integer    32
    /fifo_tb/pushed                    integer    32
    /fifo_tb/seed                      integer    32
    /fifo_tb/dut/clk                   wire       1
    /fifo_tb/dut/din                   wire       8
    /fifo_tb/dut/pop                   wire       1
    /fifo_tb/dut/push                  wire       1
    /fifo_tb/dut/rst_n                 wire       1
    /fifo_tb/dut/full                  wire       1
    /fifo_tb/dut/empty                 wire       1
    /fifo_tb/dut/DEPTH                 parameter  32
    /fifo_tb/dut/WIDTH                 parameter  32
    /fifo_tb/dut/count                 reg        3
    /fifo_tb/dut/dout                  reg        8
    /fifo_tb/dut/rptr                  reg        2
    /fifo_tb/dut/wptr                  reg        2
    /fifo_tb/check/what                reg        384
    /fifo_tb/check/exp                 integer    32
    /fifo_tb/check/got                 integer    32

31 signals from a design with ten ports. Look at what is in there:

DEPTH and WIDTH are parameters. They are constant for the whole simulation, so as waveforms they are flat lines carrying no information.
testname is 256 bits and check/what is 384 bits — Verilog string registers. A waveform viewer will render them as enormous hex values that change once.
checks, errors, i, pushed, seed are the testbench's own bookkeeping. Useful in a log, meaningless as traces.
check/what, check/exp, check/got are locals of a task, which exist only while the task is executing and are stale the rest of the time.

So "dump everything and look at it" is not a strategy. It is 31 traces of which roughly ten are the design.

4. Select, with the reason written down

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

set RULES {
    {parameter   {a parameter never changes}}
    {wide        {too wide to read as a waveform}}
    {bookkeeping {testbench bookkeeping, not design state}}
    {tasklocal   {a task local, not a signal}}
}

proc rule_hit {rule sig} {
    set path  [lindex $sig 0]
    set kind  [lindex $sig 1]
    set width [lindex $sig 2]
    switch -- $rule {
        parameter   { return [expr {$kind eq "parameter"}] }
        wide        { return [expr {$width > 64}] }
        bookkeeping { return [expr {$kind eq "integer"}] }
        tasklocal   { return [regexp {/check/} $path] }
    }
    return 0
}

The rules are data, each paired with the sentence that justifies it. That is deliberate: a filter written as a chain of anonymous ifs accumulates exclusions nobody can account for, and six months later no one knows whether a missing signal is filtered on purpose.

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

=== every rule, with what it actually caught ===
    parameter     2  a parameter never changes
    wide          2  too wide to read as a waveform
    bookkeeping   7  testbench bookkeeping, not design state
    tasklocal     0  a task local, not a signal
    kept         20  of 31 dumped

5. The rule that fired zero times

tasklocal 0. One of the four rules caught nothing at all.

That is not harmless, and it is not obvious. The first version of this report printed only categories that had members — so the tasklocal line was simply absent, and absence in a report that omits empty categories looks exactly like a rule doing its job quietly.

Printing every rule with its count is what made it visible. And the question it raises is which of two things is true: the rule is unnecessary, or it is shadowed by an earlier rule. Those have different fixes, so the next step is to probe one signal the rule was written for:

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

=== the rule that fired zero times ===
    'tasklocal' caught nothing — shadowed by an earlier rule or unnecessary
    /fifo_tb/check/got is matched by:
      bookkeeping
      tasklocal

Both, with bookkeeping first. So the rule is correct and shadowed — every task local in this design is also an integer or over 64 bits, so an earlier rule always claims it.

Which means the rule is not wrong, it is untested: it would matter for a task local that is a plain reg [3:0], and this design has none. Removing it would be wrong; keeping it without knowing it has never run is how a filter quietly stops working.

The general form, and it is worth carrying out of this chapter:

A classification rule that fires zero times is either unnecessary or shadowed, and a report that omits empty categories cannot tell you which. Print every rule's count, including the zeros, and when one reads zero, probe a case it was written for and see which rule claims it first.

This is the same hazard as a monitor that never triggers, and the same cure: a check you have never seen fire is a check you do not know you have.

6. Group by role, not by hierarchy

Twenty signals is still too many to read as a flat list, and the fix is grouping. The useful grouping is by role, which a path and a kind are usually enough to derive:

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

proc group_for {path} {
    if {[regexp {/(clk|rst_n)$} $path]}                    { return clock-reset }
    if {[regexp {/dut/} $path]} {
        if {[regexp {/(wptr|rptr|count)$} $path]}          { return dut-internal }
        return dut-port
    }
    if {[regexp {/(push|pop|full|empty)$} $path]}          { return handshake }
    return testbench
}

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

=== the wave script this generates ===
    group 'clock-reset'
      /fifo_tb/clk
      /fifo_tb/rst_n
      /fifo_tb/dut/clk
      /fifo_tb/dut/rst_n
    group 'handshake'
      /fifo_tb/full
      /fifo_tb/empty
      /fifo_tb/pop
      /fifo_tb/push
    group 'testbench'
      /fifo_tb/dout
      /fifo_tb/count
      /fifo_tb/din
    group 'dut-port'
      /fifo_tb/dut/din
      /fifo_tb/dut/pop
      /fifo_tb/dut/push
      /fifo_tb/dut/full
      /fifo_tb/dut/empty
      /fifo_tb/dut/dout
    group 'dut-internal'
      /fifo_tb/dut/count
      /fifo_tb/dut/rptr
      /fifo_tb/dut/wptr
    20 signal(s), 5 group(s)

The group order is the reading order. Clock and reset first, because every timing question starts there; handshake next, because that is where a protocol bug shows; the DUT's internals last, because you only look at them once the interface tells you something is wrong. foreach g $ordered over an explicit list rather than dict keys — the order is a decision, so it is written down.

Six of those twenty signals are duplicates, and grouping does not remove them.

/fifo_tb/din and /fifo_tb/dut/din are the same wire seen from two sides of a port connection. Likewise push, pop, full, empty, clk and rst_n.

Whether that is waste or exactly what you want depends on the bug:

Debugging a connection — a port left unconnected, a swapped pair, a width mismatch — you want both sides, because the whole point is that they might differ.
Debugging behaviour inside a working connection, you want one, and the duplicates are noise.

So "remove duplicates" is not a rule to automate; it is a flag. The honest version of this script takes -ports both|inside|outside and defaults to one, for Chapter 25.2 §3's one-script-with-options reason.

And note the limit of a path-based grouping: group_for decides from names, so a design that does not follow the naming convention it assumes gets grouped wrongly and silently — the same weakness as Chapter 19.5's pattern queries. A real tool would answer the same question from its own database rather than from a string.

7. Where the signal list should come from

The VCD route above is used here because it is what can be verified on this machine, and it has a real limitation worth stating: a VCD only contains signals that were dumped, so a selector built from one cannot offer you a signal the run did not record. It is a list of what was captured, not of what exists.

In a live session the tool answers the question directly, and those commands are vendor-specific (find signals, show, and relatives). The structure of the script does not change — query, classify, group, add wave — only the first step does. Which means the classify-and-group logic is the portable part and worth keeping separate from the query, as Chapter 17.5 argues generally.

A third route is the RTL itself, parsed for port declarations the way Chapter 21.3 pulls module names out of source. That has the opposite trade: it knows every port whether or not it was dumped, and it knows nothing about what the elaborated hierarchy actually instantiated.

8. Exercises

Exercise 1. Give three reasons a saved GUI layout is the wrong artefact.

Exercise 2. $dumpvars(0, fifo_tb) produced 31 signals for a design with ten ports. Name three categories of the surplus.

Exercise 3. Why are DEPTH and WIDTH useless as waveforms?

Exercise 4. Why pair each filter rule with a sentence?

Exercise 5. tasklocal fired zero times. What are the two possible explanations, and how did the probe distinguish them?

Exercise 6. Why was the zero invisible in the first version of the report?

Exercise 7. Should the shadowed rule be removed? Why or why not?

Exercise 8. Why is the group order written as an explicit list rather than taken from dict keys?

Exercise 9. When do you want both sides of a port connection in the waveform, and when do you not?

Exercise 10. What can a VCD-derived signal list never offer you?

Answers.

1. It is per-person and not in the repository; it does not track the design, so it silently refers to signals that have been renamed or removed; and it cannot be generated, because it is the output of applying a rule by hand once rather than the rule itself.

2. Any three of: parameters, which are constant; very wide string registers; testbench bookkeeping integers; and task locals, which are stale except while the task runs.

3. Because a parameter is constant for the whole simulation, so its trace is a flat line carrying no information.

4. Because a filter written as anonymous ifs accumulates exclusions nobody can justify later, and then a missing signal cannot be distinguished from a deliberate omission.

5. Either it is unnecessary, or it is shadowed by an earlier rule. The probe asked which rules match one task local and found that both bookkeeping and tasklocal match it, with bookkeeping tested first — so it is shadowed.

6. Because the report printed only categories that had members, so a rule with zero members produced no line at all — and an absent line looks the same as a rule working quietly.

7. No. It is correct and would matter for a task local that is a narrow reg, which this design happens not to have. But keeping it while knowing it has never fired is the point: an untested rule is not a working rule.

8. Because the order is the decision — clock and reset first, internals last — and taking it from dict keys would make the reading order an accident of insertion.

9. Both when debugging the connection itself, where the two sides differing is the bug you are looking for. One when debugging behaviour inside a working connection, where the duplicate is noise.

10. A signal the run did not dump. A VCD is a record of what was captured, not an inventory of what exists.

Remember.

A saved GUI layout is per-person, drifts from the design, and cannot be generated. The rule is the artefact; script it.
Dumping everything gives 31 traces for a ten-port design — parameters, string registers, bookkeeping integers and task locals.
Make the filter rules data, each with its justification, so an exclusion can be accounted for later.
Print every rule's count, including zeros. A report that omits empty categories hides a rule that never fires.
A rule firing zero times is unnecessary or shadowed — probe a case it was written for and see which rule claims it first.
A check you have never seen fire is a check you do not know you have.
Group by role and write the group order down — clock/reset first, internals last, because that is the reading order.
Both sides of a port connection is a flag, not a rule: both for connection bugs, one for behaviour.
A name-based grouping fails silently on a design that names things differently.
A VCD lists what was dumped, not what exists. Query the live session when you can, and keep classify-and-group separate from the query so it stays portable.

Where this fits

Part of the Tcl curriculum.