Responses and routing

Two ways back to the sequence

Many protocols need an answer: read data, an error flag, a status. In U4.1 the driver received the very object the sequence created. The simplest way back uses that: the driver writes the result into req and calls item_done(), and the sequence reads the field once finish_item returns.

The second way is a separate response object. The driver creates it, fills it in, and returns it with item_done(rsp) or seq_item_port.put_response(rsp). The sequence picks it up with get_response(rsp), which blocks until a response for this sequence arrives.

The rest of this lesson is about separate responses, because they need routing.

How a response finds its sequence

Several sequences can share one sequencer, so a response needs an address, and every item carries two numbers for this. When finish_item sends an item, the sequencer stamps it with the sending sequence's sequence ID. The sequence also numbers its items with a transaction ID: 1, 2, 3 and so on, unless you set one yourself.

A new response object has neither. rsp.set_id_info(req) copies both numbers from the request into the response. When the response comes back, the sequencer reads its sequence ID, finds that sequence and adds the response to the sequence's response queue. get_response takes responses from that queue.

1. The request goes out

   The sequence calls finish_item. The sequencer stamps the item with the sequence ID, and the sequence gives it the next transaction ID.

2. The driver builds a response

   It creates a new object, calls rsp.set_id_info(req) and fills in the result fields.

3. The response comes back

   The driver calls item_done(rsp), or put_response(rsp) at any later time. Both hand the response to the sequencer.

4. The sequencer routes it

   It looks up the sequence by sequence ID and adds the response to that sequence's queue.

5. The sequence collects it

   Its get_response call returns the response, either the oldest one or the one with the transaction ID it asked for.

Forget set_id_info and the response has no sequence ID. The sequencer cannot route it, and uvm-core stops the test with a fatal error: "Driver put a response with null sequence_id".

These item classes use the default copy, so req.clone() leaves their payload and routing IDs at defaults. A custom do_copy can copy both deliberately. Set the response fields and call set_id_info(req) to make the reply's contents and destination explicit.

Two sequences, one driver

The example runs two sequences in parallel on one sequencer. low sends 10 and 11, and high sends 100 and 101. The sequencer grants them in turn, so the driver sees 10, 100, 11, 101.

Both sequences number their items from 1, so the bus carries two items with transaction ID 1, and that is fine. The sequence ID keeps the two streams apart, and a transaction ID only has to be unique within one sequence.

Each sequence asks for its own answer with get_response(rsp, it.get_transaction_id()). With an ID, get_response waits for that response and leaves others queued. Without one, it takes the oldest arrival. That also supports reordered results if the collector uses rsp.get_transaction_id() to find the matching request, as U6.1 demonstrates.

Read the example's log by time. Each item takes two clock cycles, so responses arrive at 20, 40, 60 and 80 ns, alternating between low and high. Neither sequence ever prints the other's answer, although both wait on the same driver and use the same transaction IDs.

Collect every response

A response queue holds 8 responses by default. A sequence that receives responses but never calls get_response fills it after 8 items, and later responses are thrown away.

Three settings change this: set_response_queue_depth(-1) makes the queue unbounded, and set_response_queue_error_report_enabled(1) reports each dropped response as an error. use_response_handler(1) makes the sequencer call the sequence's response_handler function for each response instead of queuing it.

The simplest rule is to match the two sides. If a sequence wants responses, it reads every one. If it does not, the driver should not send any. The usual way into this trap is a driver written for one sequence that reads responses, later reused with another that does not. The first 8 items behave, and everything after them is lost.

Reusing an item after you send it

The hook's bug has a twin on the sequence side. A sequence that creates one item before its loop sends the same object every time. Anything that kept a handle to an earlier send, such as a list of sent items or a pipelined driver, now sees the newest values instead.

There is a quieter effect too: the sequence numbers an item only while its transaction ID is still unset. A reused item keeps the ID from its first send, so every send carries transaction ID 1, and get_response by ID can no longer tell them apart.

incr_item it = incr_item::type_id::create("it");
repeat (3) begin
  start_item(it);
  it.x = next_x++;
  finish_item(it);
  sent.push_back(it);     // three handles, one object
end

repeat (3) begin
  incr_item it = incr_item::type_id::create("it");
  start_item(it);
  it.x = next_x++;
  finish_item(it);
  sent.push_back(it);
end

The rule is the same on both sides. Create a new request for every send and a new response for every reply. If you need to keep an item and also change it afterwards, keep a clone.

Try it

Two sequences share the driver. Each line is printed by the sequence that received the response, with the transaction ID it matched on. Both sequences use transaction IDs 1 and 2, and each still gets only its own answers.

Delete the rsp.set_id_info(req); line in the driver and run again: the first item_done stops the test with a fatal error. Then restore it and make low send three values to see transaction ID 3.

Check yourself

`timescale 1ns/1ns
`include "uvm_macros.svh"
import uvm_pkg::*;
class item_c extends uvm_sequence_item;
  `uvm_object_utils(item_c)
  bit [7:0] x;
  function new(string name = "item_c"); super.new(name); endfunction
endclass
class drv_c extends uvm_driver #(item_c);
  `uvm_component_utils(drv_c)
  function new(string name, uvm_component parent); super.new(name, parent); endfunction
  task run_phase(uvm_phase phase);
    forever begin
      seq_item_port.get_next_item(req);
      #10;
      seq_item_port.item_done();
    end
  endtask
endclass
class seq_c extends uvm_sequence #(item_c);
  `uvm_object_utils(seq_c)
  function new(string name = "seq_c"); super.new(name); endfunction
  task body();
    item_c it = item_c::type_id::create("it");
    item_c sent[$];
    for (int i = 1; i <= 3; i++) begin
      start_item(it);
      it.x = 10 * i;
      finish_item(it);
      sent.push_back(it);
    end
    $display("ids %0d %0d %0d, values %0d %0d %0d",
             sent[0].get_transaction_id(), sent[1].get_transaction_id(), sent[2].get_transaction_id(),
             sent[0].x, sent[1].x, sent[2].x);
  endtask
endclass
class my_test extends uvm_test;
  `uvm_component_utils(my_test)
  drv_c drv;
  uvm_sequencer #(item_c) 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 #(item_c)::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);
    seq_c seq = seq_c::type_id::create("seq");
    phase.raise_objection(this);
    seq.start(sqr);
    phase.drop_objection(this);
  endtask
endclass
module tb;
  initial run_test("my_test");
endmodule

rsp = item_c::type_id::create("rsp");
rsp.set_id_info(req);
rsp.y = req.x + 1;
seq_item_port.item_done(rsp);

$cast(rsp, req.clone());
rsp.y = req.x + 1;
seq_item_port.item_done(rsp);

rsp = item_c::type_id::create("rsp");
rsp.set_id_info(req);
rsp.y = req.x + 1;
seq_item_port.item_done();
seq_item_port.put_response(rsp);

$cast(rsp, req.clone());
rsp.set_id_info(req);
rsp.y = req.x + 1;
seq_item_port.item_done(rsp);