Debug playbook

Debug Playbook for AXI-Lite & AXI-Stream focuses on register response latency, stream bubble rate, packet boundary errors. The goal is to connect the observable symptom to protocol mechanism, ownership, and regression risk.

Protocol debug is a search for the FIRST deviation, not the loudest symptom. Timeouts and error flags are usually many cycles downstream of the real cause.

Root-cause tree

ROOT-CAUSE TREE — AXI-Lite & AXI-Stream

register response latency, stream bubble rate, packet boundary errors looks wrong
        |
   reproducible?
     /        \
   no          yes
   |            |
 flaky env   same first transaction every time?
 / seed         /            \
              yes             no
               |               |
        protocol rule     timing/reset/PVT
        or config bug     or load-dependent

1. Freeze the failing seed, firmware tag, and spec revision.

2. Find the first bad transaction, not the loudest downstream timeout.

3. Map the transaction to signals and VIP monitor events.

4. Classify the failure: protocol rule, integration config, timing/reset, or performance pressure.

5. Prove the mechanism with one reduced sequence.

6. Patch the smallest owner-controlled boundary and rerun compliance plus workload traffic.

Review memo template

STAFF PROTOCOL REVIEW MEMO — AMBA Family (APB / AHB / AXI) / AXI-Lite & AXI-Stream

1. Symptom
   - Watched metric: register response latency, stream bubble rate, packet boundary errors
   - Failing interface: <master/slave/endpoint/controller/PHY>
   - Transaction identity: <ID/tag/address/endpoint/lane>
   - Repro setup: <sim/emulation/FPGA/silicon + firmware tag>

2. Mechanism hypothesis
   - Primary mechanism: AXI-Lite removes bursts for control paths while AXI-Stream moves ordered data without addresses.
   - Competing hypothesis: <timing, reset, bridge, ordering, firmware, or VIP issue>
   - Missing evidence: <waveform, analyzer trace, counter, spec clause, or log>

3. Proposed action
   - Minimal reversible change: <RTL, register setting, bridge config, scheduler, VIP check>
   - Expected metric movement: <delta and workload>
   - Regression risk: ordering, compatibility, performance, power, area, or timing

4. Signoff
   - Re-run artifact: TVALID/TREADY trace, TLAST packet log, control register access test
   - Required owners: IP owner, verification owner, driver owner
   - Final decision: fix, waive, document limitation, or escalate to architecture

Protocol deep dive

AMBA is the on-chip lingua franca: APB for control, AHB for legacy bursts, AXI for high-performance coherent fabrics.

Concept diagram

AMBA INTEGRATION MAP

CPU --AXI--> NIC --AXI--> SRAM
  |              |
  +--AXI-Lite--> peripherals (GPIO, timers)
  +--AXI-Stream-> video pipe

Every bridge is a contract rewrite: width, ID, burst, cache attrs.

Metric graph

AXI CHANNEL ACTIVITY (mixed traffic)

AW+W     ████████████
AR       ████████████████
R        ██████████████
B        ████████

Read-heavy phase: AR/R dominate; write resp may look idle while system is healthy.

Metrics and artifacts to collect

• AR/AW/R/B channel utilization

• write resp latency

• read OSTD depth

• SLVERR/DECERR count

• bridge hang log

Mini case study

Write burst hung because W beats arrived before AW for a narrow bridge that reordered channels. VIP flagged nothing until full-system traffic interleaved reads and writes.

Debug branches

• Hung write: verify AW/W ordering and wlast alignment.

• Hung read: check arready stall and rlast per ID.

• Decode errors: address map vs interconnect route table.

Senior review question

Ask: what is the first transaction that deviates, and which spec rule does it test?

Key takeaways

• Connect every protocol claim to a transaction identity and measurable metric.

• Store the artifact (waveform, log, counter) next to every signoff decision.

Common pitfalls

• Debugging timeouts without finding the first bad transaction.

• Quoting peak bus width without payload efficiency and retry overhead.

• Treating VIP compliance as a substitute for system integration replay.

Principal review addendum

Re-read AXI-Lite & AXI-Stream against one concrete product workload, not a synthetic directed test.

AXI-Lite removes bursts for control paths while AXI-Stream moves ordered data without addresses.