Vetoes, Early Exit and an Error-Injection Library

Let a callback refuse a beat with uvm_do_callbacks_exit_on. Then build a small injection library that drops, corrupts and delays beats, with a ledger that matches the pins.

You Will Be Able To

  • Write a veto hook with uvm_do_callbacks_exit_on and predict its return value.
  • Choose the registration order so the right callback may veto.
  • Build stackable injectors that read a plan and write a ledger.
  • Check that every injection the ledger records reached the pins.
Lesson
U18.4
Time
30 min
Runs on
Verilator with UVM
Check
4 questions

A VIP release added a hook that lets a test drop a beat. The first test that used it lost every beat on the lane, not just the planned one. The driver asked its callbacks with uvm_do_callbacks, which ignores their answers, so its veto function always returned 0.

Facade line in may_sendBeats the plan dropsBeats on the pins
uvm_do_callbacks(...)1 of 50 of 5
uvm_do_callbacks_exit_on(..., 0) (the example)1 of 54 of 5

Measured with the lesson's lane VIP: five items, the plan drops item 2.

A Hook That Can Say No

Some hooks must return an answer: may this beat go out? The VIP's second release adds allow_send, a function hook that returns bit. The driver asks it through may_send before it builds the pins, and drops the beat on 0.

uvm_do_callbacks

while (cb != null) begin
  cb.allow_send(this, it, beat);
  cb = iter.next();
end

Every callback is asked and every answer is thrown away.

uvm_do_callbacks_exit_on(..., 0)

while (cb != null) begin
  if (cb.allow_send(this, it, beat) == 0)
    return 0;
  cb = iter.next();
end
return 1;

The first callback that answers 0 ends the walk; with none, the result is 1.

The fourth argument is the value that stops the walk; the function returns its opposite when nobody gives it. With 0, every callback must agree and any one may veto. With 1, the first callback that says yes decides, and the rest are not asked.

Because the expansion contains return, it must be the last statement of a function that returns bit. A task cannot hold it, and code after it never runs. uvm_do_obj_callbacks_exit_on is the same with an object argument instead of this.

Order Decides Who May Veto

Item 2: The Walk Stops at the VetoThe example's lane0.drv asks its callbacks in queue order: drop, asked, corrupt, delay. Arrows are calls.
  • Driver
  • Step
  • I/O
  • Control
  • Data
CallValueReturnWaiting
Item 2: the walk stops at the vetoThe example's `lane0.drv` asks its callbacks in queue order: drop, asked, corrupt, delay. Arrows are calls. driver lane0.drv may_send(item 2,beat) step drop item 2 is planned:returns 0 step asked an observer: neverasked about item 2 step corrupt pre_send never runsfor item 2 step ledger dropped: 2 io lane_if pins nothing for item 2 allow_sendnext: skippeddropped 2pre_send: skippeddrives
  1. driver lane0.drvmay_send(item 2, beat)
    • allow_send → drop
    • pre_send: skipped → corrupt
    • drives → lane_if pins
  2. step dropitem 2 is planned: returns 0
    • next: skipped → asked
    • dropped 2 → ledger
  3. step ledgerdropped: 2
  4. step askedan observer: never asked about item 2
  5. step corruptpre_send never runs for item 2
  6. io lane_if pinsnothing for item 2
  1. Ask the first callback

    may_send expands uvm_do_callbacks_exit_on with value 0. It asks drop first, because drop was added first.

    Follow the calls, values and waits
    1. call allow_send(item 2): lane0.drv → drop
  2. The veto

    drop finds item 2 in the plan, records it and returns 0. The macro runs return 0 at once, so asked is never asked.

    Follow the calls, values and waits
    1. data dropped: 2: drop → ledger
    2. return returns 0: drop → lane0.drv
  3. Nothing else runs

    The driver calls item_done for item 2 and asks for item 3. No pre_send runs for item 2, so corrupt cannot touch the dropped beat although item 2 is in its plan.

