HDL Top Structure: Deterministic Static-to-UVM Boundary

Core Contract

Keep this startup boundary deterministic, observable, and fail-fast.

Treat startup as reusable infrastructure: ownership, ordering, and liveness checks must be explicit.

[UVM][ENV] top.sv layering

layer 1: clock/reset + interfaces
layer 2: DUT and static wrappers
layer 3: startup bridge (config_db + run_test)

no scenario logic in top.sv

[UVM][ENV] boundary model

boundary A: ownership and lifecycle
boundary B: publication and path scope
boundary C: first-activity liveness proof

fix the first broken boundary first

• Document ownership and ordering assumptions in code, not only slides.

• Make startup diagnostics actionable and low-noise.

• Prefer deterministic startup defaults over convenience shortcuts.

Reference Implementation

module top;
  import uvm_pkg::*;
  `include "uvm_macros.svh"
  import tb_pkg::*;

  logic clk;
  logic rst_n;
  axi_if axi_if0(.aclk(clk), .aresetn(rst_n));

  dut u_dut(
    .clk   (clk),
    .rst_n (rst_n),
    .axi   (axi_if0)
  );

  initial clk = 0;
  always #5ns clk = ~clk;

  initial begin
    rst_n = 0;
    repeat (10) @(posedge clk);
    rst_n = 1;
  end

  initial begin
    uvm_config_db#(virtual axi_if)::set(null, "uvm_test_top.env.axi_agt*", "vif", axi_if0);
    run_test();
  end
endmodule

[ENV] implementation audit

- critical startup assumptions validated?
- missing-state paths fail immediately?
- diagnostics include component path and context?
- minimal smoke seed can exercise this boundary?

[UVM][ENV] startup observability

track timestamps/counters for:
  reset release
  first sequence launch
  first monitor publish
  first checker compare

these markers reduce triage latency dramatically

• Keep startup code simple enough to audit in code review.

• Use fatal failures for non-recoverable startup contract violations.

• Expose startup metrics in report_phase for CI artifacts.

Debug Workflow

Triage order

1. Reproduce with one seed and startup tracing enabled.

2. Verify startup boundary counters and first-activity markers.

3. Classify failure by boundary before deep waveform analysis.

4. Fix root boundary and rerun identical seed to confirm.

simv +UVM_TESTNAME=smoke_test        +UVM_VERBOSITY=UVM_LOW        +UVM_CONFIG_DB_TRACE        +UVM_OBJECTION_TRACE

[UVM][ENV] quick diagnosis

fails before build:
  run_test/factory/config publish issue

build passes, no traffic:
  reset/sequence launch gating issue

monitor active, checker idle:
  connect/subscriber pipeline issue

Key takeaways

• Top structure should express static integration only.

• Deterministic naming and layering reduce startup debug time.

• Keep startup logic centralized and reviewable.

• A deterministic startup workflow improves regression trust and team velocity.

Common pitfalls

• Pushing test policy into top.sv instead of test classes.

• Scattered startup blocks with implicit execution assumptions.

• Opaque naming that breaks path-based automation.

• Skipping startup smoke and finding setup regressions only in long runs.

Applied Patterns

Use this reusable grid before landing startup-related changes.

[UVM][ENV] startup pattern grid

contract:
  ownership + ordering + liveness documented

implementation:
  fail-fast checks and deterministic defaults

observability:
  milestone counters and concise logs

verification:
  smoke seed + boundary-first triage + closure checklist

function void startup_health_report();
  `uvm_info("STARTUP_SUMMARY",
    $sformatf("rst=%0t seq=%0t mon=%0t cmp=%0t",
      first_reset_release_time,
      first_sequence_start_time,
      first_monitor_publish_time,
      first_scoreboard_compare_time),
    UVM_LOW)
endfunction

• Treat startup updates as infrastructure API changes.

• Keep code and checklist language aligned.

• Require stable startup summaries in regression logs.