A UVM sequencer is the component that passes sequence items from running sequences to the driver. It is declared from the uvm_sequencer class, and the driver pulls each item from it through a port. UVM Driver built reg_driver and left one piece dangling: seq_item_port needs something to connect to before get_next_item() can ever return anything. This article builds that something and closes the connection the driver only pointed at.

9 min read | Intermediate Level

What You'll Learn

  • What a sequencer does, and why the driver-sequencer relationship is a pull, not a push
  • How to parameterize uvm_sequencer for reg_transaction
  • How to connect a sequencer to reg_driver in connect_phase
  • When a custom sequencer class is worth writing, versus instantiating uvm_sequencer directly
  • How a sequence reaches its sequencer through m_sequencer and p_sequencer

What Is a Sequencer?

A sequencer manages the flow of transactions on their way to a driver. It doesn't generate stimulus itself (that's a sequence's job, covered in UVM Sequence), and it doesn't drive any pins either (that's reg_driver's job). A sequencer sits in between, deciding when and in what order transactions reach the driver.

Position of the sequencer inside a UVM agent, next to the driver and monitor

Several sequences can run on one sequencer at the same time. When more than one of them has an item ready, the sequencer picks which one goes next, a choice described in UVM Sequence Arbitration.

A sequencer is normally one of three components inside an agent, alongside a driver and a monitor. UVM Agent builds the agent itself; for now, reg_sequencer and reg_driver are built as siblings that will eventually live inside one.

How the Pull Model Works

The relationship between a sequencer and a driver is a pull, not a push: the driver asks for a transaction when it's ready, rather than the sequencer forcing one onto the driver on its own schedule. UVM Driver already named the two sides of this connection without building either of them:

  • reg_driver declares seq_item_port, a built-in uvm_seq_item_pull_port
  • A sequencer provides seq_item_export, a built-in uvm_seq_item_pull_imp

Both of these already exist automatically: uvm_driver declares seq_item_port, and uvm_sequencer declares seq_item_export, the same way uvm_subscriber declares analysis_export automatically. The only thing left to do is connect them.

Declaring reg_sequencer

Class hierarchy of uvm_sequencer, from uvm_component through uvm_sequencer_base and uvm_sequencer_param_base

For most testbenches, including this one, there's no need to write a sequencer class at all, because uvm_sequencer already contains everything required to communicate with a driver. It only needs to be told what transaction type it's carrying:


uvm_sequencer #(reg_transaction) m_sequencer;

uvm_sequencer is declared as uvm_sequencer #(type REQ = uvm_sequence_item, RSP = REQ). Supplying just one type parameter sets both REQ and RSP to reg_transaction. That is the same outcome reg_driver already relies on, since reg_transaction carries both the request fields and the response field in a single class.

A sequencer can be parameterized with two different types, as in uvm_sequencer #(my_data, data_rsp) m_seqr0;, when requests and responses genuinely need to be different classes. reg_transaction doesn't need that, so a single type parameter is enough here.

Connecting the Sequencer to reg_driver

Both sides are built and parameterized to match. What's left is the single line that wires them together, written inside whichever component owns both. Here it is shown directly, so the connection itself is clear before the agent that will eventually own it exists:


virtual function void build_phase(uvm_phase phase);
  super.build_phase(phase);

  m_sequencer = uvm_sequencer#(reg_transaction)::type_id::create("m_sequencer", this);
  m_driver    = reg_driver::type_id::create("m_driver", this);
endfunction

virtual function void connect_phase(uvm_phase phase);
  super.connect_phase(phase);

  // Connect the driver's seq_item_port to the sequencer's seq_item_export
  m_driver.seq_item_port.connect(m_sequencer.seq_item_export);
endfunction

After this connect() call runs, reg_driver's seq_item_port.get_next_item() calls are no longer waiting on nothing: they're waiting on m_sequencer. Nothing about reg_driver needs to change to make this work; it was already written correctly, just waiting for the other end of its port to exist.

Quick Check

Q: Why is this connection made in connect_phase rather than build_phase, where m_sequencer and m_driver are created?

Show Answer

Both components have to exist before they can be connected to each other, and you can't call .connect() on a handle that hasn't been assigned yet. build_phase constructs the entire hierarchy first; connect_phase runs afterward, specifically so every component it might need to wire together is already guaranteed to exist.

When to Write a Custom Sequencer

Writing a sequencer class of your own is rarely necessary, because uvm_sequencer already does everything a sequence needs to talk to a driver. The reason to extend it anyway is the same reason to extend uvm_monitor or uvm_subscriber instead of plain uvm_component: it's recommended practice, and it gives you a place to add functionality beyond what the base class provides.


