A DMA transfer that starts once the CPU configures a control register, and an interrupt that fires when it completes, looks like exactly the kind of cross-block scenario a virtual sequence exists for. But a C test can already configure that register and poll for that interrupt through the register model on its own - that flow is already orchestrated, by the CPU, not by SV. Reaching for a virtual sequence to replicate what the processor running firmware already does isn't just extra work; it tests something different from what the scenario was supposed to prove. The real question for a virtual sequence at SoC level isn't how to write one - it's whether this particular scenario needs one at all.

15 min read | Intermediate Level

What You'll Learn

  • Why a cross-block scenario the CPU can already drive through register writes doesn't need a virtual sequence at all
  • The specific situations - bring-up, multi-block error injection, timing a polling loop can't guarantee - where a virtual sequence is genuinely the only option
  • How a virtual sequencer gets handles to each block's real sequencer, and why that wiring happens through config_db rather than TLM
  • The difference between uvm_do_on and starting a sequence explicitly, and why a test can only do the latter

The Default: The CPU Already Orchestrates This

Real firmware reaches every block in the SoC the same way: by writing and reading registers through the CPU, at the addresses defined in the SoC's shared register map. A boot sequence that configures a DMA channel, waits for it to finish, and services the resulting interrupt is not a hypothetical SV scenario built to exercise multiple blocks together - it is what the driver actually does, every time the chip boots.

If a test's whole purpose is checking that this ordinary, software-driven flow produces correct behavior, running it as a C test is not just adequate, it is the only way to test what actually matters: whether the real access pattern, on real hardware, does the right thing.

Building a virtual sequence to reconstruct the same flow in SV, sequencer by sequencer, tests something else entirely - whether the hardware behaves correctly when the testbench pretends to be firmware, which is a weaker claim, and it leaves the actual software-driven path unverified by anything. Before writing a virtual sequence for a cross-block scenario, it's worth asking plainly whether a C test could already do the job.

Where a C Test Genuinely Can't Reach

None of that makes virtual sequences unnecessary at SoC level - it means their job is smaller than orchestrating every cross-block scenario. A handful of situations are genuinely outside what a C test can provide, and those are where a virtual sequence earns its place:

  • Before there's a driver to run. Early in SoC bring-up, a block's driver may not exist yet, or may not be trustworthy enough to build a test around. A virtual sequence programming the block's registers directly is often the only way to exercise the hardware at all until firmware catches up.
  • Reserved, illegal, or error-injection combinations that span more than one block. A single block's reserved-bit or illegal-value testing already belongs in SV rather than in a C test; some of those cases only show up as an interaction between blocks - a DMA channel started while the interrupt controller is deliberately left misconfigured, for instance. No legitimate driver would ever construct that combination, so nothing about producing it belongs in C.
  • Timing a polling loop can't guarantee. A C test's timing is at the mercy of instruction fetch, cache behavior, and whatever else is running on the core - it can wait for an interrupt, but it can't reliably land an action at a specific cycle relative to a bus transaction happening on a different block. A virtual sequence synchronizing off an event or a monitor callback can hit that precise window in a way software fundamentally cannot.
  • Interactions the CPU's register writes can't shape precisely enough. A C test can already start two DMA channels back to back and get some kind of contention on the same memory region - that much is just two register writes. What it can't do is control the contention itself: whether the second channel's first beat lands on the exact same cycle as the first channel's, or arrives cleanly after, is decided by arbitration logic the CPU has no visibility into, not by the order two stores were issued. A virtual sequence synchronizing off the bus interface directly can put both transactions at a specific cycle relative to each other; a C test can only put them at a specific instruction relative to each other, which is a much looser guarantee.
  • Signals that don't run through any block-level UVC at all. Not every sequencer a virtual sequence touches is a reused block-level agent. An external bus master, a boot-mode strap, a power or reset controller, and similar interfaces exist only at the SoC level, with no block-level environment they were ever part of. A sequence driving one of those still has to synchronize with whatever the C test is doing, and the same "can the CPU already produce this on its own" question still decides whether a virtual sequence is warranted - there's just no block-level sequence being reused for it, because there was never a block-level version of that interface to begin with.

This is the same ownership question this chapter has already raised for a single register, scaled up to a whole scenario: the default is the CPU, and a virtual sequence is justified by a specific reason the CPU can't do the job - not by habit. That reasoning holds whether the sub-sequences being coordinated are reused from block-level testbenches or written fresh for an SoC-only interface.

Coordinating What's Left: One Sequencer Can't See Another

For the scenarios that do need SV-side orchestration, the underlying problem is the same regardless of which of the cases above triggered it: each block's agent only knows how to drive its own interface - one block's sequencer has no visibility into another block's sequencer, and neither can wait on something happening at the other.

