Tcl · Module 19

Selecting Cells by Pattern

A pattern that matches too much and a pattern that matches too little look identical from the outside. Before a script changes anything, it should say what it is about to change.

Intermediate16 min readtcledapart-iipatternsecoqueriesvalidation

Part II · Module 19 · Chapter 19.5 · Selecting Cells by Pattern

Most scripts that change a design start by selecting the cells to change. An ECO, a sizing pass, a don't-touch marking, a report scoped to one block — each begins with a pattern.

Chapter 18.5 taught the command. This chapter is about the step between selecting and acting, because a pattern that is wrong does not announce itself, and the cost of acting on a wrong selection is much higher than the cost of reporting one.

1. What patterns actually catch

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

=== patterns, and what each one actually caught ===
  get_cells *                               3  u_core u_mem u_io
  get_cells -hierarchical *                 9  u_core u_core/u_ctrl u_core/u_alu u_core/u_pipe_reg u_mem u_mem/u_bank0 u_mem/u_bank1 u_io u_io/u_sync
  get_cells -hierarchical u_core/*          3  u_core/u_ctrl u_core/u_alu u_core/u_pipe_reg
  get_cells -hierarchical *bank*            2  u_mem/u_bank0 u_mem/u_bank1
  get_cells -hierarchical *_reg*            1  u_core/u_pipe_reg
  get_cells -hierarchical *u_*              9  u_core u_core/u_ctrl u_core/u_alu u_core/u_pipe_reg u_mem u_mem/u_bank0 u_mem/u_bank1 u_io u_io/u_sync

Six patterns. Two of them are the ones to learn from.

2. Over-matching

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

  get_cells -hierarchical *u_*              9

Every cell in the design. Every instance here begins with u_, which is a near-universal convention — so *u_* is not a selection at all.

3. Under-matching

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

  get_cells -hierarchical *_reg*            1

One cell. The design has six sequential cells; five of them are not named *_reg*:

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

=== by what they ARE, not what they are called ===
  filter is_sequential == true              6  u_core/u_ctrl u_core/u_pipe_reg u_mem u_mem/u_bank0 u_mem/u_bank1 u_io/u_sync
  filter ref_name == DFF                    3  u_core/u_ctrl u_core/u_pipe_reg u_io/u_sync
  filter ref_name == RAM                    2  u_mem/u_bank0 u_mem/u_bank1

Under-matching is quieter than over-matching: the script runs, does something to one cell, reports success, and the other five never get whatever it was.

4. The patterns that are reliable

Not all patterns are guesses. The reliable ones describe structure:

Pattern	Reliable?	Why
`u_core/*`	yes	a hierarchy path — structural fact
`u_mem/u_bank0`	yes	one named instance
`bank`	usually	a distinctive, deliberate substring
`_reg`	no	a naming convention, not a property
`u_`	no	matches everything

The rule from Chapter 18.5 §5: a path is structure, a suffix is a convention. Hierarchy comes from how the design was built; a name suffix comes from whoever typed it.

And when you want a property — sequential, a particular library cell, a size — use the attribute, as the three filters above do. That is Chapter 18.7.

5. How this differs from 18.5

Chapter 18.5 §4 made the case for attributes over names. This chapter is not repeating it.

The point here is narrower and applies whatever you selected by: before a script acts, it should state what it is about to act on. An attribute filter can also be wrong — a misspelled attribute name returns empty with no error, as Chapter 18.7 §6 showed. The preview is not a substitute for choosing the right selector; it is the check that catches the cases where you chose well and still got it wrong.

6. Preview before you act

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

proc preview {label h} {
    set n [sizeof_collection $h]
    puts "  $label matched $n"
    if {$n == 0} { puts "    -> nothing to do; is the pattern right?" ; return 0 }
    if {$n > 4}  { puts "    -> more than expected; showing the first 3: [lrange [collection_to_list $h] 0 2]" }
    return $n
}

preview {*_reg*} [get_cells -hierarchical *_reg*]
preview {*u_*}   [get_cells -hierarchical *u_*]
preview {*nope*} [get_cells -hierarchical *nope*]

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

=== check before you act ===
  *_reg* matched 1
  *u_* matched 9
    -> more than expected; showing the first 3: u_core u_core/u_ctrl u_core/u_alu
  *nope* matched 0
    -> nothing to do; is the pattern right?

Three cases, three different messages. Four things that helper gets right:

It always prints the count, even when nothing is wrong. A number in the log is what makes two runs comparable and what somebody notices when it changes.
Zero and "more than expected" get different messages, because they are different bugs — Chapter 18.8 and §2 here.
It shows a sample rather than everything. On nine thousand matches you want three names and a count, not nine thousand lines.
It returns the count, so the caller decides whether to proceed.

7. For anything that changes the design

The full shape, when the next step is an ECO rather than a report:

Azvya Education Pvt. Ltd.VLSI Mentor

Snippet

proc select_for_eco {pattern expected} {
    set c [get_cells -hierarchical $pattern]
    set n [sizeof_collection $c]
    if {$n == 0} {
        error "pattern '$pattern' matched nothing" {} [list ECO NOMATCH $pattern]
    }
    if {$n != $expected} {
        error "pattern '$pattern' matched $n cells, expected $expected" \
              {} [list ECO COUNT $n]
    }
    puts "  '$pattern' -> $n cell(s), as expected"
    return $c
}

set targets [select_for_eco *bank* 2]

It refuses to proceed on a surprise. For a report, printing the count is enough. For a change, the count should be asserted — because the cost of acting on the wrong set is not symmetrical with the cost of stopping.

Three further habits for ECO scripts, all from Part I:

Dry run first. A -dry-run option (Chapter 15.3) that previews and exits without changing anything.
Log what you changed, by full name, so the change is reviewable and reversible.
Honest exit status (Chapter 15.4), so a wrapper stops instead of continuing to the next stage.

8. Exercises

Exercise 1. Why is over-matching more dangerous than under-matching for an ECO?

Exercise 2. *u_* matched every cell. What made that pattern useless?

Exercise 3. *_reg* matched 1 of 6 sequential cells. What should have been used?

Exercise 4. Which kinds of pattern are reliable, and why?

Exercise 5. This chapter and 18.5 both discuss names versus attributes. What is the distinct point here?

Exercise 6. Name two things the preview helper gets right.

Exercise 7. Why assert the count before an ECO but only print it for a report?

Answers.

1. Because it still looks like a successful selection — a non-empty collection, a loop that runs, commands that succeed — so the script changes far more than intended, and undoing an ECO is not automatic.

2. Every instance in the design begins with u_, a near-universal convention, so the pattern selected everything. Any pattern whose match count equals the total is suspect.

3. The is_sequential attribute via filter_collection — a property the tool knows, rather than a naming convention five of the six cells do not follow.

4. Hierarchy paths and exact instance names, because they describe structure — how the design was actually built. Name suffixes describe a convention somebody chose and may not have followed.

5. 18.5 argues for selecting by attribute instead of name. This chapter's point applies whatever you selected by: state what you are about to act on before acting, because an attribute filter can be wrong too.

6. Any two of: it always prints the count; it gives different messages for zero and for too many; it shows a sample rather than everything; and it returns the count so the caller decides.

7. Because the costs are not symmetrical. A report with the wrong scope is embarrassing; an ECO applied to the wrong set is a change somebody must find and undo.

Remember.

Over-matching still looks like a successful selection — and for an ECO that is a change you must undo by hand.
Distrust patterns made of common substrings, and any match count equal to the total.
Under-matching is quieter: the script succeeds, having done the work to a fraction of the targets.
A path is structure; a suffix is a convention. Hierarchy paths and exact names are reliable.
For a property, use the attribute, not the name.
Preview before acting, whatever you selected by — an attribute filter can be wrong too.
Always print the count, give zero and too-many different messages, and show a sample rather than everything.
Assert the expected count before an ECO; printing it is enough for a report.
Offer a dry run, log what changed, and exit honestly.
Never collection_to_list a large match to preview it — count with sizeof_collection, sample with lrange.

Where this fits

Part of the Tcl curriculum.