The Unified GPSIMD / Cayman SoC Memory Map

This is the capstone of the Part‑13 address sub‑section. The preceding sixteen pages each dissect one view of the address space — the byte‑grounded CAYMAN (NC‑v3) flat‑YAML chip map, the forward‑looking MAVERICK (NC‑v5) pickled DB, the host PCIe BAR view, the Q7‑local NX view, and the translation machinery that joins them. This page unifies them into one canonical reference a reimplementer reads first: one region table, the three coordinate systems and how to convert between them, the generation delta, and the gen‑invariance thesis — what stays fixed in the address layout across silicon generations (the offsets you hard‑code) versus what moves (the absolute bases you must discover at runtime).

It is a synthesis page: it reconciles and presents, it does not re‑derive. Every headline number below was nonetheless re‑verified this session against the primary artifacts (address_map_flat.yaml, al_address_map_db.pkl, the nine LSP ldscripts, pcie_host_address_mapping.svh, tpb_nx.h). Confidence is tagged HIGH/MED/LOW × OBSERVED/INFERRED/CARRIED per claim.

⚠ WALL — read this before trusting any number.

• CAYMAN / NC‑v3 numbers are byte‑grounded in the RTL‑generated address_map_flat.yaml (34,858 nodes; filename + banner say "Cayman"). [HIGH · OBSERVED]
• MAVERICK / NC‑v5 numbers come from the shipped al_address_map_db.pkl (323,198 records, under arch-headers/maverick/). The DB structure (records, roots, view partition, sizes of the top nodes) is OBSERVED; anything about what a v5 address does inside the silicon is INFERRED. Every v5‑interior claim is flagged.
• The Q7‑local (NX 32‑bit) view is CAYMAN/Sunda‑grounded (the shipped LSPs, tpb_nx.h, the disassembled neuron_translate). The register widths persist to v5 (the v5 TCAM header is byte‑identical in structure); the v5 behaviour beyond those widths is INFERRED.

Primary artifacts (all under the gitignored extracted/ tree — use --no-ignore / absolute paths):

0. Self‑verify — the five headline claims, re‑challenged this session

Before authoring, the five strongest claims were re‑challenged directly against the artifacts (not carried from a sibling). All five pass.

CORRECTION carried forward (vs the "57‑bit SoC physical" shorthand). SX‑ADDR‑18 and soc-q7-translation-windows.md call the SoC space "57‑bit." That is loose. The decode field is 58 bits ([57:0], cayman_addr_decode.h); the routed geometry is [54:0] (DIE[47] + CAYMAN_ID[53:48]

• valid[54]); the populated map tops out at 2⁵⁴; bits [57:55] are attribute/valid flags, not address bits. State it as "58‑bit decode field, [54:0] routed, 2⁵⁴‑populated." This page uses that precise form throughout; "57‑bit" in the siblings means the same thing (bits [57:0] minus the reserved bit 55). [HIGH · OBSERVED] (soc-master-map.md §3 / addr-decode.md).

1. THE ONE CANONICAL UNIFIED REGION TABLE

This is the page's headline artifact: every major region with its CAYMAN (NC‑v3, byte‑grounded) base/size and, where it differs, the MAVERICK (NC‑v5, pkl‑observed) base/size side by side. Bases are absolute SoC addresses unless a column says otherwise.

The MAVERICK column shows the v5 root‑relative base where the v5 partition differs structurally (the v5 map is split into four 2⁶⁰‑wide access‑domain views — USER_INT/USER_PCIEA/SECURE_INT/SECURE_PCIEM at top nibbles 0x0/0x1/0x2/0x3, plus USER_POD at 0x4; a v5 leaf base = view_base | local). Where the v5 column reads "(SENG_n)" the block reparented under a Sub‑ENGine layer absent from Cayman.

Two die copies repeat the entire die‑0 layout OR'd with bit 47 (0x800000000000); a 2‑die Cayman thus exposes 4 × 64 GiB = 256 GiB HBM SPARSE in SoC space. [HIGH · OBSERVED] — the die‑1 copy is numerically exact for every family (soc-master-map.md §2). The full 126‑root / 34,858‑node walk lives in soc-master-map.md; this table is the navigable subset a Q7 reimplementer actually touches.