If a scenario needs one block's sequence to start only after another has finished, or two sequences to run concurrently with a specific synchronization point between them, something has to hold references to both sequencers and sequence the interaction. That something is a virtual sequence running on a virtual sequencer - a sequencer that doesn't drive any interface itself, and exists purely to hold handles to the sequencers that do.

A large SoC integrates many block-level environments, and some of those blocks may already have their own virtual sequencer coordinating multiple agents internally. That doesn't have to be flattened away - an SoC-level virtual sequencer can hold a handle to a block's virtual sequencer the same way it holds a handle to a plain sequencer, and start block-level virtual sequences on it directly. A scenario that only needs one block's own internal coordination stays inside that block's virtual sequencer; only a scenario that genuinely crosses block boundaries needs to go through the SoC-level one, so the hierarchy grows with how many blocks a given scenario actually touches, not with the total number of blocks in the chip.

Declaring the Virtual Sequencer

A virtual sequencer is an ordinary uvm_sequencer subclass, except its member variables are handles to other sequencers instead of transaction types:


class soc_virtual_sequencer extends uvm_sequencer;
  `uvm_component_utils(soc_virtual_sequencer)

  cpu_sequencer    cpu_sqr;
  dma_sequencer    dma_sqr;
  uvm_sequencer #(reg_bus_txn) reg_sqr;

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

A virtual sequence that runs on this sequencer needs typed access to those handles, not just the base m_sequencer every sequence inherits.

The uvm_declare_p_sequencer(SEQUENCER) macro is what provides that: it declares a p_sequencer handle of the given type, and in the sequence's pre_start() it $casts m_sequencer into it - so if this sequence is ever accidentally started on the wrong sequencer type, the cast fails and the test errors out immediately instead of silently working with the wrong handle.


class dma_transfer_vseq extends uvm_sequence;
  `uvm_object_utils(dma_transfer_vseq)
  `uvm_declare_p_sequencer(soc_virtual_sequencer)

  task body();
    cpu_config_seq   cfg_seq;
    dma_start_seq    dma_seq;
    cpu_poll_seq     poll_seq;

    cfg_seq = cpu_config_seq::type_id::create("cfg_seq");
    cfg_seq.start(p_sequencer.cpu_sqr);

    dma_seq = dma_start_seq::type_id::create("dma_seq");
    dma_seq.start(p_sequencer.dma_sqr);

    poll_seq = cpu_poll_seq::type_id::create("poll_seq");
    poll_seq.start(p_sequencer.cpu_sqr);
  endtask
endclass
soc_virtual_sequencer holds handles to the CPU, DMA and register sequencers, set through uvm_config_db; dma_transfer_vseq runs on it and starts cpu_config_seq on cpu_sqr, then dma_start_seq on dma_sqr, then cpu_poll_seq

Reaching for m_sequencer directly and casting it by hand in every sequence works too, but it's undocumented internal UVM state rather than a public API. uvm_declare_p_sequencer does the same cast in one place, with a clear fatal message if it ever fails - there's no real reason to write that cast yourself.

If the basic mechanics of a virtual sequencer - declaring one, starting sub-sequences on it - are still unfamiliar, ChipVerify's virtual sequence walkthrough is a good place to review them before continuing; this article assumes that part is already comfortable.

Wiring the Real Sequencers In

The virtual sequencer's handles have to be pointed at the actual sequencers living inside each block's agent, and that connection is made through uvm_config_db, not a TLM port - a virtual sequencer isn't part of the transaction-level connections between agents and their environments, it just needs a reference to each sequencer object.

Each block's environment sets its sequencer into the config_db during connect_phase(), using a path the virtual sequencer's environment knows to look under:


// inside dma_agent's containing environment
function void connect_phase(uvm_phase phase);
  uvm_config_db#(dma_sequencer)::set(this, "*", "dma_sqr", dma_agt.sqr);
endfunction

// inside the top-level SoC environment, after all sub-environments exist
function void end_of_elaboration_phase(uvm_phase phase);
  if (!uvm_config_db#(dma_sequencer)::get(this, "", "dma_sqr", v_sqr.dma_sqr))
    `uvm_fatal("NOVSQR", "dma_sqr handle not found in config_db")
endfunction

The retrieval happens in end_of_elaboration_phase() rather than connect_phase(). Every component's connect_phase() across the whole environment runs before any component's end_of_elaboration_phase() does, so waiting for that later phase guarantees every block's connect_phase() has already set its sequencer, regardless of which order the blocks happen to be built or connected in.

Starting Sub-Sequences: Macro vs. Explicit start()

