TLM 1.0: Ports, Exports, Imps

// ── PRODUCER — declares a put_port ────────────────────────────────────
class apb_monitor extends uvm_monitor;
    `uvm_component_utils(apb_monitor)
 
    // Port: "I need someone to receive my transactions"
    uvm_blocking_put_port #(apb_seq_item) put_port;
 
    function void build_phase(uvm_phase phase);
        super.build_phase(phase);
        put_port = new("put_port", this);  // ports use new(), not factory create()
    endfunction
 
    task run_phase(uvm_phase phase);
        apb_seq_item txn;
        forever begin
            collect_transaction(txn);       // observe bus, build transaction object
            put_port.put(txn);              // push to whoever is connected
        end
    endtask
    task collect_transaction(ref apb_seq_item txn); /* ... */ endtask
endclass
 
// ── CONSUMER — declares a put_imp and implements put() ────────────────
class my_scoreboard extends uvm_scoreboard;
    `uvm_component_utils(my_scoreboard)
 
    // Imp: "I will respond to put() calls"
    // Second parameter = this class (so put() is called on THIS component)
    uvm_blocking_put_imp #(apb_seq_item, my_scoreboard) put_export;
 
    function void build_phase(uvm_phase phase);
        super.build_phase(phase);
        put_export = new("put_export", this);
    endfunction
 
    // This task is called by the TLM framework when monitor calls put_port.put()
    task put(apb_seq_item txn);
        `uvm_info("SCB", $sformatf("Received txn: addr=0x%0h", txn.addr), UVM_MEDIUM)
        check_transaction(txn);
    endtask
    task check_transaction(apb_seq_item txn); /* ... */ endtask
endclass
 
// ── CONNECTION — in the parent component's connect_phase ──────────────
class my_env extends uvm_env;
    apb_monitor    mon;
    my_scoreboard  scb;
 
    function void connect_phase(uvm_phase phase);
        super.connect_phase(phase);
        mon.put_port.connect(scb.put_export);   // PORT connects to IMP
    endfunction
endclass

// ── INITIATOR — calls get() to request a transaction ──────────────────
class my_consumer extends uvm_component;
    `uvm_component_utils(my_consumer)
 
    uvm_blocking_get_port #(apb_seq_item) get_port;
 
    function void build_phase(uvm_phase phase);
        super.build_phase(phase);
        get_port = new("get_port", this);
    endfunction
 
    task run_phase(uvm_phase phase);
        apb_seq_item txn;
        forever begin
            get_port.get(txn);   // blocks until producer provides a transaction
            process(txn);
        end
    endtask
    task process(apb_seq_item txn); /* ... */ endtask
endclass
 
// ── TARGET — implements get() ──────────────────────────────────────────
class my_producer extends uvm_component;
    `uvm_component_utils(my_producer)
 
    uvm_blocking_get_imp #(apb_seq_item, my_producer) get_export;
    apb_seq_item txn_queue[$];
 
    function void build_phase(uvm_phase phase);
        super.build_phase(phase);
        get_export = new("get_export", this);
    endfunction
 
    // Called by TLM when consumer calls get_port.get()
    task get(output apb_seq_item txn);
        wait (txn_queue.size() > 0);   // block until item available
        txn = txn_queue.pop_front();
    endtask
endclass

// ── connect_phase: correct placement ──────────────────────────────────
class my_env extends uvm_env;
    apb_monitor   mon;
    my_scoreboard scb;
 
    // build_phase: create components
    function void build_phase(uvm_phase phase);
        super.build_phase(phase);
        mon = apb_monitor::type_id::create("mon", this);
        scb = my_scoreboard::type_id::create("scb", this);
    endfunction
 
    // connect_phase: wire up TLM — called AFTER all build_phases complete
    function void connect_phase(uvm_phase phase);
        super.connect_phase(phase);
        mon.put_port.connect(scb.put_export);   // ← correct place
    endfunction
endclass
 
// ── Checking port connectivity ────────────────────────────────────────
// UVM resolves bindings during END_OF_ELABORATION, and uvm_port_base checks
// each port's connection count against its min_size. A shortfall is reported
// as a UVM_ERROR with the id "Connection Error" - not a fatal, and not during
// start_of_simulation:
//
//   UVM_ERROR @ 0: reporter [Connection Error] connection count of 0 does not
//                  meet required minimum of 1
//
// The distinction matters when you go looking for it: grepping for UVM_FATAL
// finds nothing, and the run continues past the error rather than stopping.
//
// CRUCIALLY, this check only fires for ports whose min_size is non-zero.
// uvm_analysis_port is constructed with min_size = 0, because broadcasting to
// zero subscribers is legal - so an unconnected analysis port passes every
// connectivity check UVM performs. That asymmetry is the subject of the Debug
// Lab in section 10b.

// ── Non-blocking put: try without blocking ────────────────────────────
uvm_nonblocking_put_port #(apb_seq_item) nb_put_port;
 
task run_phase(uvm_phase phase);
    apb_seq_item txn;
    forever begin
        @(posedge vif.clk);
        if (nb_put_port.can_put()) begin   // check before trying — function, no time
            build_txn(txn);
            if (!nb_put_port.try_put(txn))  // returns 0 if target is busy — function
                `uvm_warn("TLM", "try_put failed — target busy")
        end
    end