Read the diagram as text
  • lane0.drv: may_send(item 2, beat)
  • drop: item 2 is planned: returns 0
  • asked: an observer: never asked about item 2
  • corrupt: pre_send never runs for item 2
  • ledger: dropped: 2
  • lane_if pins: nothing for item 2
  • lane0.drv → drop: allow_send
  • drop → asked: next: skipped
  • drop → ledger: dropped 2
  • lane0.drv → corrupt: pre_send: skipped
  • lane0.drv → lane_if pins: drives

Order decides who may veto and who is asked. An observer that must see every beat goes before the vetoing callback.

The example adds four callbacks in this order: drop, asked, corrupt, delay. asked is an observer that counts the beats it was asked about. It reports 4, not 5, because item 2 stopped at drop.

The UVM 1.1 guide shows another style: a ref bit drop argument that every callback may set. Every callback then runs, and a later one may even clear an earlier drop. Pick one style per hook and write it in the hook's comment.

Three Patterns for an Answering Hook

PatternMacro valueResult with no callbacksExample
Ask permission: anyone may veto01: sendallow_send: drop a planned beat
First handler wins10: not handledA response hook: the first callback that claims an address answers it
Everyone votes, the driver decidesnone: ref argumentwhatever the driver setUVM 1.1 trans_received(..., ref bit drop)

The value in the macro is the answer that stops the walk.

A Stackable Injection Library

Each injector does one thing at the hook that fits it. drop_cb vetoes at allow_send. corrupt_cb flips parity at pre_send. delay_cb waits at post_send. They share two objects: a plan, which items each one acts on, and a ledger, what each one really did.

Because each injector has one job, a test stacks only the ones it needs, and two tests combine without a new class. The plan can come from the configuration database or plusargs, so a regression varies it without editing code.

Lane 0 in the example: five items, drop 2, corrupt 2 and 4, delay after 3
01234567edge (ns)1525354555657585beat taken10-30-40-50paritygood-good-BAD-goodinjector-drop 2-delaycorrupt 4-item 2 vetoeditem 4 corrupted
Scroll horizontally ↔

Item 2 never reaches the pins, so its planned corruption never happens. The ledger says the same.

The ledger is what makes the library trustworthy. check_phase compares it with the monitor: one bad beat per recorded corruption, and one missing beat per recorded drop. A mismatch means an injector claims work the pins never showed, as in the hook. U12.1's CBIDLE check is the same idea for one injector.

Try It

Four beats reach the sink. Item 2 is missing, item 4 has bad parity, and item 4 waits two extra clocks after item 3. The ledger agrees with the pins, so check_phase reports nothing.

Swap the first two add lines so asked comes first: it counts 5. Then add corrupt before drop and change corrupt_cb to act in allow_send instead of pre_send: the ledger lists 2 as corrupted, and check_phase reports LEDGER.

RUNVerilator + UVM 2020.3.1 · simulator service
Edit the code, then run it
Expected among the UVM messages: 15 ns lane0 took 10, parity good 35 ns lane0 took 30, parity good 65 ns lane0 took 40, parity BAD 85 ns lane0 took 50, parity good ledger: dropped 2; corrupted 4; delayed 3; asked 4 times; pins: 4 beats, 1 bad UVM_ERROR : 0

Check Yourself

Predict the outputIn this VIP, may_send uses uvm_do_callbacks(lane_driver, lane_cb, allow_send(this, it, beat)) instead of the _exit_on form. Nothing else changes. What line does the $display print?
`timescale 1ns/1ns
`include "uvm_macros.svh"
import uvm_pkg::*;

// One lane of the chip's link. The sink takes a beat at a rising edge where valid and
// ready are both 1, then is busy for one edge.
interface lane_if (input logic clk);
  logic       valid = 0;
  logic [7:0] data = 0;
  logic       par = 0;
  logic       ready;
endinterface

module lane_sink (lane_if bus);
  logic busy = 0;
  assign bus.ready = !busy;
  always @(posedge bus.clk) busy <= bus.valid && !busy;
endmodule

class lane_item extends uvm_sequence_item;
  `uvm_object_utils(lane_item)
  bit [7:0] data;
  int       n;                         // 1, 2, 3, ...: position in the sequence
  function new(string name = "lane_item"); super.new(name); endfunction
endclass

// The pin values of one transfer. Callbacks may edit this; the item stays as the sequence sent it.
class lane_beat extends uvm_object;
  `uvm_object_utils(lane_beat)
  bit [7:0] data;
  bit       par;
  function new(string name = "lane_beat"); super.new(name); endfunction
