Architecture Debug Checklist: Deterministic Agent Triage

Symptom-to-boundary mapping

Most architecture failures can be localized quickly by mapping symptom to boundary: mode resolution, build topology, connection links, or analysis fanout.

[UVM][AGT] symptom map

sequence hangs at finish_item
  -> drv/sqr link or item_done path

monitor counts increment, scoreboard silent
  -> analysis bridge or env fanout link

passive mode contention on pins
  -> active children built in passive mode

random null-handle errors
  -> inconsistent mode/topology construction

[AGT] triage order

1) inspect effective cfg/mode
2) inspect built component shape
3) inspect connect-phase links
4) inspect per-boundary counters
5) only then inspect protocol timing

• Start with topology checks before waveform-heavy protocol analysis.

• Use fixed triage order to avoid repeated blind debugging.

• Capture effective mode and shape per instance in logs.

Instrumentation helpers

function void report_shape();
  `uvm_info("AGT_SHAPE",
    $sformatf("path=%s mode=%s mon=%0d sqr=%0d drv=%0d ap=%0d",
      get_full_name(),
      (is_active == UVM_ACTIVE) ? "ACTIVE" : "PASSIVE",
      mon != null, sqr != null, drv != null, ap != null),
    UVM_LOW)
endfunction

function void end_of_elaboration_phase(uvm_phase phase);
  super.end_of_elaboration_phase(phase);
  report_shape();
endfunction

task architecture_smoke(my_env env);
  int sb_before = env.sb.actual_seen;
  run_one_item_sequence(env.agt.sqr);
  wait (env.sb.actual_seen > sb_before);
  `uvm_info("AGT_SMOKE", "architecture path alive", UVM_LOW)
endtask

[UVM][AGT][CHECK] counters to track

sequence:
  issued_count

driver:
  done_count

monitor:
  observed_count

scoreboard:
  actual_seen

• Use compact counters to identify first broken boundary.

• Run one-item smoke tests to validate topology quickly.

• Print shape once per instance to compare across runs.

Checklist and escalation gates

1. Cfg present and mode intent logged.

2. Built shape matches mode invariants.

3. Driver-sequencer link exists only for active mode.

4. Monitor-to-agent analysis bridge connected always.

5. Env fanout connects required subscribers.

6. Counters increment across sequence->driver->monitor->subscriber chain.

7. One-item smoke passes before protocol stress tests.

[AGT] escalation gates

Gate A: topology correct
Gate B: connectivity correct
Gate C: one-item flow correct

Only after A+B+C:
  debug protocol timing/data semantics

Key takeaways

• Checklist-driven architecture debug is faster and more reproducible.

• Most agent issues are structural and detectable before complex traffic.

• Per-boundary counters and shape dumps provide high-signal diagnostics.

• Escalate to protocol details only after topology gates pass.

Common pitfalls

• Jumping straight into protocol timing without checking architecture basics.

• No consistent checklist, causing repeated rediscovery of same failures.

• Missing shape/counter logs and relying on guesswork.

• Declaring flaky behavior instead of proving boundary health.