endtask
 
// ── Implementation of non-blocking interface ───────────────────────────
// Must implement BOTH can_put() and try_put() when using uvm_nonblocking_put_imp
function bit can_put();
    return (queue.size() < 10);   // 1 = there is space, 0 = full
endfunction
 
function bit try_put(apb_seq_item txn);
    if (queue.size() >= 10) return 0;   // 0 = rejected
    queue.push_back(txn);
    return 1;                             // 1 = accepted
endfunction

// ── DRIVER — uses seq_item_port (inherited from uvm_driver) ──────────
class apb_driver extends uvm_driver #(apb_seq_item);
    `uvm_component_utils(apb_driver)
    // uvm_driver already declares:
    //   uvm_seq_item_pull_port #(REQ, RSP) seq_item_port;
 
    task run_phase(uvm_phase phase);
        apb_seq_item req;
        forever begin
            // Pull: blocks until sequencer has an item for us
            seq_item_port.get_next_item(req);
 
            // Drive the DUT signals based on req
            @(posedge vif.clk);
            vif.paddr   = req.addr;
            vif.pwdata  = req.data;
            vif.pwrite  = req.write;
            vif.psel    = 1;
            vif.penable = 1;
            @(posedge vif.clk iff vif.pready);
 
            // Signal completion — sequencer can release the item
            seq_item_port.item_done();
            // Optional: fill response fields before item_done if RSP != REQ
        end
    endtask
endclass
 
// ── SEQUENCER — instantiated, connected in the agent ──────────────────
class apb_agent extends uvm_agent;
    `uvm_component_utils(apb_agent)
 
    apb_driver                            drv;
    uvm_sequencer #(apb_seq_item)         seqr;
 
    function void build_phase(uvm_phase phase);
        super.build_phase(phase);
        drv  = apb_driver::type_id::create("drv", this);
        seqr = uvm_sequencer#(apb_seq_item)::type_id::create("seqr", this);
    endfunction
 
    function void connect_phase(uvm_phase phase);
        super.connect_phase(phase);
        // Connect driver's pull port to sequencer's export
        drv.seq_item_port.connect(seqr.seq_item_export);
    endfunction
endclass
 
// ── get_next_item() vs try_next_item() ────────────────────────────────
//   get_next_item(req)  — blocks until item available (most common)
//   try_next_item(req)  — returns null if no item available (non-blocking)
//   item_done()         — must be called after processing (always)
//   item_done(rsp)      — optional response field back to sequence

// ── TLM Rules ─────────────────────────────────────────────────────────
//
//  1. PORT declares "I initiate"   IMP declares "I respond"
//  2. PORT connects to IMP or EXPORT — never PORT to PORT
//  3. All .connect() calls go in connect_phase(), not build_phase()
//  4. Ports with min_connections > 0 must be connected — fatal if not
//  5. Both PORT and IMP are parameterised by T — types must match exactly
//  6. IMP second parameter is the component class that implements the method
//  7. Analysis ports support fanout; all other ports are point-to-point
//  8. For seqr-driver: always call item_done() after get_next_item()
 
