Heartbeats: Proving the Bench Works, Window by Window
A heartbeat checks, window by window, that the parts of a bench keep making progress. Learn what it counts, what its three modes mean, and the wiring rules that decide whether it sees anything at all.
You Will Be Able To
- Explain how a heartbeat counts raises at its context component.
- Choose ALL, ANY or ONE mode for the check you need.
- Wire the objection, the context and the component list so every raise is seen.
- Stop and restart a heartbeat around reset and idle time.
- Lesson
- U17.4
- Time
- 35 min
- Runs on
- Verilator with UVM
- Check
- 4 questions
A scoreboard thread blocks at 45 ns while the driver and the monitor keep working. Objections cannot see it, because the test is still raising. A heartbeat in ALL mode reports it at the end of the first full window without it. The report names the component and its last sign of life.
- Cycle 0
The first tick only opens a window and clears the counts. Nothing is checked yet.
- Cycle 2
The window from 40 to 60 ns still holds sb's raise at 45 ns.
- Cycle 3
The window from 60 to 80 ns has none.
HBFAILnamesuvm_test_top.bench.sband its last update, 45 ns.
Measured by the example below. HBFAIL is a fatal error in uvm-core; the example demotes it so every window shows.
What a Heartbeat Counts
uvm_heartbeat watches one uvm_objection, not a phase. Each part of the bench proves progress by raising and dropping that objection when it finishes a unit of work. The heartbeat installs a callback, a uvm_heartbeat_callback, on the objection. Every raise and drop that reaches the heartbeat's context component adds one to a count kept for the component that raised.
You drive the windows with an event. set_heartbeat(e, comps) lists the components and starts watching. The first trigger of e only opens the first window and clears the counts. Every later trigger checks the window just closed against the mode, then clears the counts again.
- Driver
- Scoreboard
- Environment
- Test
- Control
- Raises from below the contextevery item (illustrative)
The driver and the scoreboard raise. Each raise passes through env bench, where the heartbeat counts it for its source.
Follow the calls, values and waits
- call raise: bench.drv → env bench
- call raise: bench.sb → env bench
- A raise from elsewhereevery item (illustrative)
The raise of other.drv goes up through env other to the test. It never reaches env bench, so the heartbeat never counts it.
Follow the calls, values and waits
- call raise: other.drv → env other
- call raise: env other → uvm_test_top
Read the diagram as text
- bench.drv: raises prog per item
- bench.sb: raises prog per check
- env bench: heartbeat context: counts here
- other.drv: listed, but under env other
- env other: not the context
- uvm_test_top: then the root
- bench.drv → env bench: raise
- bench.sb → env bench: raise
- env bench → uvm_test_top: raise
- other.drv → env other: raise
- env other → uvm_test_top: raise
Scenario E of the example lists other.drv anyway. Every window fails, although other.drv works all the time.
Three Modes, Three Questions
set_mode picks the question asked of each window. UVM_ALL_ACTIVE is the default.
| Mode | A window passes when | Use it for | Measured in the example |
|---|---|---|---|
UVM_ALL_ACTIVE | every listed component raised | each part must keep working | A: sb silent from 45 ns fails at 80 and 100 ns |
UVM_ANY_ACTIVE | at least one listed component raised | the bench as a whole must not stall | C: drv alone passes; nobody fails at 340 ns |
UVM_ONE_ACTIVE | exactly one listed component raised | one master at a time, mutual exclusion | D: m0 and m1 both in 390-410 fails at 410 ns |
ONE mode also fails a window where nobody raised.
ANY mode is weak for liveness. In scenario C the scoreboard and the monitor are silent all the time. ANY mode stays quiet as long as the driver works. Use it only for "something in this group must happen", and ALL mode for "each of these must happen".
Two more details come from the source. A component that is not listed, but raises below the context, is added to the counts the first time it raises. From then on ALL mode expects it in every window. And the counts are per source component, so a parent never gets credit for a child's raise.
Wiring Rules
A heartbeat that sees nothing reports failures on a healthy bench, and one that sees too much misses real stalls. Four rules decide what it sees.
Pass the objection to new
With a null objection no callback is installed. uvm-core has no call to add one later, and the first failing ALL-mode window dereferences the null objection: the run aborts.
Pick the context above every listed part
A raise counts only when the propagated raise reaches the context. Scenario E lists a component of another environment, and every window fails.
Keep propagation on
With
set_propagate_mode(0)a raise jumps straight to the top. A heartbeat whose context is an environment then counts nothing; only one at the root would.Start each heartbeat with one event
start(e)with a different event while it runs is errorILHBVNT. Stop it first, then start it with the new event.
Decide what counts as progress before you wire it. Raise the heartbeat objection where work completes, such as in the monitor's write or the scoreboard's compare. A free-running pulse proves only that its own thread is alive.
Where a Heartbeat Fits
Three tools guard against a bench that stops making progress, and they answer different questions. The test timeout, set_timeout, ends a run that has lasted too long, but it names nobody and fires late. A drain time or a phase_ready_to_end check catches work that is still owed at the end of a phase. A heartbeat catches a part that stopped working in the middle of the run, within one window, and names it.
A heartbeat costs one objection raise and drop per unit of work, which is cheap. The real cost is design time: someone must decide which parts to list, what counts as progress, and when silence is legal. That is why the wiring rules above matter more than the API. It is also why a heartbeat belongs in the environment that owns the parts it watches.
Windows, Reset and Idle Time
The window event is yours to drive, so tie it to something meaningful, such as a fixed number of bus clocks. A window must be at least one item period long, or a healthy part misses some windows. A few periods is safer, at the cost of a later report.
Silence is legal in reset, under backpressure and after the traffic ends. stop() turns the callback off and ends the window process; start() turns them back on. The first window after start only opens, so the parts have time to resume. In scenario B everyone is silent from 150 to 210 ns. The heartbeat is stopped at 152 ns and started at 212 ns, and no window fails.
add(comp) and remove(comp) change the list while the heartbeat runs. A component added mid-run must take part in the window that is already open. Remove a part before it goes quiet for a legal reason, such as an unplugged port. Add a part the moment it must start working. The heartbeat adopts a component only when a raise from it arrives. So a part that never raises is checked only if you add it. For run-time phases, give each phase its own heartbeat and window, and stop it when the phase ends.
In uvm-core HBFAIL is a UVM_FATAL, and that is right for a real bench. A part that stopped working makes the rest of the run worthless. The example demotes it to an error with set_report_severity_id_override so that every window shows. On Verilator 5.052 the reporting process runs on until it waits. Processes already scheduled in that time step still run, so lines from that step can still appear.
Try It
Five scenarios, each with its own objection and window event, run one after another. The UVM_ERROR lines are the demoted HBFAIL reports; the misspelled "recieve" is the library's.
Comment out the hb.stop() and hb.start() lines of scenario B, and its windows in reset fail. Change scenario C to ALL mode and the silent monitor and scoreboard fail in every window.
--- A: ALL mode, sb stops after 45 ns UVM_ERROR @ 80: uvm_test_top.bench [HBFAIL] Did not recieve an update of prog_a for component uvm_test_top.bench.sb since last event trigger at time 60 : last update time was 45 UVM_ERROR @ 100: uvm_test_top.bench [HBFAIL] Did not recieve an update of prog_a for component uvm_test_top.bench.sb since last event trigger at time 80 : last update time was 45 --- B: ALL mode, everyone silent in reset from 150 to 210 ns 152 ns reset: heartbeat stopped 212 ns reset over: heartbeat started --- C: ANY mode, only drv works, then nobody UVM_ERROR @ 340: uvm_test_top.bench [HBFAIL] Did not recieve an update of prog_c on any component since last event trigger at time 320. The list of registered components is: --- D: ONE mode, m0 and m1 overlap at 395 ns UVM_ERROR @ 410: uvm_test_top.bench [HBFAIL] Recieved update of prog_d from more than one component since last event trigger at time 390. The list of triggered components is: uvm_test_top.bench.m0 (updated: 395) uvm_test_top.bench.m1 (updated: 405) --- E: a listed component outside the context UVM_ERROR @ 480: uvm_test_top.bench [HBFAIL] Did not recieve an update of prog_e for component uvm_test_top.other.drv since last event trigger at time 460 : last update time was 0 UVM_ERROR @ 500: uvm_test_top.bench [HBFAIL] Did not recieve an update of prog_e for component uvm_test_top.other.drv since last event trigger at time 480 : last update time was 0 UVM_ERROR : 6Check Yourself
Common Mistakes
Wrong Make a component outside the listed parts' parent the heartbeat's context.
A raise is counted only when it reaches the context. Raises that propagate past other parents never get there.
Fix Use the lowest component that is a parent of every listed part.
Wrong Create the heartbeat with no objection, meaning to add one later.
uvm-core 2020.3.1 has no call to add one later. No raise is counted, and the first failing window in ALL mode dereferences the null objection: the run aborts.
Fix Pass the objection to new.
Wrong Keep the heartbeat running through reset.
Every part is rightly silent in reset, so the first full window in reset fails.
Fix Call stop() when reset starts and start() when it ends.
Wrong Make the window shorter than a part's item period.
Some windows then hold no item from a healthy part, and they fail.
Fix Make the window at least one item period long; a few periods is safer.
Remember
- A heartbeat counts raises and drops of its objection that reach its context component, per source component, window by window.
- ALL mode needs every listed part in every window; ANY passes while one works; ONE needs exactly one.
- Pass the objection to
new, put the context above every listed part, and keep propagation on. - Stop the heartbeat in reset and idle time; the first window after
startonly opens. - Make each window at least one item period long, and leave
HBFAILfatal in a real bench.