Inside a virtual sequence's body(), a sub-sequence can be started with the uvm_do_on(seq, sqr) macro, which randomizes and starts seq on sequencer sqr in one step, or with the explicit two-line form - seq.randomize() followed by seq.start(sqr) - which is what the code above uses. Both work from inside a sequence's body().

What doesn't work is calling uvm_do_on from a test's run_phase(): the macro expects to run inside a sequence that already has a parent sequence and a sequencer context, and a test component has neither. A test that wants to kick off a virtual sequence has to construct it and call start() on the virtual sequencer explicitly, the same way any top-level sequence is started from a test.


class dma_with_interrupt_test extends uvm_test;
  `uvm_component_utils(dma_with_interrupt_test)

  soc_env         env;
  dma_transfer_vseq vseq;

  task run_phase(uvm_phase phase);
    phase.raise_objection(this);
    vseq = dma_transfer_vseq::type_id::create("vseq");
    vseq.start(env.v_sqr);
    phase.drop_objection(this);
  endtask
endclass

Sequencing Across Active and Passive Agents

Not every sequencer a virtual sequence touches drives its own bus in the traditional sense. Most SoC-level agents on real system buses stay passive, and register access from the SV side happens through whichever port is deliberately kept active for that purpose. A virtual sequence coordinating a bring-up or error-injection scenario typically drives that active debug or test-access sequencer to configure registers, while the DMA and CPU bus agents themselves stay passive and are only ever read from through their monitors - the virtual sequence doesn't hold a handle to those for driving, only the scoreboard or coverage collector downstream does.

Keeping that distinction straight in the virtual sequencer's declared handles - which member is really a driving sequencer and which is just there for something else to observe - avoids reaching for a sequencer that was never meant to be driven in the first place.

Chaining as Synchronization

In the example above, each sub-sequence's start() call blocks until that sub-sequence's body() returns, so calling them one after another already synchronizes the scenario: the DMA doesn't start until the CPU configuration sequence has finished, and the poll doesn't start until the DMA sequence has finished issuing its transfer.

That sequential chaining covers a large fraction of real virtual-sequence scenarios, because a lot of what's left after ruling out the CPU-driven cases really is "do this, then do that." A scenario that genuinely needs two things happening at once - one sequence polling while another is still in flight - needs an explicit concurrent construct instead, most commonly fork...join_none around one of the sub-sequence starts, with whatever synchronization event or semaphore the scenario actually depends on layered on top.

Common Mistakes

Mistake: Writing a virtual sequence to reconstruct a scenario a C test could already drive.

If the scenario is just configuring a block and checking the result the way firmware would, an SV virtual sequence isn't a shortcut - it's testing a different, weaker claim than the one that matters, and the C-driven path never gets exercised at all.

Mistake: Reaching for the sequence base class's internal m_sequencer handle instead of declaring a typed p_sequencer.

m_sequencer is untyped and requires a manual cast wherever it's used, with no single point of failure if the cast is wrong. uvm_declare_p_sequencer does the same cast once, with a clear fatal if the sequence ever ends up running on the wrong sequencer type.

Mistake: Retrieving a sub-sequencer handle from config_db in connect_phase() instead of end_of_elaboration_phase().

There's no guarantee every block's own connect_phase() has already set its sequencer by the time the virtual sequencer's connect_phase() runs, since phase order between sibling components isn't guaranteed within a single phase. Waiting until end_of_elaboration_phase() guarantees every connect_phase() in the environment has already completed.

Mistake: Calling uvm_do_on directly from a test component.

The macro assumes it's running inside a sequence with an established sequencer context. A test has to construct the virtual sequence and call start() on it explicitly, the same way it would start any other top-level sequence.

Summary

In this article, you learned:

  • A cross-block scenario the CPU can already drive through ordinary register writes doesn't need a virtual sequence - building one anyway tests a weaker claim and leaves the real software-driven path unverified
  • A virtual sequence earns its place for bring-up before a driver exists, multi-block error-injection or illegal-value combinations, timing a polling loop can't guarantee, interactions the CPU's programming model can't reach at all, and SoC-only interfaces with no block-level UVC behind them
  • For scenarios that do need it, a virtual sequence coordinates multiple block sequencers by holding typed handles to them, declared with uvm_declare_p_sequencer(SEQUENCER) and wired in through config_db during connect_phase()/end_of_elaboration_phase()
  • A test starts a virtual sequence with an explicit start() call, not uvm_do_on; inside the virtual sequence, sequential start() calls provide ordering for free, and concurrent scenarios need an explicit fork with its own synchronization
Did you find what you were looking for?

Quiz

Test Your Knowledge

1 of 5 Score: 0 / 5