Waveform Analysis

This chapter is not about a waveform viewer. Viewers are easy and you already have one.

It is about the question that decides whether the next hour is productive:

Which signals do I need to prove or eliminate my hypothesis?

A waveform is the most expensive evidence in the toolbox — expensive to produce, expensive to store, and above all expensive to read. It is also the most seductive, because it looks like it contains everything. It does. That is the problem.

1. The Evidence Hierarchy

Work upwards. Stop as soon as the hypotheses separate.

Every experiment in Module 27 was settled at tier 3 or 4.

• SIM B and SIM C separated on one census row: memory phases opened, 0 versus 1.
• SIM D separated on one census row: register slave phases presented, 0 versus 4.
• SIM G separated on two counters: pops and underflows.
• SIM I, J and K separated on a ten-row lineage table.

Not one of them required a waveform to reach a conclusion. The waveforms in this module exist to make a conclusion legible after it has been reached — which is a real and different job.

The anti-pattern is one line long and everybody has done it:

failure  ->  dump every signal  ->  stare

Three hundred signals over ten thousand clocks contains the answer and does not contain a way to find it. The rule:

Use the cheapest evidence that can discriminate the hypotheses.

2. The Trace Can Lie

Before trusting any of tiers 3 to 5, check them against something that is not them.

The monitor of Chapter 26.3 makes judgements: when a phase began, when it ended, which class of termination it was, which data belonged to it. Every one of those can be wrong — SIM K1 in the previous chapter is a monitor that was.

So this module carries a second observer that makes no judgements at all:

// ── WHY THIS IS NOT THE MONITOR ─────────────────────────────────────────
// A debugger who uses the monitor to check the monitor has proved nothing.
// So this module makes no judgements at all. It counts edges:
//
//     presented   ( CYC && STB )           how many clocks a request stood
//     terminated  ( presented && term )    how many ended
//     acks / errs / rtys                   which class, from the pins
//     opened      ( rising presented )     how many phases began
//     max_held                             longest unanswered stretch
//     open_now                             still presented at the end
//     unknown                              any pass-deciding pin at X

The cross-check, on the clean baseline:

Agreement across four independently derived numbers. That is what earns the transaction log the right to be believed for the rest of the session — and it costs one module and one table.

3. Signal Reduction

A waveform should contain every signal that answers a question and nothing else. Here are the four reductions this module actually used.

Two of those four are not waveforms at all. Data lineage and ownership provenance are tabular questions; drawing them as waveforms would have lost the thing that made them readable, which is that each row is one transfer or one clock and each column is one edge.

The test for a published waveform is not "is it small". It is:

Can you say, for each signal, which competing explanation it eliminates?

If not, delete it. A signal that cannot fail to look the way it looks has no evidentiary value.

4. The Reading Method

1. Identify the triggering failure — the detector, not the impression.
2. Identify the transaction or attempt it belongs to.
3. Mark the clock the request started.
4. Mark the completion, or establish its absence.
5. State the invariant you expect to hold across that interval.
6. Move backwards from the symptom.
7. Locate the first clock at which expectation and observation diverge.
8. Inspect only the causal predecessors of that clock.
9. Formulate a mechanism that explains the divergence.
10. Re-run after the fix and confirm the divergence is gone.

Step 7 is the one people skip, and it is the only one that matters. The last visible failure is almost always downstream noise:

  divergence                      first cycle    count
  target delivered != expected                4        3
  address changed downstream                  0        0
  nothing selected at all                     0        0
  slave drove wrong read data                16        2
  bus carried wrong read data                16        2
  monitor recorded wrong data                16        2

Three divergences report count 2 at cycle 16; one reports count 3 at cycle 4. Sorting by count picks the wrong one. Sorting by first occurrence picks the cause.

And then check the ordering mechanically, because a plausible story is not evidence:

  TEMPORAL CAUSALITY CHECK
  claimed root-cause event  cycle 4
  first data symptom        cycle 16
  invalid causal orderings  0

A claimed root cause whose event happens after the first observed failure is not a root cause. It is a coincidence with a narrative attached, and the check above costs nothing.

5. Say What Is On The Screen

Do not write:

"As you can see, ACK is wrong."

Write:

At edge 4, the decoder computes target S1 for address 0x0110 and the request is delivered to S0. The first divergence is the delivered target, twelve clocks before the master observes wrong read data.

The second sentence names an edge, a value, a boundary, and an ordering. The first names a feeling.

6. The Blind Case, End To End

One defect was armed and its name withheld until the reasoning finished.

Symptom. Five operations issued, five retired, two scoreboard mismatches — one data, one termination. Zero protocol violations. Zero unknown fields. Nothing hung.

