Reading RTL and Building a File List

Part II · Module 21 · Chapter 21.2 · Reading RTL and Building a File List

The first phase of a synthesis run is reading the sources, and almost all the work is deciding which sources. That decision is pure Tcl — glob, lsort, lappend, file isfile — which makes this the most Part I chapter in Module 21.

It is also the phase where a mistake is cheapest to make and most expensive to notice.

1. A bare glob takes too much

foreach f [lsort [glob -nocomplain [file join $here rtl *]]] {
    puts "    [file tail $f]"
}

=== 1. glob picks up everything, including what you did not want ===
    alu.v
    cpu_top.v
    fifo.v
    pkg_defs.vh

Four files, and only three are sources. pkg_defs.vh is a header — macro definitions meant to be included, not compiled as a design file.

Handing a header to the source reader is a real and common mistake. Depending on the tool it is an error, a warning nobody reads, or a silently empty compilation unit.

2. Restrict the pattern

set files [lsort [glob -nocomplain [file join $here rtl *.v]]]

=== 2. restrict the pattern ===
    alu.v
    cpu_top.v
    fifo.v
    -> 3 source file(s)

Three decisions in that one line, each worth keeping:

• -nocomplain so an empty directory returns an empty list rather than raising. You want your error message, not glob's — §4.
• lsort so the order is deterministic. Without it the order is filesystem order, which differs between machines and makes two runs incomparable.
• file join rather than string concatenation, per Chapter 12.10.

3. When a glob is the wrong tool

=== 3. an explicit list beats a glob when order matters ===
    alu.v
    fifo.v
    cpu_top.v

A glob answers "what is in this directory", which is not always the question. Use an explicit list when:

• Order matters. Some languages and tools require a definition before its use.
• The directory holds more than this design — several blocks, or files for another configuration.
• The list is the specification. A file list under version control is a statement about what the design is; a glob is a statement about what happens to be on disk.

The usual compromise is a file list file — one path per line, version-controlled — read with the Part I file commands:

proc read_filelist {path} {
    set fp [open $path r]
    set files {}
    while {[gets $fp line] >= 0} {
        set line [string trim $line]
        if {$line eq "" || [string index $line 0] eq "#"} { continue }
        lappend files $line
    }
    close $fp
    return $files
}

Comments and blank lines skipped — the same shape as the parser in Chapter 15.9. Now the list is reviewable, diffable, and a deliberate statement rather than a side effect of what is in a directory.

4. Check before you read

The registry purpose's clause, and the most valuable four lines in the phase:

proc check_files {files} {
    set missing {}
    foreach f $files { if {![file isfile $f]} { lappend missing $f } }
    if {[llength $missing]} {
        error "[llength $missing] source file(s) missing: [join $missing {, }]" \
              {} [list FLIST MISSING $missing]
    }
    return [llength $files]
}

=== 4. check every file exists BEFORE reading any of them ===
    all present : 3 file(s)
    with a typo : 1
    1 source file(s) missing: /private/tmp/m21/proj/rtl/nosuch.v

file isfile rather than file exists is deliberate — Chapter 14.11 §2. A directory passes file exists, and a directory in a source list is a mistake you want caught here rather than inside the tool's reader.

5. Handing the list over

With a checked list, the read itself is one line:

read_verilog $files        ;# a tool command, not Tcl

Most tools accept a list, which is why building a proper Tcl list rather than a string matters — Chapter 14.8 §2. A string built with append breaks on the first path containing a space.

If your tool reads one file at a time, loop — and count, so the number can be checked:

set n 0
foreach f $files {
    read_verilog $f
    incr n
}
puts "  read $n source file(s)"

That count is worth printing either way. A log line saying read 3 source file(s) on a design with forty is a problem somebody notices.

6. What a wrong file list produces

Worth being concrete, because the symptom is far from the cause.

A missing file means a missing module. At elaboration the tool finds a reference it cannot resolve and — depending on settings — either errors, or creates an empty black box and carries on. The black box has no timing, no area and no logic, so the design appears smaller and faster than it is. That is Chapter 21.5's subject.

An extra file can be worse: a stale copy of a module, or the same module defined twice. Which definition wins may depend on read order, which is why §2's lsort matters.

A header read as a source produces an empty unit or an error, depending on the tool.

All three are prevented by the same thing: a file list that is a deliberate, checked, version-controlled statement rather than whatever glob returned.

7. Exercises

Exercise 1. Why does a bare glob * on an RTL directory take too much?

Exercise 2. Name the three things [lsort [glob -nocomplain [file join ...]]] gets right.

Exercise 3. Why is -nocomplain dangerous without a following check?

Exercise 4. Give two situations where an explicit file list beats a glob.

Exercise 5. Why check every file before reading any, rather than as you go?

Exercise 6. Why file isfile rather than file exists?

Exercise 7. A source file is missing from the list. What does the tool produce, and why is the design misleading?