class reg_sequencer extends uvm_sequencer #(reg_transaction);

  `uvm_component_utils(reg_sequencer)

  function new(string name, uvm_component parent);
    super.new(name, parent);
  endfunction

endclass

This is functionally identical to declaring a plain uvm_sequencer #(reg_transaction). The only difference is that reg_sequencer now has its own class name, which becomes useful the moment you want to add a custom method or property a sequence might need to access.

m_sequencer and p_sequencer

A running sequence often needs to reach the sequencer it was started on. Every sequence gets a handle for this automatically, m_sequencer, set when the sequence is started. Its type is the generic base class uvm_sequencer_base, so it can only see what every sequencer has, not the members a custom class like reg_sequencer adds.

To read a custom member, the sequence declares a typed handle with the `uvm_declare_p_sequencer macro. The macro adds a variable named p_sequencer of the given type and casts m_sequencer into it when the sequence starts:


class reg_limited_sequence extends uvm_sequence #(reg_transaction);

  `uvm_object_utils(reg_limited_sequence)
  `uvm_declare_p_sequencer(reg_sequencer)

  function new(string name = "reg_limited_sequence");
    super.new(name);
  endfunction

  virtual task body();
    // max_transactions only exists in reg_sequencer, so p_sequencer is needed
    repeat (p_sequencer.max_transactions) begin
      req = reg_transaction::type_id::create("req");
      start_item(req);
      if (!req.randomize()) `uvm_error("SEQ", "Randomization failed")
      finish_item(req);
    end
  endtask

endclass
m_sequencer of type uvm_sequencer_base and p_sequencer of type reg_sequencer both point to the same sequencer object; only p_sequencer can see max_transactions

Both handles point to the same sequencer object. m_sequencer always exists and works on any sequencer; p_sequencer only exists when the macro is used, and the cast fails with a fatal error if the sequence is started on a sequencer of a different type. That dependency is why many teams pass settings through uvm_config_db instead, and keep p_sequencer for cases such as reaching the sub-sequencers of a virtual sequencer.

The name is unfortunate in one way: this article's m_sequencer is just a variable name for the sequencer instance inside the environment, unrelated to the m_sequencer handle that every sequence carries.

Common Mistakes

Mistake #1: Forgetting the connect_phase wiring

A driver and sequencer that are each individually correct still do nothing together if m_driver's seq_item_port is never connected to m_sequencer's seq_item_export. UVM does not treat the missing connection as an error during the build: seq_item_port is allowed to stay unconnected, so you only get a warning at the end of elaboration that the driver is not connected to a sequencer. The real failure comes later. The first get_next_item() call goes through a port with nothing behind it, and the simulator stops with a null handle error deep inside the UVM library, far from the line that is actually missing.

When a driver crashes on its very first get_next_item(), look for that warning in the log, then check the connect_phase of the agent.

Mistake #2: Connecting the export to the port instead of the port to the export

Wrong: m_sequencer.seq_item_export.connect(m_driver.seq_item_port);
Right: m_driver.seq_item_port.connect(m_sequencer.seq_item_export);

Why? connect() is called on the port, with the export passed as its argument, because the port is the side that requests the items. The export of a sequencer is an imp, an endpoint that is tied to its own component when it is constructed, and an imp's connect() method may not be called at all. UVM reports a UVM_ERROR saying it cannot call an imp port's connect method, and the simulation stops with a fatal error before the run phase starts.

Practice Exercise

Challenge: Add a Transaction Limit

Extend reg_sequencer with a property, max_transactions, that a sequence such as reg_limited_sequence above can read to know how many transactions it's allowed to send.

Hint

This only requires adding a plain class property to reg_sequencer; nothing about the constructor or factory registration needs to change.

Solution
class reg_sequencer extends uvm_sequencer #(reg_transaction);

  `uvm_component_utils(reg_sequencer)

  int max_transactions = 100;

  function new(string name, uvm_component parent);
    super.new(name, parent);
  endfunction

endclass
  

This is exactly the kind of addition that makes a custom sequencer worth writing in the first place. max_transactions doesn't exist on plain uvm_sequencer, so without a class of its own to belong to, a sequence would have no type-safe way to read it through p_sequencer.

Summary

In this article, you learned:

  • A sequencer manages the flow of transactions to a driver, using a pull model rather than pushing them
  • uvm_sequencer already provides seq_item_export, the matching half of a driver's seq_item_port
  • Connecting the two happens in connect_phase, after both components are built, by calling connect() on the port
  • A custom sequencer class is only necessary when a sequence needs to access something beyond what uvm_sequencer already provides
  • Every sequence has m_sequencer; `uvm_declare_p_sequencer adds a typed p_sequencer handle for custom members

Going Deeper

Did you find what you were looking for?

Quiz

Test Your Knowledge

1 of 5 Score: 0 / 5