UVM sequence layering is a way to generate stimulus for a layered protocol, where higher-level transactions are carried by lower-level ones, such as a message made of several bytes, a transfer made of packets, or a frame made of cells. Each layer gets its own sequencer and sequences. A translator sequence, running on the lower-layer sequencer, pulls items from the upper-layer sequencer and turns each one into one or more lower-layer items.
The benefit is that tests are written at the level they care about. A test that sends messages does not mention bytes, and the same message sequences keep working if the lower layer changes, for example from a serial link to a parallel bus, by swapping the translator and the agent beneath it.
8 min read | Intermediate
What You'll Learn
- Explain when to layer sequences and when to layer agents
- Write a translator sequence that pulls items from an upper sequencer
- Build the layering component that creates and starts it
- Rebuild upper-layer items from lower-layer ones on the monitoring path
Layered Protocols
Many protocols are stacked: TCP segments travel in IP packets, which travel in Ethernet frames. USB transfers consist of transactions, which consist of packets. Items at one layer relate to items at the layer below in a few ways: one-to-one, one-to-many (a message split into bytes), many-to-one (small messages packed into one frame) or many-to-many.
The UVM User's Guide gives a rule of thumb for how to model that:
- When layers are tightly bound together and always used as a stack, as in USB, use sequence layering inside a single protocol agent.
- When a protocol can be carried over different lower layers, or one lower layer carries different protocols, use agent layering: separate agents per layer, with the upper layer reusable over any lower one.
The example below is agent layering: a message protocol on top of a byte-wide interface that already has its own agent.
How the Layers Connect
On the generation path, the translator sequence runs on the lower-layer sequencer, the one that feeds the byte driver. It holds a handle to the upper-layer sequencer, and calls get_next_item() and item_done() on it just as a driver would. Between those two calls it sends the lower-layer items. The upper-layer sequencer sees the translator as an ordinary consumer, so message sequences run on it without knowing about bytes.
On the monitoring path, a reconstruction monitor subscribes to the lower-layer monitor, collects bytes, and publishes a complete message on its own analysis port.
The Items
class msg_item extends uvm_sequence_item;
rand byte unsigned payload[]; // variable-length message body
constraint c_len { payload.size() inside {[1:16]}; }
`uvm_object_utils(msg_item)
// Rest of the code (constructor, convert2string)
endclass
class byte_item extends uvm_sequence_item;
rand byte unsigned data;
`uvm_object_utils(byte_item)
// Rest of the code (constructor)
endclass
The byte protocol carries a message as a length byte followed by the payload bytes. That framing is what the translator adds and the reconstruction monitor removes.
The Translator Sequence
The translator is a normal sequence of the lower item type. Its extra member is the handle to the upper sequencer:
class msg2byte_seq extends uvm_sequence #(byte_item);
`uvm_object_utils(msg2byte_seq)
uvm_sequencer #(msg_item) up_sequencer; // set by the layering component
// Rest of the code (constructor)
virtual task body();
msg_item msg;
byte_item b;
forever begin
up_sequencer.get_next_item(msg); // blocks until an upper sequence sends a message
b = byte_item::type_id::create("b"); // length byte
start_item(b);
b.data = msg.payload.size();
finish_item(b);
foreach (msg.payload[i]) begin // one byte item per payload byte
b = byte_item::type_id::create("b");
start_item(b);
b.data = msg.payload[i];
finish_item(b);
end
up_sequencer.item_done(); // the message is fully sent
end
endtask
endclass
A new b is created for every byte, so the driver is never working with an object the sequence is about to change. The message sequence that supplied msg stays blocked in its finish_item() until item_done(), which means it resumes only when the whole message has gone out.
The Layering Component
The layering component owns the upper-layer sequencer, creates the translator, connects it, and starts it on the lower sequencer:
class msg_layering extends uvm_subscriber #(byte_item);
`uvm_component_utils(msg_layering)
uvm_sequencer #(msg_item) msg_sequencer; // test sequences run here
byte_agent m_byte_agent; // lower layer, instantiated by the env
uvm_analysis_port #(msg_item) ap; // reconstructed messages
// Rest of the code (constructor, reconstruction state)
virtual function void build_phase(uvm_phase phase);
super.build_phase(phase);
msg_sequencer = uvm_sequencer #(msg_item)::type_id::create("msg_sequencer", this);
ap = new("ap", this);
endfunction
virtual task run_phase(uvm_phase phase);
msg2byte_seq xlate = msg2byte_seq::type_id::create("xlate");
xlate.up_sequencer = msg_sequencer; // connect the layers
fork
xlate.start(m_byte_agent.m_sequencer); // runs for the whole simulation
join_none
endtask
endclass
The translator never finishes, since it waits forever for the next message. It runs without raising an objection, in a thread of its own, so it doesn't keep the test alive. The test's message sequences raise objections as usual and decide when the test ends. This is the same pattern as for a responder, described in UVM Reactive (Responder) Sequences.
Quick Check
Q: A message sequence sends two messages back to back. When does the second message's finish_item() start waiting, relative to the bytes of the first?
Show Answer
Only after the first message's finish_item() has returned, which happens when the translator calls item_done(), after the last byte of the first message. The second message therefore doesn't start until the first has been fully sent.
The Monitoring Path
The layering component is also a uvm_subscriber of the byte monitor's items, connected by the environment with m_byte_agent.m_monitor.ap.connect(m_layering.analysis_export). It rebuilds each message from the bytes it sees. Its write() function is a small state machine: expect a length, then collect that many payload bytes, then publish.
// Inside msg_layering
int unsigned remaining;
byte unsigned bytes_q[$];
bit have_length;
virtual function void write(byte_item t);
if (!have_length) begin
remaining = t.data; // first byte is the length
have_length = 1;
bytes_q.delete();
end else begin
bytes_q.push_back(t.data);
remaining--;
end
if (have_length && remaining == 0) begin
msg_item m = msg_item::type_id::create("m");
m.payload = new[bytes_q.size()];
foreach (bytes_q[i]) m.payload[i] = bytes_q[i];
ap.write(m); // a complete, observed message
have_length = 0;
end
endfunction
The scoreboard and coverage for the message layer connect to ap and work purely in terms of messages. For a protocol with more than two layers, each layer adds its own translator and reconstruction monitor.
Sequence Layering Inside One Agent
For a tightly bound stack, the same idea can live inside a single agent. The agent keeps one driver and sequencer for the lowest layer, and the higher-layer sequences are plain sequences that create lower-layer items directly, in a hierarchy of sequences. A message sequence then simply starts a byte sequence in its body(). This needs no translator, no second sequencer and no layering component, at the price that the layers can't be separated or reused over a different lower layer. Choose it when the layers will always travel together.
Common Mistakes
Mistake #1: Running the translator on the upper sequencer
The translator sends lower-layer items, so it must run on the lower-layer sequencer, the one that feeds the driver. It only reads from the upper sequencer through its handle.
Mistake #2: Raising an objection in the translator
A forever loop that raises an objection keeps the run phase open for ever. Let the message sequences in the test control objections.
Mistake #3: Reusing one lower-layer item
With finish_item() returning before the driver is necessarily finished with the object, changing an item that was already sent can corrupt it. Create a new item for each one.
Mistake #4: Forgetting item_done() on the upper sequencer
Without it the message sequence stays blocked in finish_item() and the next message never starts. Every get_next_item() needs its item_done().
Summary
In this article, you learned:
- Layering gives each protocol layer its own sequencer and sequences, so tests work at the level they care about
- Use sequence layering for tightly bound stacks and agent layering for layers that can be mixed
- A translator sequence runs on the lower sequencer and pulls items from the upper one with
get_next_item()anditem_done() - The layering component creates the upper sequencer, connects the translator and starts it without an objection
- A reconstruction monitor on the way back rebuilds upper-layer items from lower-layer ones