// ── Naming convention (used in all UVM VIPs) ─────────────────────────
// Ports ending in _port are initiator side (driver, monitor's output)
// Ports ending in _export are target side (scoreboard's input face)
// Despite name: uvm_blocking_put_imp IS the export for the scoreboard
 
// ── Minimum required code to add TLM to a component ──────────────────
 
// Producer side:
uvm_blocking_put_port #(my_txn) put_port;
// in build_phase:
put_port = new("put_port", this);
// in run_phase:
put_port.put(txn);
 
// Consumer side:
uvm_blocking_put_imp #(my_txn, my_consumer) put_export;
// in build_phase:
put_export = new("put_export", this);
// implement the method:
task put(my_txn txn); /* process txn */ endtask
 
// Connection (in parent component's connect_phase):
producer.put_port.connect(consumer.put_export);

// ── Transaction type ──────────────────────────────────────────────────
class apb_txn extends uvm_sequence_item;
    `uvm_object_utils(apb_txn)
    rand logic [31:0] addr;
    rand logic [31:0] data;
    rand logic        write;
    function new(string name = "apb_txn"); super.new(name); endfunction
endclass
 
// ── Monitor: observes bus, pushes transactions ─────────────────────────
class apb_monitor extends uvm_monitor;
    `uvm_component_utils(apb_monitor)
    uvm_blocking_put_port#(apb_txn) put_port;
 
    function void build_phase(uvm_phase phase);
        super.build_phase(phase);
        put_port = new("put_port", this); // ports use new(), NOT factory create()
    endfunction
 
    task run_phase(uvm_phase phase);
        apb_txn txn;
        forever begin
            @(posedge vif.clk iff (vif.psel && vif.penable && vif.pready));
            txn       = apb_txn::type_id::create("txn");
            txn.addr  = vif.paddr;
            txn.data  = vif.pwrite ? vif.pwdata : vif.prdata;
            txn.write = vif.pwrite;
            put_port.put(txn); // blocks until scoreboard's put() returns
        end
    endtask
endclass
 
// ── Scoreboard: implements put() — receives transactions ──────────────
class apb_scoreboard extends uvm_scoreboard;
    `uvm_component_utils(apb_scoreboard)
    uvm_blocking_put_imp#(apb_txn, apb_scoreboard) put_export;
    // ↑ Second param is THIS class — put() is called on this component
 
    function void build_phase(uvm_phase phase);
        super.build_phase(phase);
        put_export = new("put_export", this);
    endfunction
 
    task put(apb_txn txn); // TLM calls this when monitor does put_port.put()
        `uvm_info("SCB", $sformatf("Checking: addr=0x%0h data=0x%0h write=%0b",
            txn.addr, txn.data, txn.write), UVM_MEDIUM)
        // ... compare against expected ...
    endtask
endclass
 
// ── Env: creates and connects — note connect_phase, NOT build_phase ───
class apb_env extends uvm_env;
    `uvm_component_utils(apb_env)
    apb_monitor    mon;
    apb_scoreboard scb;
 
    function void build_phase(uvm_phase phase);
        super.build_phase(phase);
        mon = apb_monitor::type_id::create("mon", this);
        scb = apb_scoreboard::type_id::create("scb", this);
    endfunction
 
    function void connect_phase(uvm_phase phase);
        super.connect_phase(phase);
        mon.put_port.connect(scb.put_export); // port → imp: the only valid connection
    endfunction
endclass

// ── Inside the agent: expose monitor's put_port as an agent-level port ─
class apb_agent extends uvm_agent;
    `uvm_component_utils(apb_agent)
    apb_driver     drv;
    apb_monitor    mon;
    uvm_sequencer#(apb_txn) seqr;
 
    // Agent re-exports the monitor's TLM port as its own interface
    // Env connects to apb_agent.mon_port — not to mon.put_port directly
    uvm_blocking_put_port#(apb_txn) mon_port; // ← this IS the agent's outward face
 
    function void build_phase(uvm_phase phase);
        super.build_phase(phase);
        drv  = apb_driver::type_id::create("drv",  this);
        mon  = apb_monitor::type_id::create("mon",  this);
        seqr = uvm_sequencer#(apb_txn)::type_id::create("seqr", this);
        mon_port = new("mon_port", this); // agent's own port wrapping mon's port
    endfunction
 
    function void connect_phase(uvm_phase phase);
        super.connect_phase(phase);
        drv.seq_item_port.connect(seqr.seq_item_export);
        // Chain the agent's port to monitor's port
        // The actual IMP is in the scoreboard — connected from env
        mon.put_port.connect(mon_port); // ← port-to-port OK here? Actually use analysis port for this pattern
    endfunction