endclass

typedef class lane_driver;

// ---- The VIP author's hook class: three hooks, all empty until a callback overrides them ----
class lane_cb extends uvm_callback;
  `uvm_object_utils(lane_cb)
  function new(string name = "lane_cb"); super.new(name); endfunction
  // Before anything else. Return 0 to drop this beat; 1 lets it go on to the other callbacks.
  virtual function bit allow_send(lane_driver drv, lane_item it, lane_beat beat); return 1; endfunction
  // After the driver builds the beat, before any pin moves. Edit the beat here.
  virtual function void pre_send(lane_driver drv, lane_item it, lane_beat beat); endfunction
  // After the sink took the beat, before item_done. A task: the driver waits until it returns.
  virtual task post_send(lane_driver drv, lane_item it, lane_beat beat); endtask
endclass

class lane_driver extends uvm_driver #(lane_item);
  `uvm_component_utils(lane_driver)
  `uvm_register_cb(lane_driver, lane_cb)          // lane_driver offers lane_cb hooks
  virtual lane_if vif;
  int unsigned hook_runs;                          // how many times a hook point ran
  int unsigned dropped;                            // beats a callback vetoed
  function new(string name, uvm_component parent); super.new(name, parent); endfunction
  // 1 when no callback objects. The first callback that returns 0 vetoes the beat, and the
  // callbacks after it are not asked.
  function bit may_send(lane_item it, lane_beat beat);
    `uvm_do_callbacks(lane_driver, lane_cb, allow_send(this, it, beat))
  endfunction
  task run_phase(uvm_phase phase);
    forever begin
      lane_beat beat;
      seq_item_port.get_next_item(req);
      beat = lane_beat::type_id::create("beat");
      beat.data = req.data;
      beat.par  = ^req.data;                       // even parity over data and par
      if (!may_send(req, beat)) begin              // vetoed: the beat never reaches the pins
        dropped++;
        seq_item_port.item_done();
        continue;
      end
      hook_runs++;
      `uvm_do_callbacks(lane_driver, lane_cb, pre_send(this, req, beat))
      @(negedge vif.clk);
      vif.valid <= 1;
      vif.data  <= beat.data;
      vif.par   <= beat.par;
      do @(posedge vif.clk); while (!vif.ready);   // the sink takes the beat at this edge
      vif.valid <= 0;
      hook_runs++;
      `uvm_do_callbacks(lane_driver, lane_cb, post_send(this, req, beat))
      seq_item_port.item_done();
    end
  endtask
endclass

