Reactive agents

The direction of the conversation turns round

In every agent so far a sequence invents a transaction and the driver pushes it onto the pins. A reactive agent, also called a responder or slave agent, works the other way. Something on the design side starts a transfer; the agent must notice it and answer. This lesson's design under test is a small bus master, a plain SystemVerilog module with a fixed script of reads and writes. The UVM agent plays the memory it talks to.

The question is where the reply is decided. The driver could hold a memory array and answer alone, but then every variation (an error on one address, a slow reply, preloaded data) is a driver change. The reactive pattern keeps the driver as a pin mover and lets a responder sequence decide. Step through the four-part conversation below; it repeats for every bus request.

Step 2 relies on a fact from U4.1: the driver receives the very object the sequence created. Fields the driver writes are visible to the sequence as soon as finish_item returns. The pattern assumes one responder per sequencer; two responders on one sequencer would interleave their request and reply items and break the pairing.

rand and non-rand change places

Compare a master item with the responder's item for the same bus. On the master side addr, we and wdata are rand, because a test chooses them, and rdata and err are plain fields the driver fills in. On the responder side it is reversed. The request fields come from the pins and must not be randomized; the reply fields rdata, err and wait_cycles are rand, because the responder chooses them.

rand bit       we;
rand bit [7:0] addr, wdata;
bit [7:0]      rdata;    // from the design
bit            err;

bit            we;      // from the pins
bit [7:0]      addr, wdata;
rand bit [7:0] rdata;   // chosen by the responder
rand bit       err;
rand bit [1:0] wait_cycles;
constraint c_wait { wait_cycles <= 2; }

The responder sequence narrows those constraints per reply. A memory responder constrains rdata to the stored value for a read, err to 0 and wait_cycles to 0. An error-injecting responder keeps the same item and driver and constrains differently. For addresses at or above 0x80 it sets err to 1, returns the poison value 0xee and adds one wait cycle. The constraint block on the item sets the legal range; the sequence decides what this test needs.

A long-lived sequence

A master sequence runs for a known number of items and returns. A responder cannot know when the next request will arrive, so its body() is a forever loop that lasts the whole test. The test starts it in a forked thread and does not wait for it. The responder raises no objection; the last section shows who ends the run.

task body();
  forever begin
    bit [7:0] data;
    slave_item request = slave_item::type_id::create("request");
    slave_item reply   = slave_item::type_id::create("reply");
    start_item(request);
    finish_item(request);           // returns once the driver has seen a bus request
    if (request.we) mem[request.addr] = request.wdata;
    reply.we = request.we; reply.addr = request.addr; reply.wdata = request.wdata;
    data = mem.exists(request.addr) ? mem[request.addr] : 8'h00;
    start_item(reply);
    if (!reply.randomize() with { rdata == data; err == 0; wait_cycles == 0; })
      `uvm_error("RAND", "reply randomize failed")
    finish_item(reply);
  end
endtask

The forever is not decoration. A body that serves one request and returns leaves the driver blocked in get_next_item at the master's second access, and the test ends in a timeout. The quiz has that variant.

Swapping the responder is a one-line change in the test, or none at all with a factory override: err_responder_seq extends mem_responder_seq and overrides only the function that chooses the reply. The example runs both responders at once, on two copies of the master and agent, so the difference is visible in one log.

The driver as a pin mover

The driver's loop mirrors the four steps. It takes the request item, waits at the clock edge until req is high, fills the item from the pins and calls item_done. Then it takes the reply item, waits wait_cycles clocks, drives ack, rdata and err for one clock, and calls item_done again.

Nothing in the driver reads or stores data, and nothing in it knows about errors or delays beyond copying the reply's fields to the pins. That is what makes the agent reusable: a project with a different memory map, an ECC error model or a slow peripheral changes the sequence and keeps the driver.

Steps 2 and 3 take no simulation time. At the 65 ns edge the driver reports the request, the sequence computes and sends the reply, and the driver schedules ack. The master sees the answer at the next edge. A reply that needs real time, from a slow peripheral for example, gets it from wait_cycles, which the driver spends before driving ack.

One item or two

The example uses one item class for both halves of the conversation, with the request fields and the reply fields side by side. Its advantage is simplicity: one class, one sequencer type, no casting.

The alternative uses two item classes on a shared base. The request item holds only the non-rand pin fields. The reply item holds the rand response fields plus the few request fields the driver needs again, such as we. The sequencer and driver are parameterized with the base class, and the driver casts each item it receives to the request or reply type. Choose this when the halves have little in common, or when a protocol has more than two phases.

Who ends a responder

Nothing ends a responder from the inside. Its forever loop stops when the run phase ends: uvm-core kills every thread still running in a task phase once that phase completes. So the real question is what the test waits for before it drops its objection.

Wait for the design side, not the responder. Here the test waits for both masters' done flags. If it dropped its objection on a timer instead, a master could be mid-access, with its request reported and its reply still counting wait_cycles. That access would be cut off unanswered and never checked. A responder idle in finish_item(request) is safe to stop; one between the two halves is not.

Checking does not belong in the responder either. Its log is the agent's own account of what it answered. A monitor on the same pins, as in U7, gives the scoreboard a separate observation of what the master actually received.

Try it

Each master access produces two lines: the responder's decision at the edge where the driver reports the request, and the master's view one or two clocks later. Master 0 and resp0 run the memory responder; master 1 and resp1 run the error responder on an identical agent.

The two logs agree up to address 0x90. There resp1 answers the write with err=1 after one wait cycle and drops it. Master 1's read of 0x90 then returns the poison value 0xee with the error flag, while master 0 reads back 0x33. No driver code changed between the two agents; only the sequence did.

Try changing err_responder_seq to keep the write and error only the read, or constrain wait_cycles to inside {[0:2]} in mem_responder_seq and watch the master lines move while the data stays right.

Check yourself

`timescale 1ns/1ns
`include "uvm_macros.svh"
import uvm_pkg::*;
class slave_item extends uvm_sequence_item;
  `uvm_object_utils(slave_item)
  bit            we;
  bit [7:0]      addr, wdata;
  rand bit [7:0] rdata;
  rand bit       err;
  function new(string name = "slave_item"); super.new(name); endfunction
