Analysis ports: one call, many listeners

One call reaches every listener

An analysis port is a port whose interface has one method, write(T t), and which may reach any number of imps. A put port, with its default bounds, reaches exactly one. When you call ap.write(t), the port loops over its resolved imps and calls write(t) on each, then returns.

Zero listeners is legal. The example's spare_ap has none: size() is 0 and write returns without a message. That is why a monitor can always publish, whether or not this bench uses its output.

Why write is a function

A monitor samples the bus at every clock edge. If a listener could wait inside write, the monitor would be stuck in that call and miss the next transfer. Making write a function rules this out at compile time: #5 in a write gives Functions cannot contain time-controlling statements.

A listener that needs time therefore splits its work. Its write stores the packet, and a task in its own thread does the slow part. The checker environment does exactly that with a uvm_tlm_analysis_fifo, which never fills, so write always succeeds.

1. in_mon: ap.write(#1) at 10 ns

   Inside this call: the FIFO stores the handle, cov.write samples, sb.write_in queues the expected packet.

2. in_mon: write returned at 10 ns

   Zero time has passed. The monitor is free for the next edge.

3. chk: fifo.get -> #1 at 10 ns

   The checker's thread was waiting in get. It takes #1 and works for 25 ns.

4. chk: fifo.get -> #2 at 35 ns

   #2 was published at 20 ns and waited in the FIFO for 15 ns. Nobody upstream noticed.

5. chk: finished #2 at 60 ns

   The monitor dropped its objection at 50 ns, while #2 was still in work. The test waits for the checker to report both checks done, against a 200 ns deadline. Here the checks win at 60 ns and the run ends cleanly. Had the deadline won, the test would report a UVM_ERROR naming the taken and finished counts. Counting gets alone would have claimed two checks at 35 ns.

Who hears first

The test connects the scoreboard first, then coverage, then the checker. The trace shows a different order: FIFO, cov, sb. This library keeps a port's resolved imps in an associative array indexed by their full names, so delivery follows name order: uvm_test_top.chk.fifo... sorts before uvm_test_top.cov..., which sorts before uvm_test_top.sb....

That order is a detail of this implementation, not a promise of the standard. Rename cov to zcov and it hears last. A design whose result depends on which listener runs first is broken, even if it passes today.

The same holds between listeners and the publisher's next step. Every write finishes before ap.write returns, so a listener cannot see the monitor's next packet early. In this run, the checker woken through the FIFO ran only after the monitor's thread reached its next wait: trace line 5 comes after line 4.

Receiving: imps, suffixes, subscribers and exports

A listener receives through uvm_analysis_imp #(T, IMP), which calls write on its owner. One component with two analysis inputs has a problem: both imps would call the same write.

uvm_analysis_imp_decl(_in) solves it. The macro declares a new imp class, uvm_analysis_imp_in, whose write calls write_in on the owner. The scoreboard declares _in and _out and gets two imps and two methods.

Publishing through a parent works the other way round. An agent usually offers its monitor's output as its own ap. Either connect mon.ap.connect(ap) in the agent, a port-to-port link as in U3.2, or copy the handle, ap = mon.ap;, in connect_phase. With the copy, both names refer to one port object, so listeners connected to agent.ap are listeners of the monitor's port.

The checker environment shows the last row. Its analysis_export is the public input, connected inside to fifo.analysis_export. The test connects to the environment's edge and never names the FIFO. An analysis export with nothing behind it reports connection count of 0 does not meet required minimum of 1 and stops the build.

Every listener gets the same object

write passes a handle. All three listeners receive the same pkt object, and the scoreboard stores that handle as its expected packet. Change the coverage collector to mask the data in place, t.data = t.data & 8'h0f, and the run shows sb.write_in: #1 data=01.

Order does not save you. If the scoreboard heard first, it would store the handle, and the coverage collector would change the stored packet a moment later. A listener that needs a different value must make its own copy. U7.2 shows the other half of the rule: a monitor must publish a new object each time.

Try it

The first line lists the resolved imps in name order, the order the trace then follows. Note the subscriber's imp: uvm_subscriber names its analysis_export member analysis_imp.

The checker's two lines took and finished count different things: a packet taken from the FIFO is still in work for 25 ns. On success the test ends the run when finished reaches 2, at 60 ns, ten nanoseconds after the monitor dropped its objection. If the 200 ns deadline came first, it would raise CHK as a UVM_ERROR with both counts, so unfinished work fails the run instead of ending it quietly (U7.3 makes the same split between queued, in-flight and checked work).

Try it: replace the body of cov.write with t.data = t.data & 8'h0f; and rerun. The scoreboard stores the changed packet and both results mismatch. Then rename the coverage instance to zcov: the order changes, and the mismatches stay.

Check yourself

`timescale 1ns/1ns
`include "uvm_macros.svh"
import uvm_pkg::*;

string heard;

class listener extends uvm_subscriber #(int);
  `uvm_component_utils(listener)
  function new(string name, uvm_component parent); super.new(name, parent); endfunction
  function void write(int t); heard = {heard, get_name(), " "}; endfunction
endclass

class order_test extends uvm_test;
  `uvm_component_utils(order_test)
  uvm_analysis_port #(int) ap;
  listener zeta, alpha, mid;
  function new(string name, uvm_component parent); super.new(name, parent); endfunction
  function void build_phase(uvm_phase phase);
    ap    = new("ap", this);
    zeta  = listener::type_id::create("zeta", this);
    alpha = listener::type_id::create("alpha", this);
    mid   = listener::type_id::create("mid", this);
  endfunction
  function void connect_phase(uvm_phase phase);
    ap.connect(zeta.analysis_export);
    ap.connect(alpha.analysis_export);
    ap.connect(mid.analysis_export);
  endfunction
  task run_phase(uvm_phase phase);
    phase.raise_objection(this);
    ap.write(1);
    $display("%s", heard);
    phase.drop_objection(this);
  endtask
endclass

module tb;
  initial run_test("order_test");
endmodule

begin pkt c = new; c.data = t.data & 8'h0f; hits[c.data]++; end

seen.push_back(t); hits[t.data[3:0]]++;

hits[t.data[7:4]]++;

t.data = t.data & 8'h0f; hits[t.data]++;

#250;

#90;

#25;

#60;