Debug playbook

Debug Playbook for Global Address Map Planning focuses on decode conflicts, remap churn, software breakage from map changes. The goal is to map symptoms to boundary contracts, owner actions, and regression-proof closure.

Integration debug is a search for the first contract break, not the loudest downstream failure signature.

Root-cause tree

ROOT-CAUSE TREE — Global Address Map Planning

decode conflicts, remap churn, software breakage from map changes regressed
         |
   same baseline manifest?
      /           \
    no             yes
    |               |
version/collateral  real integration
mismatch            contract break
 /       \            |
inputs    env      isolate domain
drift     drift    and first failure

1. Freeze baseline manifest and owner matrix.

2. Find first failing boundary and earliest reproducible symptom.

3. Classify failure type: contract, collateral, implementation, or governance.

4. Prove with one reduced experiment.

5. Apply smallest owner-controlled fix.

6. Run focused verification and full cross-domain regression.

Review memo template

STAFF SOC REVIEW MEMO — Memory Maps & I/O / Global Address Map Planning

1. Symptom
   - Watched metric: decode conflicts, remap churn, software breakage from map changes
   - Failing integration boundary: <domain/interface>
   - Baseline manifest: <hash/tag>
   - Repro setup: <sim/emulation/fpga/silicon + fw tag>

2. Mechanism hypothesis
   - Primary mechanism: A stable address map aligns hardware decode, virtualization windows, security regions, and firmware assumptions across the product lifecycle.
   - Competing hypothesis: <contract drift, collateral mismatch, implementation bug, governance gap>
   - Missing evidence: <trace, report, checklist, signoff artifact>

3. Proposed action
   - Minimal reversible fix: <contract update, config patch, RTL fix, process guardrail>
   - Expected metric movement: <delta and scope>
   - Regression risk: timing, power, functionality, schedule

4. Signoff
   - Re-run artifact: address map registry, decode validation report, alias checker output
   - Required owners: SoC architect, firmware architect, security owner
   - Final decision: close, waive (bounded), or escalate

SoC deep dive

Address, interrupt, and IO contracts are where hardware/software alignment is won or lost.

Concept diagram

HW/SW CONTRACT
address map + interrupt model + io defaults -> firmware behavior

Metric graph

BOOT REGRESSION SOURCES
map churn █████
reset defaults ████
driver mismatch ███

Reports and artifacts

• address decode audit

• interrupt latency report

• IO bring-up checklist

• boot contract review

Mini case study

A map alias issue caused sporadic peripheral misconfiguration despite clean block-level tests.

Debug branches

• Freeze address map baseline

• Audit reset defaults

• Validate firmware assumptions

Senior review question

Ask: what baseline, owner, and artifact prove this topic is truly closed?

Key takeaways

• State baseline manifest and owner with every closure metric.

• Run cross-domain regression after every top-level fix.

Common pitfalls

• Comparing results across different manifests.

• Unowned issues slipping through review cycles.

• Waiving risks without expiry and validation plan.

Principal SoC review addendum

A stable address map aligns hardware decode, virtualization windows, security regions, and firmware assumptions across the product lifecycle.

Metric: decode conflicts, remap churn, software breakage from map changes