// Counts, and prints, every beat the sink takes.
class lane_monitor extends uvm_monitor;
  `uvm_component_utils(lane_monitor)
  virtual lane_if vif;
  int unsigned beats, bad;
  function new(string name, uvm_component parent); super.new(name, parent); endfunction
  task run_phase(uvm_phase phase);
    forever begin
      @(posedge vif.clk);
      if (vif.valid && vif.ready) begin
        beats++;
        if (vif.par != ^vif.data) bad++;
      end
    end
  endtask
endclass

class lane_agent extends uvm_agent;
  `uvm_component_utils(lane_agent)
  uvm_sequencer #(lane_item) sqr;
  lane_driver  drv;
  lane_monitor mon;
  function new(string name, uvm_component parent); super.new(name, parent); endfunction
  function void build_phase(uvm_phase phase);
    virtual lane_if vif;
    if (!uvm_config_db #(virtual lane_if)::get(this, "", "vif", vif)) `uvm_fatal("NOVIF", "no lane_if")
    sqr = uvm_sequencer #(lane_item)::type_id::create("sqr", this);
    drv = lane_driver::type_id::create("drv", this);
    mon = lane_monitor::type_id::create("mon", this);
    drv.vif = vif;
    mon.vif = vif;
  endfunction
  function void connect_phase(uvm_phase phase); drv.seq_item_port.connect(sqr.seq_item_export); endfunction
endclass

// Items 1, 2, 3, ... with data 10, 20, 30, ... (hex).
class lane_seq extends uvm_sequence #(lane_item);
  `uvm_object_utils(lane_seq)
  int count = 3;
  function new(string name = "lane_seq"); super.new(name); endfunction
  task body();
    for (int i = 1; i <= count; i++) begin
      lane_item it = lane_item::type_id::create("it");
      start_item(it);
      it.data = 8'(16 * i);
      it.n    = i;
      finish_item(it);
    end
  endtask
endclass

// ---- The test's injection library ----
// Which items each injector acts on. A test fills one plan and hands it to every injector.
class inject_plan extends uvm_object;
  `uvm_object_utils(inject_plan)
  int drop[$], corrupt[$], delay[$];
  int delay_cycles = 2;
  function new(string name = "inject_plan"); super.new(name); endfunction
  static function bit has(int q[$], int n);
    foreach (q[i]) if (q[i] == n) return 1;
    return 0;
  endfunction
endclass

// What the injectors really did, by item number. The checks compare it with the pins.
class inject_ledger extends uvm_object;
  `uvm_object_utils(inject_ledger)
  int dropped[$], corrupted[$], delayed[$];
  function new(string name = "inject_ledger"); super.new(name); endfunction
  static function string show(int q[$]);
    string s = "";
    foreach (q[i]) s = {s, $sformatf(" %0d", q[i])};
    return s == "" ? " -" : s;
  endfunction
endclass

// Each injector reads the plan and writes the ledger.
class inject_cb extends lane_cb;
  `uvm_object_utils(inject_cb)
  inject_plan   plan;
  inject_ledger ledger;
  function new(string name = "inject_cb"); super.new(name); endfunction
endclass

// Vetoes the planned items: they never reach the pins.
class drop_cb extends inject_cb;
  `uvm_object_utils(drop_cb)
  function new(string name = "drop_cb"); super.new(name); endfunction
  function bit allow_send(lane_driver drv, lane_item it, lane_beat beat);
    if (!inject_plan::has(plan.drop, it.n)) return 1;
    ledger.dropped.push_back(it.n);
    return 0;
  endfunction
endclass

// Flips the parity of the planned items.
class corrupt_cb extends inject_cb;
  `uvm_object_utils(corrupt_cb)
  function new(string name = "corrupt_cb"); super.new(name); endfunction
  function void pre_send(lane_driver drv, lane_item it, lane_beat beat);
    if (!inject_plan::has(plan.corrupt, it.n)) return;
    beat.par = !beat.par;
    ledger.corrupted.push_back(it.n);
  endfunction
endclass

// Holds the lane idle for a few clocks after the planned items.
class delay_cb extends inject_cb;
  `uvm_object_utils(delay_cb)
  function new(string name = "delay_cb"); super.new(name); endfunction
  task post_send(lane_driver drv, lane_item it, lane_beat beat);
    if (!inject_plan::has(plan.delay, it.n)) return;
    repeat (plan.delay_cycles) @(posedge drv.vif.clk);
    ledger.delayed.push_back(it.n);
  endtask
endclass

// An observer: counts the beats it was asked about. It never vetoes.
class asked_cb extends lane_cb;
  `uvm_object_utils(asked_cb)
  int asked;
  function new(string name = "asked_cb"); super.new(name); endfunction
  function bit allow_send(lane_driver drv, lane_item it, lane_beat beat);
    asked++;
    return 1;
  endfunction
endclass

class inject_test extends uvm_test;
  `uvm_component_utils(inject_test)
  lane_agent    lane0;
  inject_plan   plan;
  inject_ledger ledger;
  drop_cb       drop;
  corrupt_cb    corrupt;
  delay_cb      delay;
  asked_cb      asked;
  function new(string name, uvm_component parent); super.new(name, parent); endfunction
  function void build_phase(uvm_phase phase);
    inject_cb all[3];
    lane0   = lane_agent::type_id::create("lane0", this);
    plan    = inject_plan::type_id::create("plan");
    ledger  = inject_ledger::type_id::create("ledger");
    plan.drop    = '{2};
    plan.corrupt = '{2, 4};
    plan.delay   = '{3};
    drop    = drop_cb::type_id::create("drop");
    corrupt = corrupt_cb::type_id::create("corrupt");
    delay   = delay_cb::type_id::create("delay");
    asked   = asked_cb::type_id::create("asked");
    all = '{drop, corrupt, delay};
    foreach (all[i]) begin
      all[i].plan   = plan;
      all[i].ledger = ledger;
    end
  endfunction
  function void connect_phase(uvm_phase phase);
    uvm_callbacks #(lane_driver, lane_cb)::add(lane0.drv, drop);
    uvm_callbacks #(lane_driver, lane_cb)::add(lane0.drv, asked);
    uvm_callbacks #(lane_driver, lane_cb)::add(lane0.drv, corrupt);
    uvm_callbacks #(lane_driver, lane_cb)::add(lane0.drv, delay);
  endfunction
  task run_phase(uvm_phase phase);
    lane_seq seq = lane_seq::type_id::create("seq");
    seq.count = 5;
    phase.raise_objection(this);
    seq.start(lane0.sqr);
    #20;
    phase.drop_objection(this);
  endtask
  // The ledger must match the pins: one bad beat per corruption, one missing beat per drop.
  function void check_phase(uvm_phase phase);
    if (lane0.mon.bad != ledger.corrupted.size())
      `uvm_error("LEDGER", $sformatf("pins show %0d bad beats, ledger %0d corruptions", lane0.mon.bad, ledger.corrupted.size()))
    if (lane0.mon.beats + ledger.dropped.size() != 5)
      `uvm_error("LEDGER", $sformatf("pins show %0d beats, ledger %0d drops, for 5 items", lane0.mon.beats, ledger.dropped.size()))
  endfunction
  function void report_phase(uvm_phase phase);
    $display("ledger: dropped%s; corrupted%s; delayed%s; asked %0d times; pins: %0d beats, %0d bad",
             inject_ledger::show(ledger.dropped), inject_ledger::show(ledger.corrupted),
             inject_ledger::show(ledger.delayed), asked.asked, lane0.mon.beats, lane0.mon.bad);
  endfunction
endclass

module tb;
  bit clk;
  always #5 clk = ~clk;
  lane_if   bus0 (clk);
  lane_sink sink0 (bus0);
  initial begin
    uvm_config_db #(virtual lane_if)::set(null, "uvm_test_top.lane0", "vif", bus0);
    run_test("inject_test");
  end
endmodule
ConceptA response hook should let the first callback that claims an address answer it, and skip the rest. Which facade line fits, inside function bit claimed(...)?
ConceptWhy does the example keep a ledger instead of counting each injector's calls?
Conceptmay_send holds the _exit_on macro. A developer adds hits++; on the line after it, to count the beats that were allowed. What does hits count?

Common Mistakes

Wrong Put a veto hook point behind uvm_do_callbacks in a function that returns bit.

The plain macro throws every answer away, and the function returns its default, 0.

Fix Use uvm_do_callbacks_exit_on, which returns the first veto or the other value.

Before
function bit may_send(lane_item it, lane_beat beat);
  `uvm_do_callbacks(lane_driver, lane_cb, allow_send(this, it, beat))
endfunction
After
function bit may_send(lane_item it, lane_beat beat);
  `uvm_do_callbacks_exit_on(lane_driver, lane_cb, allow_send(this, it, beat), 0)
endfunction

Wrong Write code after the ` _exit_on ` macro in the same function.

The macro ends in return statements, so the code after it never runs.

Fix Give the macro a function of its own, and act on its result in the caller.

Wrong Register an observer after the vetoing callback and trust its count of every beat.

The walk stops at the veto, so callbacks later in the queue are never asked about that beat.

Fix Put callbacks that must see every beat before the one that may veto, or count from the monitor.

Remember

  • uvm_do_callbacks_exit_on(T, CB, METHOD, VAL) returns VAL at the first callback that returns VAL, and 1-VAL if none does.
  • The macro contains return, so it must be the last statement of a function that returns bit.
  • Callbacks after a veto are not asked. Put observers before the vetoing callback, or count from the monitor.
  • Give each injector one job at the hook that fits it. Share a plan and a ledger, and check the ledger against the pins.

Practice

Report a problem with this page