An Assertion Plan
Turn a spec into a plan of assertion rows: their kind, their owner, when they are enough, and how to bind them.
You Will Be Able To
- Turn spec sentences into plan rows, each with a fail column and a covered column.
- Sort rows into the five kinds of assertion and give each kind an owner.
- Write rules that state intent, stay quiet on legal traffic, and fill the holes a silent failure shows.
- Add rules to an existing design with
bind, without editing it.
- Lesson
- A1.9
- Time
- 25 min
- Runs on
- Verilator
- Check
- 5 questions
A team wrote 40 assertions for a read channel. All 40 passed in every regression. Then a test failed at the output, and no assertion fired.
| What went wrong | What a plan row would have said |
|---|---|
| Ten rules restated the RTL line by line | state the intent, not the code |
| Six rules never had an antecedent match | covered? = no: the rule proved nothing |
| No rule watched the stall path | a spec sentence with no row |
| Two rules fired on legal traffic and were switched off | a rule must be quiet on legal traffic |
Counting assertions says little. A plan says what each one is for, and whether it ever ran.
This lesson builds that plan for the read channel, one row at a time.
From Spec Sentences to Plan Rows
Start from the spec, not from the RTL. Each sentence that constrains behaviour becomes one row: a name, the rule in words, and two result columns.
| Row | Spec sentence | Kind | Owner | Fail? | Covered? |
|---|---|---|---|---|---|
| R1 | An offered beat stays offered until it is taken | interface | DV | ||
| R2 | rdata does not change while the beat waits | interface | DV | ||
| R3 | A read is answered within three edges | performance | DV + arch | ||
| R4 | The read engine moves from WAIT to DATA | RTL | designer | ||
| R5 | At least one stalled beat is seen | cover | DV | n/a |
The plan of the read channel. A run fills the last two columns.
Why two columns and not a "passed" column? A rule that never fails may simply never have run. The covered column counts the edges where the rule had something to check.
Five Kinds of Rows
Sort the rows by what they protect. The kind decides who writes the row, and which tests can reach it.
| Kind | Protects | Read-channel example |
|---|---|---|
| RTL (inside a module) | design intent: legal states, no deadlock, one-hot, FIFO flags | the read engine never skips DATA |
| Module interface | the protocol between two blocks | rvalid holds until rready |
| Chip function | end-to-end behaviour | a read that is retried ends up in the retry queue |
| Chip interface | pins and standard buses | no x on rdata after reset |
| Performance | latency and throughput limits | a read is answered within three edges |
The performance kind is the one teams forget. It catches an architecture problem while there is still time to change it.
A performance row is an ordinary rule with a bound. It fires when a latency goes past the limit, long before anyone measures throughput.
Who Writes Which Row
Both designers and verification engineers write assertions. They see different things, so they write different rows.
Designer
state == WAIT |=> state == DATA
Micro-architecture: internal states, counters, FIFOs. Written while the RTL is written.
Verification engineer
$rose(req) |-> ##2 rvalid
Ports and spec: interfaces, end-to-end behaviour. Written from the spec, not the RTL.
Every assumption a designer makes is a row. "My request always gets an answer in two edges" is an assumption about the next block, so it becomes an assertion.
Capture Intent, Never Copy the RTL
A rule that restates an RTL line checks that the code equals itself. It passes whatever the bug. Write what the block is for instead.
A copy of the RTL
g1 == (req1 && !last0)
Always true: the RTL says exactly this.
The intent
!(g0 && g1)
Never two grants: fails on the bug.
Two more points belong to this row of the method. Add rules while the RTL is written: they are hard to add later. And low-level rules still pay: every FIFO deserves its flag and order rules.
When Is the Plan Enough?
Three signs tell you a plan needs more rows. Each one is a check you can run.
Review the plan against the spec
Every critical spec sentence has a row. A sentence without a row is a hole.
Watch for silent failures
A test that fails at the outputs while no assertion fires shows a missing row. Add the rule that would have fired. It now guards every other test too.
Check the density
A register whose value reaches no assertion within a few edges is unwatched. Formal tools also work better on many short rules than on a few long ones.
- I/O
- Control / FSM
- Storage
- Transaction / TLM
- Data
- Rows at the ports
The request port and the rdata port are well watched.
- The hole
Nothing watches the stall pipeline. A bug there is seen only at rdata, edges later.
Read the diagram as text
- Request port: 2 rows
- Read engine FSM: 1 row
- Stall pipeline: 0 rows: a hole
- rdata port: 3 rows
- Request port → Read engine FSM: request
- Read engine FSM → Stall pipeline: beat
- Stall pipeline → rdata port: beat
Colour the block diagram by rows per block. A block with no row is the next place to add one.
Cost and Noise
The usual objection is time: "I have no time to write assertions." The answer is debug time. A rule that fires points at the edge and the block where the bug is.
The real cost is noise. A rule that fails on legal traffic gets switched off, and then it protects nothing. Write each rule exactly as loose as the spec.
The spec allows the answer one or two edges later. The strict rule fails on the second, legal, answer.
Write Once, Keep Alive Under Full Random
A rule is written once and used many times: in every test, in formal, in emulation, and on the bench's own logic. Bench code has bugs too.
Late in a project, teams blast the design with random traffic from every port at once. Scoreboards often cannot predict that traffic, so they are switched off. The assertions stay on.
Scoreboard under full random
expected = model(txn);
if (got != expected) error();
Often off: it cannot predict every collision.
Assertion under full random
req |-> ##[1:2] gnt
Always on: it needs no prediction, only the rule.
Settle the Spec in Review
Writing a rule forces a precise reading of the spec. A plan review then finds sentences that are vague, missing or in conflict.
| Spec sentence | Reading A | Reading B |
|---|---|---|
| "ack comes after req" | $rose(req) |=> ack: the next edge | $rose(req) |-> ##[1:$] ack: any later edge |
| Verdict when ack is two edges late | fails | passes |
One English sentence, two rules. The review picks one and fixes the spec text.
Adding Rules to a Design You Cannot Edit
A legacy block or a bought IP block may be closed to edits. Write its rules in a separate module, and bind attaches a copy inside every instance of the block.
- Environment
- DUT
- Property
- Step
- Structure
- The block stays as it is
No line of legacy_ctr changes.
- bind adds the rules
One bind statement puts ctr_rules inside every legacy_ctr. Its ports connect to the block's own signals.
Read the diagram as text
- tb: instantiates legacy_ctr
- legacy_ctr: unchanged RTL
- ctr_rules: written apart
- bind statement: bind legacy_ctr ctr_rules ...
- tb → legacy_ctr: instance
- bind statement → ctr_rules: names
- ctr_rules → legacy_ctr: a copy inside
Decide the bind method at the start of a project, so that rules are not half inside the RTL and half bound.
A7.1 covers bind in full: binding to a module type or to one instance, and what the bound module can see.
Try It
Three plan rows run together. R1 passes: the beat stays offered from 35 until it is taken at 55. R2 fails at 45, where the data changed while the beat waited.
R3 fails at 105: the second request, seen at 75, gets no answer in its window. hold_cov is 2, so R1 and R2 really had stalled edges to check.
Fill in the Fail? and Covered? columns of the plan for R1, R2 and R3 from this run.
t=45 R2 failed t=105 R3 failed hold_cov=2Check Yourself
Common Mistakes
Wrong Write one assertion per RTL line.
A rule that restates the code passes whatever the bug.
Fix State the intent: what must never or always happen at the block's boundary or inside it.
assert property (@(posedge clk)
g1 == (req1 && !last0)) else errors++;assert property (@(posedge clk)
!(g0 && g1)) else errors++;Wrong Read a rule that never failed as a rule that worked.
It may never have had an antecedent match.
Fix Keep a covered column beside the fail column, and count the edges where each rule had something to check.
Wrong Make a rule stricter than the spec "to be safe".
It fails on legal traffic, gets switched off, and then protects nothing.
Fix Write each rule exactly as loose as the spec. Ask in review when the spec is vague.
Wrong Leave assertion writing to the verification team.
Only the designer sees the internal states and assumptions.
Fix Designers write the micro-architecture rows as they write the RTL; verification writes the interface and chip rows.
Remember
- Every spec sentence that constrains behaviour becomes a plan row with a fail and a covered column.
- Five kinds: RTL, module interface, chip function, chip interface and performance.
- Designers write the internal rows; verification writes the port and spec rows. State intent, never copy the RTL.
- A noisy rule gets switched off; assertions stay on under full random traffic.
bindadds rules to a design without editing it.