Layered protocols

One agent per layer

Protocols such as PCIe, USB and MIPI define a transaction layer over a link layer over a physical layer. Even a home-grown link has at least two: the frames a test reasons about and the symbols the pins carry. A layering keeps those levels apart in the bench. The byte agent stays a plain agent that knows nothing about packets, and a packet layer sits on top of it.

The layering here is one component, pkt_layering. It holds pkt_sqr, an ordinary uvm_sequencer #(pkt_item) where packet sequences run; the byte agent link; a translator sequence; and a reconstruction monitor. A real layering also exposes an analysis port per rebuilt level and carries one configuration object for its children.

The leaf agent may live inside the layering, as here, or elsewhere in the bench with the layering holding a handle. Either way the agent is unchanged, and a raw-byte test can run a byte sequence on link.sqr instead of the packet layer.

Not at the same time, though, in this design. Each byte the translator sends is arbitrated on its own, so a second byte sequence on link.sqr could slip bytes between a packet's destination, length and payload. The example has one translator and no other byte traffic. Mixing the two needs the translator to hold a lock on link.sqr for each packet (U5.2), or an intent to corrupt frames.

The translator is a sequence that behaves like a driver

The translator is started on the byte sequencer. Its start_item(it) calls name no sequencer, so its bytes go there by default; start_item also accepts a sequencer as a third argument, unused here. Towards the packet layer it plays the driver's part: it holds a handle to pkt_sqr and calls pkt_sqr.get_next_item(pkt) and pkt_sqr.item_done() on it directly. Those are the sequencer's own public tasks; a driver's seq_item_port is only a port that forwards to them. Nothing in the packet sequencer knows whether a driver or a sequence is pulling from it.

class pkt_to_bytes_seq extends uvm_sequence #(byte_item);
  uvm_sequencer #(pkt_item) up_sqr;      // the layer above
  task body();
    forever begin
      pkt_item pkt;
      up_sqr.get_next_item(pkt);         // pull one packet; its sequence waits in finish_item
      send_byte(pkt.dst);                // header: destination
      send_byte(pkt.payload.size());     // header: length
      foreach (pkt.payload[i]) send_byte(pkt.payload[i]);
      up_sqr.item_done();                // the packet is on the link: release its sequence
    end
  endtask
  task send_byte(bit [7:0] b);
    byte_item it = byte_item::type_id::create("it");
    start_item(it);
    it.data = b;
    finish_item(it);
  endtask
endclass

The layering's run_phase creates the translator, sets up_sqr, and starts it on link.sqr in a forked thread. Like the responder of U6.2 it is long-lived: a forever loop that lasts the whole run. The packet sequence that a test starts on pkt_sqr is ordinary and knows nothing about bytes.

The two upstream calls pair up exactly as in a driver. Forget item_done and the next get_next_item reports "called twice" and hands back the same packet, while the packet sequence waits in finish_item forever. Call item_done before sending the bytes and everything still arrives, but the packet sequence's finish_item no longer means "the packet is on the link".

What finish_item means one layer up

A packet with two payload bytes takes four clocks. The translator calls item_done after the fourth byte, so packet 1's finish_item returns at 35 ns. The packet sequence sees packet-level timing without knowing how many bytes each packet took.

This is the one-to-many mapping: one upstream item, several downstream items, and one upstream completion after the last of them. The upstream item stays outstanding the whole time, so its finish_item can mean "on the link".

Many-to-one: packing upstream items

Now reverse the ratio. A 16-bit link carries two bytes per transfer, so the translator must pull two upstream byte items for every downstream word. One rule of the pull side shapes the whole design: a sequencer hands out one item at a time. A second get_next_item before item_done reports an error and returns the same item again.

forever begin
  up_sqr.get_next_item(hi);
  up_sqr.item_done();              // must release hi before pulling lo
  up_sqr.get_next_item(lo);
  up_sqr.item_done();
  w = word_item::type_id::create("w");
  start_item(w);
  w.data = {hi.data, lo.data};
  finish_item(w);                  // the word transfer has completed
  rsp = byte_item::type_id::create("rsp"); rsp.set_id_info(hi); up_sqr.put(rsp);
  rsp = byte_item::type_id::create("rsp"); rsp.set_id_info(lo); up_sqr.put(rsp);
end