endclass
class drv_c extends uvm_driver #(slave_item);
  `uvm_component_utils(drv_c)
  bit       we[5]    = '{1, 0, 0, 1, 0};
  bit [7:0] addr[5]  = '{8'h10, 8'h10, 8'h11, 8'h11, 8'h11};
  bit [7:0] wdata[5] = '{7, 0, 0, 9, 0};
  int reads[$];
  function new(string name, uvm_component parent); super.new(name, parent); endfunction
  task run_phase(uvm_phase phase);
    slave_item request, reply;
    phase.raise_objection(this);
    for (int i = 0; i < 5; i++) begin
      seq_item_port.get_next_item(request);
      #10;
      request.we = we[i]; request.addr = addr[i]; request.wdata = wdata[i];
      seq_item_port.item_done();
      seq_item_port.get_next_item(reply);
      if (!reply.we) reads.push_back(reply.rdata);
      seq_item_port.item_done();
    end
    $display("reads %0d %0d %0d", reads[0], reads[1], reads[2]);
    phase.drop_objection(this);
  endtask
endclass
class responder_seq extends uvm_sequence #(slave_item);
  `uvm_object_utils(responder_seq)
  bit [7:0] mem [bit [7:0]];
  function new(string name = "responder_seq"); super.new(name); endfunction
  task body();
    forever begin
      bit [7:0] data;
      slave_item request = slave_item::type_id::create("request");
      slave_item reply   = slave_item::type_id::create("reply");
      start_item(request);
      finish_item(request);
      if (request.we) mem[request.addr] = request.wdata;
      data = mem.exists(request.addr) ? mem[request.addr] : 8'h00;
      reply.we = request.we; reply.addr = request.addr;
      start_item(reply);
      if (!reply.randomize() with { rdata == data; err == 0; })
        `uvm_error("RAND", "randomize failed")
      finish_item(reply);
    end
  endtask
endclass
class my_test extends uvm_test;
  `uvm_component_utils(my_test)
  drv_c drv;
  uvm_sequencer #(slave_item) sqr;
  function new(string name, uvm_component parent); super.new(name, parent); endfunction
  function void build_phase(uvm_phase phase);
    drv = drv_c::type_id::create("drv", this);
    sqr = uvm_sequencer #(slave_item)::type_id::create("sqr", this);
  endfunction
  function void connect_phase(uvm_phase phase);
    drv.seq_item_port.connect(sqr.seq_item_export);
  endfunction
  task run_phase(uvm_phase phase);
    responder_seq seq = responder_seq::type_id::create("seq");
    fork seq.start(sqr); join_none
  endtask
endclass
module tb;
  initial run_test("my_test");
endmodule

forever begin
  request = slave_item::type_id::create("request");
  start_item(request);
  finish_item(request);
  if (request.we) mem[request.addr] = request.wdata;
  data = lookup(request.addr);
  start_item(request);
  if (!request.randomize() with { rdata == data; err == 0; wait_cycles == 0; })
    `uvm_error("RAND", "randomize failed")
  finish_item(request);
end

forever begin
  request = slave_item::type_id::create("request");
  reply   = slave_item::type_id::create("reply");
  start_item(request);
  finish_item(request);
  if (request.we) mem[request.addr] = request.wdata;
  reply.we = request.we; reply.addr = request.addr;
  reply.rdata = lookup(request.addr); reply.err = 0; reply.wait_cycles = 0;
  start_item(reply);
  finish_item(reply);
end

request = slave_item::type_id::create("request");
reply   = slave_item::type_id::create("reply");
start_item(request);
finish_item(request);
if (request.we) mem[request.addr] = request.wdata;
data = lookup(request.addr);
reply.we = request.we; reply.addr = request.addr;
start_item(reply);
if (!reply.randomize() with { rdata == data; err == 0; wait_cycles == 0; })
  `uvm_error("RAND", "randomize failed")
finish_item(reply);

forever begin
  request = slave_item::type_id::create("request");
  reply   = slave_item::type_id::create("reply");
  start_item(request);
  finish_item(request);
  if (request.we) mem[request.addr] = request.wdata;
  data = lookup(request.addr);
  reply.we = request.we; reply.addr = request.addr;
  start_item(reply);
  if (!reply.randomize() with { rdata == data; err == 0; wait_cycles == 0; })
    `uvm_error("RAND", "randomize failed")
  finish_item(reply);
end

Practice

• Play the memory, including its protected page Implement · Medium