endclass
 
// NOTE: The cleaner industry approach is to use uvm_analysis_port for monitors
// (covered in Module 13) — it supports fan-out and no direct connection chain needed.
// The above pattern is valid for blocking put TLM where exactly one subscriber exists.
 
// ── Env connects agent's exposed port to scoreboard ────────────────────
function void connect_phase(uvm_phase phase);
    super.connect_phase(phase);
    // Env sees apb_agent.mon_port — doesn't know about mon directly
    apb_agent.mon_port.connect(scb.put_export);
endfunction

// ── Scoreboard with two separate TLM ports (one per channel) ─────────
class mem_scoreboard extends uvm_scoreboard;
    `uvm_component_utils(mem_scoreboard)
 
    // Two separate put_imps — one for write transactions, one for read results
    // Can't use two uvm_blocking_put_imp with the same name on same class without macro
    // Solution: use uvm_tlm_analysis_fifo (Module 14) OR the analysis port pattern
    // For blocking put with two ports, use uvm_tlm_*_imp_decl macros:
 
    `uvm_blocking_put_imp_decl(_wr)  // declares uvm_blocking_put_imp_wr
    `uvm_blocking_put_imp_decl(_rd)  // declares uvm_blocking_put_imp_rd
 
    uvm_blocking_put_imp_wr#(mem_txn, mem_scoreboard) wr_export;
    uvm_blocking_put_imp_rd#(mem_txn, mem_scoreboard) rd_export;
 
    mem_txn expected_q[$];  // write ops stored as expected reads
 
    function void build_phase(uvm_phase phase);
        super.build_phase(phase);
        wr_export = new("wr_export", this);
        rd_export = new("rd_export", this);
    endfunction
 
    // Called when write monitor does wr_port.put(txn)
    task put_wr(mem_txn txn);
        expected_q.push_back(txn);
        `uvm_info("SCB", $sformatf("Expected: addr=0x%0h data=0x%0h",
            txn.addr, txn.data), UVM_HIGH)
    endtask
 
    // Called when read monitor does rd_port.put(txn)
    task put_rd(mem_txn actual);
        mem_txn expected;
        if (expected_q.size() == 0) begin
            `uvm_error("SCB", "Read response received but no pending expected")
            return;
        end
        expected = expected_q.pop_front();
        if (actual.data !== expected.data)
            `uvm_error("SCB", $sformatf("MISMATCH addr=0x%0h exp=0x%0h got=0x%0h",
                actual.addr, expected.data, actual.data))
        else
            `uvm_info("SCB", "MATCH", UVM_HIGH)
    endtask
endclass
 
// ── Env connection ─────────────────────────────────────────────────────
function void connect_phase(uvm_phase phase);
    super.connect_phase(phase);
    wr_mon.put_port.connect(scb.wr_export);  // write channel
    rd_mon.put_port.connect(scb.rd_export);  // read channel
endfunction

// ❌ DEADLOCK — item_done() never called ──────────────────────────────
task run_phase(uvm_phase phase);
    apb_txn req;
    forever begin
        seq_item_port.get_next_item(req);   // blocks → gets item 1 → continues
        @(posedge vif.clk);
        vif.paddr  <= req.addr;
        vif.pwdata <= req.data;
        @(posedge vif.clk iff vif.pready);
        // FORGOT item_done() here!
        // Second call to get_next_item() → sequencer sees item 1 still "in flight"
        // → deadlock: sequencer holds item 1 locked, never sends item 2
        // → simulation runs until UVM_TIMEOUT fires (typically 1ms later)
    end
endtask
// UVM_FATAL timeout: simulation timed out after 1ms with objection held
// No useful stack trace — the real cause is inside get_next_item()
 
// ✓ CORRECT — item_done() after every get_next_item() ─────────────────
task run_phase(uvm_phase phase);
    apb_txn req;
    forever begin
        seq_item_port.get_next_item(req);
        @(posedge vif.clk);
        vif.paddr  <= req.addr;
        vif.pwdata <= req.data;
        @(posedge vif.clk iff vif.pready);
        seq_item_port.item_done();  // ← mandatory: releases item 1, sequencer sends item 2
    end
endtask
 
// Rule: every get_next_item() must be paired with exactly one item_done()
// Think of it as a lock: get_next_item() acquires, item_done() releases.
// Missing item_done() leaves the lock held forever.

// ❌ WRONG — TLM connect in build_phase ───────────────────────────────
class apb_env extends uvm_env;
    function void build_phase(uvm_phase phase);
        super.build_phase(phase);
        mon = apb_monitor::type_id::create("mon", this);
        scb = apb_scoreboard::type_id::create("scb", this);
        mon.put_port.connect(scb.put_export); // ← WRONG — connect in build_phase
    endfunction
endclass
// Possible result 1: null handle if scb.put_export not yet constructed
// Possible result 2: UVM_FATAL: connect called before end_of_elaboration
// Either way, the simulation doesn't run.
 
// ✓ CORRECT — create in build_phase, connect in connect_phase ─────────
class apb_env extends uvm_env;
    function void build_phase(uvm_phase phase);
        super.build_phase(phase);
        mon = apb_monitor::type_id::create("mon", this);
        scb = apb_scoreboard::type_id::create("scb", this);
        // NO connect here — just create
    endfunction
 
    function void connect_phase(uvm_phase phase);
        super.connect_phase(phase);
        mon.put_port.connect(scb.put_export); // ← CORRECT place
        // By now: ALL build_phases in the hierarchy have completed
        // All components and their ports are fully constructed
    endfunction
endclass

// ❌ WRONG — using base class as second parameter ─────────────────────
class my_scoreboard extends uvm_scoreboard;
    // Second param = uvm_scoreboard → tries to call put() on uvm_scoreboard
    // uvm_scoreboard does not have a put() method → compile error
    uvm_blocking_put_imp#(apb_txn, uvm_scoreboard) put_export; // ← WRONG
    task put(apb_txn txn); /* ... */ endtask
endclass
// Error: 'put' is not a member of 'uvm_scoreboard'
 
// ❌ WRONG — trying to create a put_imp for a different class ─────────
uvm_blocking_put_imp#(apb_txn, other_class) put_export;
// TLM will call put() on 'other_class' — but put_export is inside my_scoreboard
// The second parameter must be the class that CONTAINS this imp and implements put()
 
// ✓ CORRECT — second parameter is THIS class ──────────────────────────
class my_scoreboard extends uvm_scoreboard;
    uvm_blocking_put_imp#(apb_txn, my_scoreboard) put_export; // ← CORRECT
    // Second param = my_scoreboard → TLM calls my_scoreboard::put()
    task put(apb_txn txn); /* called by TLM framework */ endtask
endclass
 
// Rule: the second parameter of *_imp is always the class that:
// 1. Declares the imp object
// 2. Implements the corresponding method (put/get/peek)

// ❌ WRONG — two ports trying to connect to each other ────────────────
// monitor.sv:
uvm_blocking_put_port#(apb_txn) put_port;   // ← port (initiator)
 
// scoreboard.sv (WRONG — should be imp, not port):
uvm_blocking_put_port#(apb_txn) put_port;   // ← also a port — no put() implemented
 
// env.sv:
mon.put_port.connect(scb.put_port);   // ← both initiators — invalid
// Result: UVM_FATAL at start_of_simulation_phase:
// "port 'mon.put_port' has 0 connections to an implementation"
 
// ✓ CORRECT — scoreboard declares an imp, not a port ─────────────────
// scoreboard.sv:
uvm_blocking_put_imp#(apb_txn, apb_scoreboard) put_export;  // ← imp (responder)
task put(apb_txn txn); /* process */ endtask
 
// env.sv:
mon.put_port.connect(scb.put_export);   // ← port → imp: valid
 
// Memory rule:
// _port  = "I start communication" = needs someone to receive
// _imp   = "I receive communication" = implements the method
// If you're implementing put()/get()/write() → you need an _imp, not a _port

// tlm_push_demo.sv — complete runnable TLM push model demo
// Compile: vlog -sv tlm_push_demo.sv
// Run:     vsim -c work.tb_tlm_top +UVM_TESTNAME=tlm_push_test -do "run -all; quit"
 
`include "uvm_macros.svh"
import uvm_pkg::*;
 