So the translator calls item_done on the first byte before it pulls the second. That releases the first byte's finish_item before its word exists. Handoff and completion come apart, exactly as in the pipelined driver of U6.1. The same tool joins them again: when the word's transfer completes, the translator sends each byte a response, routed by set_id_info.

The upstream sequence therefore takes the two-thread shape of U6.1, sending on one thread and collecting responses on the other. A sequence that only cares about handoff can skip responses, and then the translator should send none; otherwise they pile up in the upstream sequence's response queue.

Packing raises one decision the one-to-many case never meets. If the upstream stops after an odd byte, the translator holds half a word forever. It needs a flush rule: pad after a quiet period, or close the word on an end-of-stream marker.

Rebuilding packets in the analysis path

Stimulus goes down the layering; checking goes up. The byte monitor publishes every byte it sees on the far side of the link, which suits a byte-link scoreboard. A packet scoreboard needs packets, so the layering adds a reconstruction monitor.

1. The monitor publishes

   The byte monitor owns a uvm_analysis_port #(byte_item) named ap and calls ap.write(b) for every byte. The call returns at once and takes no simulation time.

2. Every connected subscriber receives it

   write loops over everything connected to the port and calls each one's write(b) with the same handle. Nothing is queued or copied.

3. A subscriber implements write

   uvm_subscriber #(byte_item) is a component with one input, analysis_export, and one function to fill in, write(byte_item t). The layering connects them with link.mon.ap.connect(pkt_mon.analysis_export).

That is all this lesson needs from analysis ports; U7.2 covers them fully, including FIFOs for slower consumers. The reconstruction monitor's write runs a small state machine over the byte stream. Byte 1 is the destination and byte 2 the length. The next len bytes are the payload, and after the last one the monitor publishes a pkt_item on its own analysis port.

The monitor rebuilds from observed bytes, never from the translator's knowledge of what it sent. If the link dropped or duplicated a byte, the rebuilt packets would differ from the sent ones, and that is exactly what a packet-level comparison should catch. U8 builds the scoreboards that would consume the rebuilt packets. This parser trusts the length byte. A bench that injects malformed frames, as the hook's corrupt-frame test would, first needs a framing rule, such as resynchronising on a marker.

task run_phase(uvm_phase phase);
  forever begin
    seq_item_port.get_next_item(pkt);
    drive_byte(pkt.dst);
    drive_byte(pkt.payload.size());
    foreach (pkt.payload[i]) drive_byte(pkt.payload[i]);
    seq_item_port.item_done();
  end
endtask

up_sqr.get_next_item(pkt);
send_byte(pkt.dst);
send_byte(pkt.payload.size());
foreach (pkt.payload[i]) send_byte(pkt.payload[i]);
up_sqr.item_done();

Where each piece is created

Each extra layer adds one sequencer, one translator and one reconstruction monitor, each knowing only its neighbours. A change to the byte format then touches one translator and one monitor.

The translator ends the way the responder of U6.2 does: its forever loop is killed when the run phase ends. A packet half-sent at that moment is an interrupted transaction that nobody checks. So the test drops its objection only when the reconstruction monitor has rebuilt every packet it sent, as the example does with wait (layering.pkt_mon.packets == 2).

Try it

Read the three voices. The byte driver logs one byte per clock: destination, length, then the payload. The translator logs when it has sent a whole packet and calls item_done, and the packet sequence's finish_item returns in the same time step, at 35 ns and 85 ns. The packet sequence never mentions bytes.

The reconstruction monitor logs one clock after the last byte of each packet, because the link registers each byte before the byte monitor sees it. Its rebuilt packets match what was sent: four bytes for packet 1, five for packet 2.

Try adding a third packet with one payload byte and predict every line before running. Then make the translator call up_sqr.item_done() before the bytes and watch where the packet sequence's lines move.

Check yourself

`timescale 1ns/1ns
`include "uvm_macros.svh"
import uvm_pkg::*;
class byte_item extends uvm_sequence_item;
  `uvm_object_utils(byte_item)
  bit [7:0] data;
  function new(string name = "byte_item"); super.new(name); endfunction
endclass
class word_item extends uvm_sequence_item;
  `uvm_object_utils(word_item)
  bit [15:0] data;
  function new(string name = "word_item"); super.new(name); endfunction
