Debug playbook

Debug Playbook for I2C Timing & Arbitration focuses on NACK rate, clock-stretch duration, bus recovery time. 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 — I2C Timing & Arbitration

NACK rate, clock-stretch duration, bus recovery time 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 — Embedded Peripherals (I2C / SPI / UART) / I2C Timing & Arbitration

1. Symptom
   - Watched metric: NACK rate, clock-stretch duration, bus recovery time
   - 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: I2C shares open-drain wires with address arbitration, acknowledge cycles, and optional clock stretching.
   - 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: SCL/SDA waveform, transaction log, pull-up timing check
   - Required owners: peripheral owner, board owner, driver owner
   - Final decision: fix, waive, document limitation, or escalate to architecture

Protocol deep dive

I2C/SPI/UART bugs are contract bugs: timing, reset value, IRQ type, and DMA watermark.

Concept diagram

PERIPHERAL CONTRACT

firmware writes regs -> RTL state machine -> pins -> board -> device
        ^                    |
        +------- IRQ/DMA ----+

If IRQ is level but driver assumes edge, you get lost events.

Metric graph

FIFO WATERMARK vs DMA

FIFO fill
 100%|        *** overrun risk
  75%|     ***
  50%|  ***     <- ideal DMA trigger band
  25%| *
   0%+----------------> time

Metrics and artifacts to collect

• NACK rate

• overrun count

• CS setup/hold violations

• IRQ miss rate

Mini case study

SPI flash worked in loopback but failed in system: CS deasserted one cycle early relative to device hold time. Board + RTL + mode bits together formed the contract.

Debug branches

• If overrun, FIFO depth vs ISR latency vs DMA burst.

• If NACK on I2C, pull-ups, speed, and clock stretch.

• If garbage data, CPOL/CPHA and MSB/LSB first.

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 I2C Timing & Arbitration against one concrete product workload, not a synthetic directed test.

I2C shares open-drain wires with address arbitration, acknowledge cycles, and optional clock stretching.