Classify. Not completion: 5 issued, 5 retired. Not timing: maximum open phase 0 clocks. Not ownership: owner moved 0, responses misdelivered 0. Data or routing.

Hypotheses. H1 the memory stored the wrong value. H2 the return path delivered the wrong value. H3 the request never reached the memory. H4 the monitor or model is wrong.

Observation 1 — two counters and a back-door read, no waveform:

    phases presented to S0 registers   5
    phases presented to S1 memory      0
    memory word 0x0110, via back door  0xxxxxxxxx

Eliminate. A memory that was never addressed cannot have stored anything, right or wrong — H1 rejected. A return path carries what a slave sent, and no slave in that window sent anything — H2 rejected. The monitor's unknown count is 0 and the register transfers in the same run are correct — H4 unlikely. H3 survives.

Observation 2 — the decode trace:

    transfer  address  expected  delivered
    0         0x0110   S1 mem    S0 regs
    2         0x0110   S1 mem    S0 regs
    4         0x0200   unmapped  S0 regs

Root cause. 0x0110 reaches S0 and so does 0x0200, which is outside every window. Both are true if and only if the region compare uses a truncated address. A widened window would not do this: widening S0 to cover 0x0100–0x01FF captures 0x0110 and leaves 0x0200 outside. 0x0200 is the address that separates the two hypotheses, and the trace says it reached S0.

Only then: the armed defect was ADDR_TRUNCATE, comparing ADR[7:0].

Fix and proof:

  STAGE 9  FIX VERIFICATION
    scoreboard mismatches   before 2   after 0
    memory word 0x0110      before 0xxxxxxxxx   after 0x5555bbbb
    phases presented to S1  before 0   after 2

  STAGE 10  REGRESSION
    before the fix  retired 8  mismatches 2  violations 0
    after  the fix  retired 8  mismatches 0  violations 0

The original failing test passes, the memory now holds what was written to it, and an eight-operation regression that also failed before the fix is clean after it.

7. The Fix That Is Not A Fix

  THE FIX THAT IS NOT A FIX
  The same defective system, running a test that never
  touches the memory window:
    operations retired      4
    scoreboard mismatches   0
    protocol violations     0
  The suite is green and the decoder is exactly as broken
  as it was. A test that avoids the failing address has
  removed the evidence, not the defect.

Root cause requires all six of these, not the last one alone:

1. a mechanism that explains the symptom;
2. evidence the mechanism actually occurred;
3. a first divergence consistent with it;
4. a correction that removes the divergence;
5. the original failing test passing;
6. a clean regression staying clean.

"I changed three lines and the waveform looks better" satisfies none of them.

8. The Assertions Were Clean

  A1 0   A2 0   A3 0   A4 0   A5 0   SPEC 0   LOCAL 0

Every executable assertion in the system reported clean, and the system was decoding 0x0200 onto a peripheral. An assertion catches its own class and nothing else. None of the five encodes the address map, because the address map is not a Wishbone rule — it is this system's own specification, and only the decode trace was ever going to find this.

9. Twelve Sentences This Module Refutes

10. The Root-Cause Report

Short, causal, and written for the next engineer. This is a template filled in by hand, not simulator output — every number in it is quoted from the runs above:

FAILURE        memory readback at 0x0110 returns register data;
               0x0200 acknowledges instead of erroring.
REPRODUCTION   5-op deterministic program, no randomness, byte-identical
               across runs.
FIRST DIVERGENCE
               cycle 4 — decode computes S1, routing delivers S0.
               First data symptom at cycle 16; ordering checked.
ROOT CAUSE     the region compare uses ADR[7:0]. The high byte is
               discarded, so 0x0110 and 0x0200 both alias onto S0's base.
FIX            compare the full address width.
PROOF          original test 2 mismatches -> 0; 8-op regression 2 -> 0;
               memory phases presented 0 -> 2.
PREVENTION     add the boundary sweep of Chapter 27.2 to the regression
               suite: first and last of each window, one above and below,
               a hole, and an alias candidate. 0x0200 is the address that
               would have caught this on day one.

The PREVENTION line is what stops the same afternoon happening twice.

11. What To Carry Forward

• Use the cheapest evidence that discriminates. Twelve experiments, zero settled by a waveform.
• Cross-check the trace against raw pins before you trust it. The monitor makes judgements; a pin census does not.
• Every published signal must eliminate an explanation. If you cannot say which, remove it.
• Some questions are tables, not waveforms. Lineage and provenance both lost nothing by being printed.
• Sort by first occurrence, never by count.
• Check causal ordering mechanically. A root cause that happens after its symptom is a story.
• Green after avoiding the failing case is not a fix.
• Write the report for the next engineer, and include the test that would have caught it.

Module 27 ends here. Chapter 26.1 taught which detector says something is wrong; this module was about what evidence localises why.