endclass
// The word link takes 20 ns per word.
class word_driver extends uvm_driver #(word_item);
  `uvm_component_utils(word_driver)
  bit [15:0] words[$];
  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);
      #20;
      words.push_back(req.data);
      seq_item_port.item_done();
    end
  endtask
endclass
// Many-to-one: two upstream bytes become one downstream word.
class pack_seq extends uvm_sequence #(word_item);
  `uvm_object_utils(pack_seq)
  uvm_sequencer #(byte_item) up_sqr;
  function new(string name = "pack_seq"); super.new(name); endfunction
  task body();
    forever begin
      byte_item hi, lo, rsp;
      word_item w;
      up_sqr.get_next_item(hi);
      up_sqr.item_done();                 // only one item may be outstanding: release before the next pull
      up_sqr.get_next_item(lo);
      up_sqr.item_done();
      w = word_item::type_id::create("w");
      start_item(w);
      w.data = {hi.data, lo.data};
      finish_item(w);                     // the word transfer has completed
      rsp = byte_item::type_id::create("rsp"); rsp.set_id_info(hi); up_sqr.put(rsp);
      rsp = byte_item::type_id::create("rsp"); rsp.set_id_info(lo); up_sqr.put(rsp);
    end
  endtask
endclass
class byte_seq extends uvm_sequence #(byte_item);
  `uvm_object_utils(byte_seq)
  int handed[$], completed[$];
  function new(string name = "byte_seq"); super.new(name); endfunction
  task body();
    bit [7:0] values[6] = '{8'h11, 8'h22, 8'h33, 8'h44, 8'h55, 8'h66};
    fork
      foreach (values[i]) begin
        byte_item b = byte_item::type_id::create("b");
        start_item(b);
        b.data = values[i];
        finish_item(b);                   // handed off: the translator has pulled it
        handed.push_back($time);
      end
      repeat (6) begin
        get_response(rsp);                // completed: its word transfer is done
        completed.push_back($time);
      end
    join
  endtask
endclass
class my_test extends uvm_test;
  `uvm_component_utils(my_test)
  uvm_sequencer #(byte_item) up_sqr;
  uvm_sequencer #(word_item) down_sqr;
  word_driver drv;
  function new(string name, uvm_component parent); super.new(name, parent); endfunction
  function void build_phase(uvm_phase phase);
    up_sqr = uvm_sequencer #(byte_item)::type_id::create("up_sqr", this);
    down_sqr = uvm_sequencer #(word_item)::type_id::create("down_sqr", this);
    drv = word_driver::type_id::create("drv", this);
  endfunction
  function void connect_phase(uvm_phase phase);
    drv.seq_item_port.connect(down_sqr.seq_item_export);
  endfunction
  task run_phase(uvm_phase phase);
    pack_seq xl = pack_seq::type_id::create("xl");
    byte_seq seq = byte_seq::type_id::create("seq");
    xl.up_sqr = up_sqr;
    phase.raise_objection(this);
    fork xl.start(down_sqr); join_none
    seq.start(up_sqr);
    $display("words %h %h %h; handed off %0d %0d %0d %0d %0d %0d; completed %0d %0d %0d %0d %0d %0d",
             drv.words[0], drv.words[1], drv.words[2],
             seq.handed[0], seq.handed[1], seq.handed[2], seq.handed[3], seq.handed[4], seq.handed[5],
             seq.completed[0], seq.completed[1], seq.completed[2], seq.completed[3], seq.completed[4], seq.completed[5]);
    phase.drop_objection(this);
  endtask
endclass
module tb;
  initial run_test("my_test");
endmodule

up_sqr.get_next_item(pkt);
up_sqr.item_done();
send_byte(pkt.dst);
send_byte(pkt.payload.size());
foreach (pkt.payload[i]) send_byte(pkt.payload[i]);

up_sqr.get_next_item(pkt);
send_byte(pkt.dst);
send_byte(pkt.payload.size());
foreach (pkt.payload[i]) send_byte(pkt.payload[i]);
up_sqr.item_done();

up_sqr.get_next_item(pkt);
send_byte(pkt.dst);
send_byte(pkt.payload.size());
foreach (pkt.payload[i]) send_byte(pkt.payload[i]);

up_sqr.get(pkt);
send_byte(pkt.dst);
send_byte(pkt.payload.size());
foreach (pkt.payload[i]) send_byte(pkt.payload[i]);

Practice

• Pack bytes into words, and flush the odd one Implement · Hard