// ── Simple transaction ─────────────────────────────────────────────────
class simple_txn extends uvm_sequence_item;
    `uvm_object_utils(simple_txn)
    int id;
    int data;
    function new(string name = "simple_txn"); super.new(name); endfunction
endclass
 
// ── Producer: pushes transactions through its put_port ─────────────────
class txn_producer extends uvm_component;
    `uvm_component_utils(txn_producer)
    uvm_blocking_put_port#(simple_txn) put_port;
 
    function new(string name, uvm_component parent);
        super.new(name, parent);
    endfunction
 
    function void build_phase(uvm_phase phase);
        super.build_phase(phase);
        put_port = new("put_port", this);
    endfunction
 
    task run_phase(uvm_phase phase);
        simple_txn txn;
        phase.raise_objection(this);
        for (int i = 0; i < 5; i++) begin
            txn      = simple_txn::type_id::create($sformatf("txn%0d",i));
            txn.id   = i;
            txn.data = (i + 1) * 16'hAA;
            `uvm_info("PROD", $sformatf("Pushing txn[%0d] data=0x%0h", i, txn.data), UVM_LOW)
            put_port.put(txn);   // blocks until consumer's put() returns
            `uvm_info("PROD", $sformatf("txn[%0d] accepted by consumer", i), UVM_LOW)
        end
        phase.drop_objection(this);
    endtask
