Gray Code Crossing: Debug Playbook

Debug playbook

Debug Playbook for Gray Code Crossing focuses on single-bit transition compliance, pointer decode correctness, CDC flag integrity. The goal is to convert issue observations into mechanism-backed closure decisions.

CDC/RDC debug is about finding the earliest violated assumption. Start with intent and context before touching low-level signal traces.

Root-cause tree

ROOT-CAUSE TREE — Gray Code Crossing

crossing failure observed
        |
   reproducible?
     /        \
   no          yes
   |            |
stress mode   classify issue
expansion       /      |      \
            synchronizer protocol reset/reconvergence
                 |         |           |
            MTBF fit    liveness    release ordering

1. Freeze RTL/config/tool tags for reproducibility.

2. Reproduce in smallest mode/reset/traffic scenario.

3. Classify mechanism: synchronizer, protocol, reset, reconvergence, or governance.

4. Collect one decisive artifact that proves the class.

5. Pick minimal fix or bounded waiver.

6. Run targeted and full-regression matrices before closure.

Review memo template

STAFF CDC/RDC REVIEW MEMO — Reconvergence & Gray Coding / Gray Code Crossing

1. Symptom
   - Failing metric: single-bit transition compliance, pointer decode correctness, CDC flag integrity
   - Context: <mode, traffic, reset state, corner>
   - Risk class: <critical/high/medium/low>
   - Database tags: <rtl, config, assertions, tool setup>

2. Mechanism hypothesis
   - Primary mechanism: Gray encoding limits transitions to one bit per step, reducing sampled ambiguity when pointers cross asynchronous boundaries.
   - Competing hypothesis: <false warning / protocol bug / reset order / reconvergence>
   - Missing evidence: <assertion, waveform, formal proof, stress replay>

3. Proposed action
   - Minimal reversible change: <sync/protocol/reset/waiver decision>
   - Expected metric movement: <critical count delta>
   - Regression risk: throughput, boot, latency, mode interaction

4. Signoff
   - Re-run artifact: gray encode/decode checks, pointer transition proof, FIFO status tests
   - Required owners: RTL owner, CDC owner, formal owner
   - Final decision: fix, bounded waiver, or escalate

CDC/RDC deep dive

Reconvergence failures are timing + logic coupling hazards.

Concept diagram

RECONVERGENCE

branch A sync --                 -> merge logic -> illegal combination window
branch B sync --/

Metric graph

HAZARD REPRODUCTION RATE

before fix: 1/2000 runs
after fix: 0/100000 runs

Reports and artifacts

• reconvergence warnings

• gray transition checks

• hazard replay traces

• multi-bit strategy map

Mini case study

Gray pointer was legal, but downstream merge decoded mixed-era values during burst stress.

Debug branches

• Trace fanin cones

• align event windows

• verify decode assumptions

Senior review question

Ask: what evidence proves this risk is closed for silicon, not just tool-clean?

Key takeaways

• State crossing class, assumptions, and owner with every issue.

• Run structural and dynamic regressions after each fix.

Common pitfalls

• Treating all warnings as equivalent risk.

• Waiving issues without containment evidence.

• Skipping reset and reconvergence stress after CDC fixes.

Principal CDC/RDC review addendum

Gray encoding limits transitions to one bit per step, reducing sampled ambiguity when pointers cross asynchronous boundaries.

Metric: single-bit transition compliance, pointer decode correctness, CDC flag integrity