Reading the Netlist

Part II · Module 22 · Chapter 22.2 · Reading the Netlist

Timing analysis runs on a gate-level netlist. Loading it is one command, and the interesting question is the one the registry purpose asks: is this the netlist the current synthesis run produced?

Getting that wrong produces a perfectly valid timing report for a design that no longer exists.

1. The read

read_verilog $NETLIST        ;# a tool command
link_design  $TOP            ;# resolve it against the libraries

Two steps, and the second matters: linking resolves every cell instance against the libraries from Chapter 22.3. An unresolved cell at this point is the same black box as Chapter 21.5 §2 — no timing, no area, and paths through it simply absent from the analysis.

So the first check is the same one:

if {[sizeof_collection [get_cells -hierarchical *]] == 0} {
    error "netlist linked to nothing" {} {STA EMPTY}
}

2. Which netlist is this?

A timing session is usually started hours or days after the synthesis run that produced its input, often by a different person, sometimes from a path somebody typed. The netlist file does not say where it came from.

Unless synthesis wrote it down — which Chapter 21.9 §4 did.

3. Reading the provenance back

proc read_provenance {path} {
    set d [dict create]
    if {![file isfile $path]} { return $d }
    set fp [open $path r]
    while {[gets $fp line] >= 0} {
        set line [string trim $line]
        if {$line eq "" || [string index $line 0] eq "#"} { continue }
        dict set d [lindex $line 0] [lrange $line 1 end]
    }
    close $fp
    return $d
}

set prov [read_provenance [file join [file dirname $NETLIST] PROVENANCE.txt]]
foreach k {top corner libraries sdc source_count} {
    puts [format "    %-14s %s" $k [dict get $prov $k]]
}

=== 1. what produced the netlist we are about to analyse ===
    top            cpu_top
    corner         slow
    libraries      slow.lib,mem_slow.lib
    sdc            constraints.sdc
    source_count   3

That is the file Module 21 wrote, read back by the parser from 21.9 §5. Four things it now tells you before any timing command runs:

• The top matches what this session expects.
• The corner synthesis targeted — which may legitimately differ from the one being analysed, but you should know.
• The libraries synthesis used, which Chapter 22.3 will compare against.
• The SDC, which Chapter 22.4 will compare against.

4. The freshness check

Provenance says what the netlist claims. File times say whether anything has changed since.

proc newer_than {a b} { return [expr {[file mtime $a] >= [file mtime $b]}] }

puts [format "    netlist mtime : %s" [clock format [file mtime $netlist] -format %H:%M:%S]]
puts [format "    sdc     mtime : %s" [clock format [file mtime $sdc] -format %H:%M:%S]]
puts [format "    netlist is newer than the sdc: %s" \
    [expr {[newer_than $netlist $sdc] ? "yes" : "NO — the SDC changed after synthesis"}]]

=== 2. is the netlist newer than the sources it claims to be built from? ===
    netlist mtime : 19:58:43
    sdc     mtime : 19:58:43
    netlist is newer than the sdc: yes

Now edit the constraints, as somebody does between a synthesis run and a timing run:

=== 2. is the netlist newer than the sources it claims to be built from? ===
    netlist mtime : 19:58:43
    sdc     mtime : 19:58:58
    netlist is newer than the sdc: NO — the SDC changed after synthesis

5. What to compare

Three comparisons worth making, in increasing order of effort:

File times. Is anything the session reads newer than the netlist? Cheap, and catches the common case.

Provenance against the session. Does the SDC named in the provenance match the one this session is about to read? A different filename is a different question being asked.

Content. A checksum of the SDC recorded at synthesis, compared against the file now. This catches an edit that did not change the filename — which file times also catch, unless somebody restored an mtime.

The first two are a handful of lines and catch nearly everything. The third is worth adding for a signoff flow specifically.

6. When a mismatch is legitimate

Not every difference is a bug, and the script should not pretend otherwise.

• Timing a netlist at a different corner than synthesis used is normal — that is what Chapter 22.8 is about.
• Signoff constraints differing from synthesis constraints is also normal, and Chapter 22.4 §5 explains why.
• A netlist from an earlier run, analysed deliberately for comparison, is fine.

So these checks should report loudly and let the caller decide, rather than refusing. The distinction worth preserving: a difference you declared is a decision; a difference you did not notice is a bug.

if {$::SIGNOFF} {
    # at signoff, a stale input is fatal
    if {![newer_than $NETLIST $SDC]} { error "stale netlist" {} {STA STALE} }
} else {
    puts stderr "  WARNING netlist older than the SDC"
}

7. Exercises

Exercise 1. What does linking do, and what does an unresolved cell produce?

Exercise 2. Why can the netlist file not tell you where it came from?

Exercise 3. What four things does the provenance record establish before any timing command runs?

Exercise 4. An SDC is edited after synthesis and timing is run. What happens if the constraint got looser?

Exercise 5. Why is that worse than if it got tighter?

Exercise 6. Name the three comparisons, in increasing order of effort.

Exercise 7. Give two cases where a netlist–session mismatch is legitimate.