GOTCHA — "TPB_0 base is 0x2000000000, not 0x2800000000." 0x2800000000 is the child TPB_0_TPB_RESERVED_SBUF, not the container. The POOL Q7 cluster uses 0x2800000000 only as a pseudo‑base for its +0x3100000 core offset (so POOL_Q7_CORE0_IRAM = 0x2800000000 + 0x3100000 = 0x2803100000), which is also TPB_0 + 0x803100000. Both readings give the same absolute address; do not conflate the pseudo‑base with the container base. [HIGH · OBSERVED] (soc-master-map.md CORRECTION / tpb-pool.md).

2. THE THREE COORDINATE SYSTEMS — and how to convert between them

A GPSIMD reimplementer juggles three distinct address namespaces. Confusing them is the single most common class of bug. Each has its own width, its own zero, and its own translation step to the next.

The conversion graph is a chain, host at one end, the Q7 core at the other, the SoC‑physical space in the middle:

  (2) PCIe‑host BAR        (1) SoC‑physical 58‑bit          (3) Q7‑local NX 32‑bit
   (bar, offset)   ──►  cayman_address[54:0]   ──►   NX pointer 0x07012345
                  #898                        #910
        ▲  per‑window .svh table         ▲  TCAM {mask,match,replace}
        │  (NOT a global add)            │  (Sunda: {lo,hi} sw‑TLB)
        │                                │
        └─ host ioremap                  └─ Q7 build‑time: LSP places code at
                                            0x84000000+cpu·0x200000  (#911)

2a. Host BAR → SoC‑physical (the #898 per‑window join)

There is no closed‑form arithmetic — each BAR window carries its own independent SoC base. The recovered table (pcie_host_address_mapping.svh) is the translation:

soc = window.cayman_address + (bar_offset - window.host_offset);   /* per‑window base */

Two BARs only: BAR0 = 4 GiB control aperture, 64 windows (every engine CSR compacted into a dense sub‑4 GiB region); BAR4 = 256 GiB HBM aperture, 4 windows (the four 64 GiB stacks flattened back‑to‑back). The host view flattens the sparse SoC layout: host_offset ≠ cayman_address low bits for every window except HBM_0 (offset 0 → SoC 0). [HIGH · OBSERVED] (pcie-bars.md). Worked rows:

host_to_cayman(BAR0, 0xD0000000) -> 0x2000000000   ("TPB_0" → TPB_0_STATE_BUF)
host_to_cayman(BAR4, 0x2000000000) -> 0x800000000000 ("HBM_2", die1, LOCAL=0)

The PEB/DFT path (amzn0/amzn1 functions, BAR0+BAR3) is a separate PCIe function carrying CAYMAN_ID = 32 (0x20) in bits [53:48] — that non‑zero chip‑id is what routes it apart from the regular (CAYMAN_ID = 0) host function.

2b. SoC‑physical → Q7‑local NX (the #910 window translate)

A Q7 core cannot dereference a 58‑bit SoC address directly — it dereferences a 32‑bit NX pointer that a hardware window register maps onto the SoC. Two generations of that register:

• Sunda (NC‑v2): a {lo, hi} base‑pair per window. The device caches it in a 5‑entry software TLB (neuron_translate): on a HIT it returns window_NX_base + (soc & ~mask) (pure arithmetic); on a MISS it evicts a round‑robin victim (%3 over the 3 dynamic slots) and writes the {lo,hi} into the hardware MEM_WINDOWn register in one act. The three dynamic 16 MiB slots map HW MEM_WINDOW3/5/6 at NX 0x100218/228/230. [HIGH · OBSERVED]
• Cayman (NC‑v3) and after: a 40‑window TCAM at NX register offset 0x2000, each a {control, mask, match, replace} struct. match/mask compare address bits [39:20] (20‑bit, 1 MiB granule, fully resizeable); replace[63:20] is the SoC output base. The same {lo,hi} shape feeds the host‑side program_window.

/* Cayman TCAM translate, NX 32‑bit -> SoC 58‑bit (one window). */
if ((nx[39:20] & care_mask) == (match & care_mask))          /* TCAM HIT */
    soc = (replace[63:20] << 20) | (nx & ((1<<20)-1));        /* 1 MiB passthrough */

The five fixed NX bases (byte‑exact from the _init_translate_ctx disasm):

Full machinery in soc-q7-translation-windows.md.

2c. Q7 build‑time placement (the #911 LSP)

The customop library is linked into the low slice of the 0x84000000 hbm_scratch pinned window, per‑core: sram0_0_seg org = 0x84000000 + cpu_id·0x200000 (2 MiB stride; re‑verified all 9 LSPs this session — cpu0 0x84000000, cpu3 0x84600000, cpu7 0x84E00000, single 0x84000000/32 MiB). The four XEA3 vector sections go in iram0_0_seg org = 0x0, len = 0x1000 (4 KiB). No stack, no heap in the LSP — both are runtime‑carved. [HIGH · OBSERVED] (lsp-sram-window-map.md).

2d. A worked round‑trip — host driver to Q7 pointer to SoC byte

Suppose the host wants a Q7 core to read PSUM byte 0x2802012345 (PSUM base 0x2802000000 + 0x12345), and wants to confirm the host BAR that reaches the same byte. Trace all three systems:

SYSTEM (1) SoC‑physical: target = 0x2802012345
                         decode: LOCAL[46:0]=0x2802012345, DIE[47]=0, CAYMAN_ID=0

(2) host side — which BAR0 window?  (cayman_to_host)
    0x2802012345 ∈ TPB_0_PSUM_BUF window? PSUM lives inside TPB_0 (STATE_BUF aperture
    is 32 MiB @0xD0000000→0x2000000000); the 4 MiB psum_buf is interior. The host
    reaches it through BAR0 0xD0000000 + (0x2802012345 − 0x2000000000) — but note the
    32 MiB STATE_BUF aperture does NOT cover 0x2802xxxxx; PSUM proper is the
    TPB_0_PSUM_BUF/RESERVED_SBUF window @0xD2000000→0x2800000000. Host MMIO =
    0xD2000000 + (0x2802012345 − 0x2800000000) = 0xD2000000 + 0x2012345 = 0xD4012345.
       (per‑window base remap — NEVER a global add)

(3) Q7 side — neuron_translate(ctx, 0x2802012345), cold cache, victim slot 0:
    rec0.ptr  = 0x2802012345 & 0xff000000 = 0x02000000        (lo prefix install)
    *(MEM_WINDOW3_HI 0x10021C) = 0x2802012345 >> 32 = 0x28
    *(MEM_WINDOW3_LO 0x100218) = 0x02000000
    return 0x07000000 + (0x2802012345 & 0x00FFFFFF) = 0x07012345   (NX pointer)

  Q7 then dereferences NX 0x07012345; MEM_WINDOW3 (now holding SoC 0x2802000000)
  re‑expands it to SoC 0x2802012345.  ✓  back to SYSTEM (1).

Round‑trip closes: SoC 0x2802012345 ⇄ host (BAR0, 0xD4012345) ⇄ Q7 NX 0x07012345. [HIGH · OBSERVED] for the per‑step arithmetic; the host‑window choice is the pcie-bars.md §2d table (the BAR label TPB_n_PSUM_BUF maps to the 32 MiB RESERVED_SBUF aperture, the true 4 MiB psum CSR being interior).

3. THE CAYMAN‑vs‑MAVERICK GENERATION DELTA

The v3→v5 address‑space changes a reimplementer must account for. CAYMAN values are byte‑grounded; MAVERICK values are pkl‑observed for structure, the interior behaviour INFERRED.

The 64‑die mesh addressing (CAYMAN_ID [53:48] = 2⁶ chips) is shared by both generations; only the intra‑chip layout grows. The v5 HBM/TPB sizes and the 5‑view partition were re‑verified this session against the pkl directly (roots on a 2⁶⁰ stride; pickle.load len = 323,198). [HIGH · OBSERVED]

WALL — the "39 UCIE links" and the v5 HBM/TPB GiB sizes are sourced to the right sibling. They are not in pkl-db.md. The v5 HBM 128 GiB / TPB 256 GiB sizes are read off the pkl root nodes (also tabulated in soc-master-map.md §8); the UCIE link count lives in pkl-pcie-d2d-fabric.md and the HBM detail in pkl-hbm-subtree.md. Cite those, not pkl-db.md. [HIGH · OBSERVED]

4. THE GEN‑INVARIANCE THESIS FOR ADDRESSES — the reimplementer's keystone

This is the single most useful generalization on the page. A reimplementer can hard‑code the gen‑invariant set and need only discover at runtime the small gen‑variant set. The dividing line is relative offset (fixed) vs absolute base (moves).

4a. WHAT STAYS FIXED across generations (hard‑code these)

4b. WHAT MOVES across generations (discover at runtime)

The keystone reading. A reimplementer who hard‑codes §4a's offsets and reads §4b's bases from one DB at init has a forward‑portable engine: the Q7 firmware references everything engine‑relative (its own ENGINE_BASE_ADDR + fixed offsets

• the NX window map), so it runs unchanged when the SoC moves the cluster's absolute base. The fragile code is anything that bakes an absolute SoC base; the robust code computes every SoC address as runtime_engine_base + fixed_offset. [HIGH · OBSERVED] for the invariants; the "forward‑portable" reading is INFERRED (architectural, grounded in the byte‑exact offset equality across PREPROC/POOL and the gen‑stable NX map).

5. WHERE DO I FIND X — the region → sibling index

6. Confidence ledger

HIGH · OBSERVED (re‑verified this session against the artifacts):

• The unified CAYMAN region table — every base re‑grepped from address_map_flat.yaml (HBM_0/PREPROC_0/TPB_0/HBM_1/2/3/PCIE_A0_0/EVT_SEM/POOL CORE0/LOCAL_REG, line‑cited).
• 34,858 flat nodes (wc -l), 19,012 json bindings; pkl 323,198 records, 5 roots on 2⁶⁰ stride, by‑view 79,104 + 244,040 + 24 + 24 + 5 + 1 = 323,198 (both re‑loaded).
• All 9 LSP origins (iram0 0x0/0x1000, sram0 0x84000000 + cpu·0x200000 / 2 MiB, single 32 MiB) — re‑grepped byte‑exact.
• PREPROC CORE0 offset = POOL CORE0 offset = +0x3100000; LOCAL_REG +0x3060000; EVT_SEM container 0x2802700000 + windows +0x1000/1400/1800/1C00 — direct from YAML.
• The 3‑coordinate conversion chain (host per‑window join / TCAM replace[63:20] / LSP build base) and the worked round‑trip — each step grounded in its sibling.
• The CAYMAN↔MAVERICK delta sizes (64→128 GiB HBM, 32.06→256 GiB TPB, SDMA→DDMA/CDMA/UDMA).
• The gen‑invariant offset set (§4a) — the offset equality across PREPROC/POOL is the byte‑exact anchor.

MED:

• The 0x2802012345 worked round‑trip's host‑window choice (the BAR TPB_n_PSUM_BUF label vs the interior 4 MiB psum CSR — the aperture mapping is OBSERVED, the exact interior offset is the pcie-bars.md §2d reading).
• EVT_SEM SEMAPHORE_CNTR_INC v5 window (observed in pkl; per‑field semantics not separately schema‑verified).

INFERRED / WALL:

• All MAVERICK / NC‑v5 interior behaviour — the DB structure is OBSERVED, what a v5 address does in silicon is INFERRED. The byte‑grounded behavioral reference is the CAYMAN flat YAML.
• The "forward‑portable engine" reading of the gen‑invariance thesis (§4b) — grounded in the offset equality + the gen‑stable NX map, but a synthesis, not a traced fact.
• The run‑stall register offset within LOCAL_REG (+0x3000) is carried from tpb-pool.md #900; the register name is obscured to release_n in the shipped schema JSON, so the offset is sibling‑anchored, not re‑derived this session.

See also

• soc-master-map.md — the full 126‑root / 34,858‑node CAYMAN chip map
• addr-decode.md — the 58‑bit decode bitfield (DIE / CAYMAN_ID / neighbor route)
• pcie-bars.md — the host PCIe BAR0/BAR4 → SoC join
• preproc-cc.md · tpb-pool.md — the two Q7 clusters
• evt-sem-regions.md — the EVT_SEM 256/256 data plane
• pkl-db.md · pkl-topsp-coverage.md — the MAVERICK DB + the coverage proof
• soc-q7-translation-windows.md — the SoC↔Q7 window machinery
• lsp-sram-window-map.md — the Q7 build‑time NX layout