Failure Classification Buckets: Symptom Before Root Cause

The five-bucket model

Every UVM regression failure is one of: completion, checking, config, stimulus, or prediction . Misclassification wastes hours — classify in the first five minutes.

[DEBUG][SENIOR][UVM] bucket decision tree

sim still running at timeout?
  yes -> COMPLETION (objections / handshake / drain)

UVM_ERROR from scoreboard/checker?
  yes -> CHECKING (first mismatch txn)

uvm_config_db::get failed / null handle?
  yes -> CONFIG (path / name / type / timing)

zero transactions / instant pass?
  yes -> STIMULUS (run_phase / vif / reset / seq start)

RAL mirror != observed / predict gap?
  yes -> PREDICTION (predictor / adapter / auto-predict)

typedef enum {
  BUCKET_COMPLETION,
  BUCKET_CHECKING,
  BUCKET_CONFIG,
  BUCKET_STIMULUS,
  BUCKET_PREDICTION
} debug_bucket_e;

function debug_bucket_e classify_from_log(string last_msg);
  if (last_msg.find("objection") != -1) return BUCKET_COMPLETION;
  if (last_msg.find("MISMATCH") != -1)  return BUCKET_CHECKING;
  if (last_msg.find("config_db") != -1)   return BUCKET_CONFIG;
  if (last_msg.find("RAL") != -1)         return BUCKET_PREDICTION;
  return BUCKET_STIMULUS;
endfunction

Key takeaways

• Five buckets cover essentially all UVM regression failures.

• The bucket determines tooling — not personal debug preference.

• Write the bucket on the bug ticket before any deep investigation.

Common pitfalls

• Labeling a hang as 'RTL bug' without checking completion bucket first.

• Treating config_db failures as checking failures.

• Skipping classification because 'it looks like last week's bug'.

Bucket signatures and evidence

Each bucket has recognizable log signatures. Train yourself to grep for these before opening a waveform viewer.

Signature cheat sheet

[DEBUG][SENIOR][UVM] log signatures

COMPLETION:
  - sim timeout with UVM_FATAL or hang
  - last msg: "waiting get_next_item" or phase never ends
  - +UVM_OBJECTION_TRACE shows non-zero count

CHECKING:
  - UVM_ERROR from scoreboard/compare
  - "expected X got Y" on a transaction field

CONFIG:
  - "config_db::get failed for ..."
  - null virtual interface handle at time 0

STIMULUS:
  - test passes in <1us with zero traffic
  - run_phase never logged / sequence never started

PREDICTION:
  - uvm_reg predict/mirror mismatch
  - register read OK on bus but mirror stale

• Completion: grep for objection count and get_next_item stalls.

• Checking: grep UVM_ERROR and scroll to first occurrence only.

• Config: grep config_db set and get on the same field name.

• Stimulus: confirm run_phase entry and vif != null before waves.

• Prediction: trace adapter → predictor → reg_model path.

Classification drill

# bucket classification one-liners
grep -E "objection|MISMATCH|config_db|RAL|get_next_item" sim.log | tail -20
grep -c UVM_ERROR sim.log
grep "run_phase" sim.log | head -5

[DEBUG] classification pass criteria

bucket written on ticket
and
first-move tool selected
and
seed frozen before any TB edit

Common pitfalls

• Multi-bucket guessing — pick one primary bucket and prove it.

• Changing random seed before classification is complete.

• Using waveform time % as bucket evidence instead of log signatures.