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.

Scenario A: 20 Ns Windows, ALL Mode, Sb Silent After 45 Ns
01234tick (ns)20406080100window checkednone: opens20-4040-6060-8080-100drv raised-yesmon raised-yessb raised-yesyes (45)noHBFAIL-sbfirst window without sb
Scroll horizontally ↔
  1. Cycle 0

    The first tick only opens a window and clears the counts. Nothing is checked yet.

  2. Cycle 2

    The window from 40 to 60 ns still holds sb's raise at 45 ns.

  3. Cycle 3

    The window from 60 to 80 ns has none. HBFAIL names uvm_test_top.bench.sb and 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.

Which Raises Reach the HeartbeatThe arrows follow an objection raise up the component tree. The heartbeat counts at its context, env bench. A part of env other never passes through it.
  • Driver
  • Scoreboard
  • Environment
  • Test
  • Control
CallValueReturnWaiting
Which raises reach the heartbeatThe arrows follow an objection raise up the component tree. The heartbeat counts at its context, env bench. A part of env other never passes through it. driver bench.drv raises prog per item scoreboard bench.sb raises prog per check env env bench heartbeat context:counts here driver other.drv listed, but under envother env env other not the context test uvm_test_top then the root raiseraiseraiseraiseraise
  1. driver bench.drvraises prog per item
    • raise → env bench
  2. scoreboard bench.sbraises prog per check
    • raise → env bench
  3. env env benchheartbeat context: counts here
    • raise → uvm_test_top
  4. driver other.drvlisted, but under env other
    • raise → env other
  5. env env othernot the context
    • raise → uvm_test_top
  6. test uvm_test_topthen the root
  1. 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
    1. call raise: bench.drv → env bench
    2. call raise: bench.sb → env bench
  2. 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
    1. call raise: other.drv → env other
    2. 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.

ModeA window passes whenUse it forMeasured in the example
UVM_ALL_ACTIVEevery listed component raisedeach part must keep workingA: sb silent from 45 ns fails at 80 and 100 ns
UVM_ANY_ACTIVEat least one listed component raisedthe bench as a whole must not stallC: drv alone passes; nobody fails at 340 ns
UVM_ONE_ACTIVEexactly one listed component raisedone master at a time, mutual exclusionD: 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.

  1. 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.

  2. 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.

  3. 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.

  4. Start each heartbeat with one event

    start(e) with a different event while it runs is error ILHBVNT. 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.

RUNVerilator + UVM 2020.3.1 · simulator service
Edit the code, then run it
Expected among the UVM messages: --- 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 : 6

Check Yourself

Predict the outputA heartbeat in ALL mode watches two workers with a 30 ns window, and w2 stops raising after 50 ns. HBFAIL is demoted to an error so the run goes on. What line does the $display print?
`timescale 1ns/1ns
`include "uvm_macros.svh"
import uvm_pkg::*;
class worker extends uvm_component;
  `uvm_component_utils(worker)
  uvm_objection prog;
  int stop_at = 1000;
  function new(string name, uvm_component parent); super.new(name, parent); endfunction
  task run_phase(uvm_phase phase);
    #5;
    while ($time <= stop_at) begin prog.raise_objection(this); prog.drop_objection(this); #10; end
  endtask
endclass
class my_test extends uvm_test;
  `uvm_component_utils(my_test)
  worker w1, w2;
  uvm_objection prog = new("prog");
  function new(string name, uvm_component parent); super.new(name, parent); endfunction
  function void build_phase(uvm_phase phase);
    w1 = worker::type_id::create("w1", this); w1.prog = prog;
    w2 = worker::type_id::create("w2", this); w2.prog = prog; w2.stop_at = 50;
    set_report_severity_id_override(UVM_FATAL, "HBFAIL", UVM_ERROR);
  endfunction
  task run_phase(uvm_phase phase);
    uvm_event #(uvm_object) win = new("win");
    uvm_heartbeat hb = new("hb", this, prog);
    uvm_component parts[$] = '{w1, w2};
    phase.raise_objection(this);
    hb.set_heartbeat(win, parts);
    repeat (4) begin #30; win.trigger(); end
    hb.stop();
    $display("HBFAIL reports: %0d", uvm_report_server::get_server().get_id_count("HBFAIL"));
    phase.drop_objection(this);
  endtask
endclass
module tb;
  initial run_test("my_test");
endmodule
ConceptAn environment has a driver, a monitor and a scoreboard under it. Where should a heartbeat that watches all three have its context?
ConceptA heartbeat is started at 0 ns with window ticks at 50, 100 and 150 ns. A component stops raising at 60 ns. When is the first HBFAIL?
ConceptWhat does hb.stop() followed later by hb.start() do to the first window after the restart?

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 start only opens.
  • Make each window at least one item period long, and leave HBFAIL fatal in a real bench.

Practice

Report a problem with this page