endclass
 
// ── Consumer: implements put() ─────────────────────────────────────────
class txn_consumer extends uvm_component;
    `uvm_component_utils(txn_consumer)
    uvm_blocking_put_imp#(simple_txn, txn_consumer) put_export;
 
    function new(string name, uvm_component parent);
        super.new(name, parent);
    endfunction
 
    function void build_phase(uvm_phase phase);
        super.build_phase(phase);
        put_export = new("put_export", this);
    endfunction
 
    task put(simple_txn txn);   // called by TLM when producer calls put_port.put()
        `uvm_info("CONS", $sformatf("Received txn[%0d] data=0x%0h — processing",
            txn.id, txn.data), UVM_LOW)
        // Simulate processing time (2ns per transaction)
        #2;
    endtask
endclass
 
// ── Test: connects producer to consumer ───────────────────────────────
class tlm_push_test extends uvm_test;
    `uvm_component_utils(tlm_push_test)
    txn_producer prod;
    txn_consumer cons;
 
    function new(string name, uvm_component parent);
        super.new(name, parent);
    endfunction
 
    function void build_phase(uvm_phase phase);
        prod = txn_producer::type_id::create("prod", this);
        cons = txn_consumer::type_id::create("cons", this);
    endfunction
 
    function void connect_phase(uvm_phase phase);
        prod.put_port.connect(cons.put_export); // THE connection
    endfunction
endclass
 
module tb_tlm_top;
    initial run_test();
endmodule
 
// Expected output:
// UVM_INFO PROD: Pushing txn[0] data=0xaa — processing
// UVM_INFO CONS: Received txn[0] data=0xaa — processing
// UVM_INFO PROD: txn[0] accepted by consumer     ← put() returned after 2ns
// UVM_INFO PROD: Pushing txn[1] data=0x154
// UVM_INFO CONS: Received txn[1] data=0x154 — processing
// UVM_INFO PROD: txn[1] accepted by consumer
// ... (repeats 5 times total)
// --- UVM Report Summary ---
// UVM_INFO: 15     UVM_ERROR: 0     → PASS
//
// Key observation: producer blocks on each put() until consumer's put() returns.
// Blocking TLM is synchronous — the chain waits at each step.