pkl TOP_SP / Sync / MISC Subtree + Coverage Tally

This page closes the pkl-carve sub-lane. It does two jobs:

1. Carve the last engine subtree out of the Annapurna-Labs address-map source DB — the TOP_SP collective sequencer (engine 5), the sync / semaphore substrate (EVT_SEM 256-array + COLLECTIVE_SYNC + SP_SHARED_RAM), and the MISC / residual peripherals (URB routing fabric + the PEB chiplet-management IO blocks: PLL, QSPI, GPIO, I²C, SPIS, PVT, DFX, scratchpad).
2. Prove coverage is complete — sum every carved subtree against the 323,198 record total, reconciled on two independent axes (by physical lane AND by access-domain view), and show the residual closes to 0.

The shared load primitive (safe pickletools.genops() / streaming-JSON readers, the 23-field record schema, the 5 access-domain views, the 6-class type taxonomy) is the deliverable of pkl-db.md — read that first. This page reuses it and never calls pickle.load().

⚠ WALL — MAVERICK (v5), header-OBSERVED only. The DB is arch-headers/maverick/ext/al_address_map_db.pkl (216,631,794 B) + its .json mirror (514,276,583 B); every record's json path is rooted at /proj/maverick/hannloui/pool_wa/…. The DB structure (records, fields, counts, view partition) is OBSERVED — streamed structurally from the shipped file. Any claim about what a v5 address does inside the silicon is INFERRED. The byte-grounded behavioral cross-check is the CAYMAN (NC-v3) flat YAML (address_map_flat.yaml); it is a different SoC instance and is used only for the generational deltas in §6. HIGH · OBSERVED for structure; [* · INFERRED] for v5 interiors.

Primary artifacts (all binary-derived, citeable):

(All under the gitignored extracted/ tree — use --no-ignore / absolute paths.)

0. Self-verify — the five headline claims

The five strongest claims are grounded directly against the .json mirror's name key (text only, zero pickle risk). The name key occurs exactly once per record (323,198 = the DB len), so a name-keyed token count is a true per-record count, not an inflated multi-field grep.

GOTCHA — count off the name key, not the raw line. A bare rg -c '"[^"]*TOP_SP' over the JSON returns 6,144, because the TOP_SP token also appears in the short_name (184) and json schema-path (48) keys. The authoritative record count is the name-keyed 5,912 (= 6,144 − 184 − 48). Every count on this page is name-keyed.

Two absences also hold (defining-by-what-is-not-there): SDMA, RDM, SPAD, TSYNC name-keyed counts are all 0 — Maverick names its DMA DDMA/CDMA, the Ring-Descriptor-Manager lives inside INTC as INTC_RDM (already in the ADDR-15 lane), and the TOP_SP's SPAD cc_op program + device tsync are runtime software structs (loaded into TOP_SP RAM at runtime), not address-mapped register blocks.

1. The TOP_SP subtree — the collective sequencer (engine 5)

TOP_SP appears in 5,912 records (pkl == JSON mirror, byte-identical). By view: user_int 936 / secure_int 4,976. By type: REGFILE 4,984 / TABLE 800 / NODE 128.

1a. Role

TOP_SP is engine 5, the on-device collective sequencer: an embedded Xtensa-NX core that walks the lowered collective program, issuing DMA tail-pointer increments and EVT_SEM arrive/wait/dec ops. It is distinct from the per-TPB TPB_SP (engine 4 — the 16 SP_0..15 sequencers inside each tensor block, carved in pkl-tpb-subtree.md). The CSR-side model is TOP_SP = TPB_EVT_SEM + RAM + NX-core; the lowering of barrier→semaphore sequences onto it is documented in ../../collectives/ops/top-sp-lowering.md and the CSR layout in ../csr/rdm-top-sp.md. [role HIGH (cross-CSR/CCL); engine-5-vs-4 split HIGH · OBSERVED]

1b. The TOP_SP_CLUSTER0 block — the dominant TOP_SP surface (1,344 records)

The SP_CLUSTER token carries 2,688 name-keyed records — and these are a subset of the 5,912 TOP_SP set (a TOP_SP_CLUSTER0 leaf name carries both tokens). The cluster is a REGFILE strip at parent-offset +0x55000. It hosts the collective-leg DGE command-injection engine — the stream-to-AXI command tables the TOP_SP uses to launch the SB2SB / DMA legs of a collective:

DGE_CMD_INJECT_TABLE 1,152 records; STREAM_TO_AXI tables 960 (size 0x80 each). This command-injection table engine is a Maverick addition — Cayman's TOP_SP carried no such tables (§6).

1c. The TOP_SP CSR leaves (top_sp_amzn.json)

The pkl record offsets match the on-disk top_sp_amzn.json schema byte-for-byte:

top_sp_misc_amzn.json exposes the write-ordering-buffer config the NX core uses to order its emitted DMA descriptors: wob / wob_wr_bypass / wob_wr_clear / wob_force_inorder / wob_use_wid_base / wob_wid_base. TPB_TOP_SP_SIDE_FABRIC = 40 NODE records, size 0x80000 (512 KiB) — the side-fabric aperture wiring TOP_SP into the TPB tile fabric.

1d. The NX sequencer core (xtensa_nx.json)

The physical Xtensa-NX control-CSR window is named TOP_NX_CORE_n (600 records, REGFILE, size 0x4000 = 16 KiB each, at TPB-parent offsets +0x5000/+0x9000/+0xd000, ≥3 cores per TPB). Because it carries no TOP_SP token, it physically lands in the ADDR-11 / TPB lane (under TPB_0), not the TOP_SP lane — important for the non-double-counting partition in §4. The engine-5 sequencer core is address-mapped; only its name path sits under TPB.

2. The sync / semaphore subtree

2a. The EVT_SEM 256-array (504 records)

name-key EVT_SEM = 504 (24 TPB_EVT_SEM containers × 21 recs/instance; by view user_int 288 / secure_int 216). Each container is type=NODE, size 0x100000 (1 MiB). Its window children are a byte-exact match to the EVT_SEM data-plane model documented (Cayman-grounded) in evt-sem-regions.md:

Each 0x400 window = 256 entries × 4 B → 256 hardware events + 256 hardware 32-bit semaphores, confirming the 256/256 model. The four-window aliasing (read/set/inc/dec all addressing the same 256 physical counters, with the address selecting the operation) and the byte-exact offsets 0x1000/0x1400/0x1800/0x1C00 are documented in full in evt-sem-regions.md. Bases agree with that page at TPB_0_EVT_SEM = 0x2802700000 (Cayman); the v5 equivalent is the same +0x1000-class window layout, view-relative.

CORRECTION/DELTA vs Cayman EVT_SEM (evt-sem-regions.md §1) [MED · OBSERVED]. The Cayman address-map tiles the 1 MiB container as 7 leaves with EVENT_RESERVED1 = 0xFE000 and no counter-inc bank. The Maverick pkl exposes an EXTRA SEMAPHORE_CNTR_INC bank at +0x2000 (size 0x4000), shrinking EVENT_RESERVED1 to 0xFA000. This is a v5-side addition — the counter-increment aperture used by the collective DMA-tail-doorbell path. Marked MED: observed in the pkl; its per-field semantics are not cross-checked against a separate Maverick CSR schema. The 6 original windows and the 256/256 model are unchanged.

EVT_SEM also appears as a LOCAL_EVT_SEM_n alias plane (the cluster-pseudo-base mirror; 8 LOCAL_EVT_SEM_0 + 8 LOCAL_EVT_SEM_1).

2b. COLLECTIVE_SYNC (48 records) — Maverick-new

name-key COLLECTIVE = 48 (24 LOCAL_ aliases). type=REGFILE, size 0x100000 (1 MiB) at parent-offset +0x2180000. This is the on-chip collective barrier-sync region the TOP_SP drives — the address-map home of the barrier→semaphore lowering. A COLL_SYNC short-name strip (16 + 16 reserved) sits inside it. Cayman's YAML has 0 COLLECTIVE records — this is a v5 collective-acceleration addition (§6).

2c. SP_SHARED_RAM (144 records) — Maverick-new

name-key SP_SHARED = 144 (8 banks SHARED_RAM_BANK_0..7 × 16 + 8 SP_SHARED_RAM

• 8 LOCAL_SP_SHARED_RAM). Container type=NODE, size 0x100000 (1 MiB) at +0x2280000 — the shared scratch the SP sequencers and the TOP_SP share for collective state. Again Cayman = 0 (§6).

2d. SPAD cc_op / device tsync — not address-mapped (absence)

The TOP_SP's SPAD cc_op command table and the device tsync struct are runtime software structs (the cc_op entry rides in the DMA CCE descriptor; the tsync struct is host-decoded), not register blocks. Confirming: name-key SPAD / TSYNC / TIMESTAMP = 0 records. The TOP_SP program is loaded into the TOP_SP RAM aperture at runtime; the address map exposes only the RAM window, never the program. [OBSERVED absence]

2e. RDM lives in INTC — no double-count (absence)

name-key RDM = 0. The Ring-Descriptor-Manager is embedded as INTC_RDM (a 0x1000 APB block) inside the INTC family — already counted in the pkl-intc-sprot-security.md lane. It is not under TOP_SP. No double-count.

3. The MISC / residual subtree

Everything in this lane that is not TOP_SP / EVT_SEM / COLLECTIVE / SP_SHARED is a real, schema-bound block family — no anonymous remainder. Two families:

3a. The URB routing fabric — the bulk of the residual

The Unified-Resource-Buffer is the on-die, TCAM-matched address-routing fabric plus its RAS logs (name-key URB = 15,624 whole-DB; the physical-partition residual that lands in this lane is 11,592 — the rest are URB-named leaves that first-match into other lanes, the same keyword-vs-lane overlap §4 explains):

3b. The PEB chiplet-management peripherals (the boot/clock/IO control plane)

Each lives in the PEB APB_IO container. Bases are view-relative (the example column shows the low bits; the view's top nibble — §4 of pkl-db.md — prefixes the domain); sizes and schemas are all verified on disk. The two count columns separate the whole-DB name-keyword family from the first-match lane residual (§4):

NOTE — name-keyword ≠ lane residual. The name-kw column above counts every record whose name contains the token anywhere in the DB (so GPIO 552 includes GPIO-named RAS/parity leaves that first-match into protection lanes). The first-match lane residual for the PEB peripherals (the slice that lands in this ADDR-16 lane and feeds §4) is ≈2,240. Both numbers are correct; they answer different questions (keyword family vs physical partition), exactly like every other family in §4.

ABSENCE — no EFUSE/BOOT block. name-key EFUSE / BOOT = 0. Efuse/boot is either folded into GLOBS/PLL or simply not address-mapped in this DB.

4. THE GRAND COVERAGE TALLY — every subtree vs 323,198

This is the page's headline result: does the union of all six engine subtrees account for every one of the 323,198 records, with zero remainder? It does — but only once the keyword-vs-lane distinction is handled correctly.

4.1 Why headline keyword counts cannot be summed

The per-subsystem keyword families overlap heavily: every IP block has its own embedded INTC, FIS protection, SPROT enforcement, and RAS log. So the report headline counts double-count — e.g. the FIS family (34,384) and INTC family (31,692) are distributed across every protected IP, physically residing inside the DMA / HBM / PCIe / TPB subtrees. Summing the headlines (TPB 42,360 + DMA 175,376 + HBM 31,604 + FIS 34,384 + INTC 31,692 + …) blows past 323,198. First-match distribution of the two worst offenders:

FIS  34,384 -> tpb 4,232 / dma 6,240 / hbm 7,192 / pcie 11,120 / intc 5,448 / topsp 152
INTC 31,692 -> tpb 2,952 / dma 17,856 / hbm 3,648 / pcie 7,008 / intc 228

i.e. INTC / FIS / SPROT / NOTIFIC are decentralized — embedded in every IP. The fix is a non-overlapping, exhaustive first-match partition.

4.2 The partition rule

Each of the 323,198 records is assigned to exactly one lane by priority-ordered name tokens (most-specific physical-IP token wins; embedded INTC/FIS/SPROT fold into their host IP, which is where they physically reside — so no double-count):

1. UCIE | D2D | PCIE                          -> pcie/d2d/fabric   (ADDR-14)
2. TOP_SP | SP_CLUSTER | EVT_SEM | COLLECTIVE | SP_SHARED
                                              -> topsp/sync        (ADDR-16)
3. DDMA | CDMA | UDMA                          -> dma              (ADDR-12)
4. TPB | DGE  (incl. the TOP_NX_CORE engine-5 cores, §1d)
                                              -> tpb              (ADDR-11)
5. HBM                                         -> hbm              (ADDR-13)
6. INTC | SPROT | NOTIFIC | FIS  (standalone, not IP-embedded)
                                              -> intc/sprot/sec    (ADDR-15)
7. everything else  (URB fabric + PEB peripherals)
                                              -> misc              (ADDR-16)

4.3 The tally (by lane × by access-domain view)

The partition was computed two ways — by lane (token first-match) and by view (rec['parent_names'][1]) — and both axes sum identically to 323,198:

  by-lane:  35,896 + 175,376 + 31,604 + 54,200 + 5,676 + 20,440 + 6 = 323,198   ✔
  by-view:  79,104 + 244,040 +     24 +     24 +     5 +      1     = 323,198   ✔
  residual = 323,198 − 323,198 = 0     *** COVERAGE PROVABLY COMPLETE ***

Every record lands in exactly one lane; both independent axes close to zero remainder.

4.4 Cross-checks against the sibling carve pages

⚠ keyword-vs-lane — the TPB, PCIe and INTC lanes differ from their page headlines, and that is correct. The sibling pages headline keyword-family counts (which overlap); the §4.3 table uses physical-partition lane counts (non-overlapping). The differences are expected and reconcile via §4.1's first-match distribution:

• TPB: pkl-tpb-subtree.md headlines 42,360 TPB-named records (a keyword family). The physical TPB lane is 35,896 — the 6,464 difference is TPB-named leaves whose more-specific token (DDMA/UCIE/HBM/…) first-matches into another lane. Both are correct.
• PCIe: the page reports UCIE 53,720, D2D 33,432, PCIE 50 — but these overlap (D2D ∩ UCIE = 33,000; D2D is inside UCIE). The non-overlapping union is UCIE 53,720 + D2D-only 432 sideband + PCIE 50 − 2 shared = 54,200 — the §4.3 lane total.
• INTC/SPROT: the page headlines the INTC keyword family 31,692 and type='INTC' fleet 5,904; the §4.3 standalone INTC/SPROT lane is 5,676 — the rest fold into their host IP (DMA 17,856 + HBM 3,648 + …, per §4.1). No double-count.

Keyword counts answer "how many records mention X anywhere?"; lane counts answer "where does each record physically live?" Only the lane partition can sum to 323,198.

4.5 The ADDR-16 lane internal breakdown

TOP_SP / sync union      6,608  = TOP_SP 5,912 (SP_CLUSTER 2,688 ⊂ TOP_SP; both tokens
                                    on the same TOP_SP_CLUSTER0 leaf, NOT additive)
                                  + EVT_SEM 504 + COLLECTIVE 48 + SP_SHARED 144
MISC residual           13,832  = URB fabric 11,592 + PEB peripherals ~2,240
------------------------ ------
ADDR-16 lane TOTAL      20,440  EXACT

5. Reference pseudocode — the TOP_SP/MISC carve + coverage reconciliation

"""Carve the TOP_SP / sync / MISC subtree and prove total coverage == 323,198.

SAFETY: never pickle.load(). Stream the .json mirror (Recipe C from pkl-db.md):
ijson yields ONE record dict at a time, O(1) memory, zero pickle risk. A single
pass classifies every record into exactly one lane AND tallies the view axis.
"""
import ijson

JSON = ".../arch-headers/maverick/ext/al_address_map_db.json"

# Priority-ordered first-match token rule (most-specific physical-IP token wins).
# Order matters: a TOP_SP_CLUSTER0 DGE leaf must hit TOPSP (rule 2) before TPB/DGE
# (rule 4); a UCIE-embedded D2D leaf must hit PCIE (rule 1) before anything else.
LANE_RULES = [
    ("pcie",  ("UCIE", "D2D", "PCIE")),
    ("topsp", ("TOP_SP", "SP_CLUSTER", "EVT_SEM", "COLLECTIVE", "SP_SHARED")),
    ("dma",   ("DDMA", "CDMA", "UDMA")),
    ("tpb",   ("TPB", "DGE")),              # incl. TOP_NX_CORE engine-5 cores (§1d)
    ("hbm",   ("HBM",)),
    ("intc",  ("INTC", "SPROT", "NOTIFIC", "FIS")),
    # rule 7 ("misc") is the catch-all fall-through below.
]

def classify(name: str) -> str:
    """Assign one address-map record to exactly one physical lane by first match."""
    for lane, tokens in LANE_RULES:
        if any(tok in name for tok in tokens):
            return lane
    return "misc"        # URB fabric + PEB peripherals + the root/views land here...

def coverage_tally(json_path: str) -> tuple[dict, dict, int]:
    """One streaming pass. Returns (by_lane, by_view, total).

    by_lane[lane]            -> record count in that physical partition
    by_view[parent_names[1]] -> record count per access-domain view (independent axis)
    The two dicts MUST sum to the same total (the closure proof).
    """
    by_lane: dict[str, int] = {}
    by_view: dict[str, int] = {}
    total = 0
    with open(json_path, "rb") as f:
        for rec in ijson.items(f, "item"):     # O(1) memory; no code path executes
            total += 1
            pn = rec.get("parent_names", [])
            # --- view axis (independent of the lane partition) ---------------------
            if len(pn) >= 2:                   # a real leaf: parent_names[1] == view
                view = pn[1]
            elif len(pn) == 1:                 # a top-level VIEW node (child of root)
                view = "_view_node_"
            else:                              # parent_names == [] -> the root
                view = "_root_"
            by_view[view] = by_view.get(view, 0) + 1
            # --- lane axis (first-match physical partition) ------------------------
            if view in ("_root_", "_view_node_"):
                lane = "root_view"             # 6 structural nodes, no IP token
            else:
                lane = classify(rec["name"])
            by_lane[lane] = by_lane.get(lane, 0) + 1
    return by_lane, by_view, total

def assert_closure(by_lane: dict, by_view: dict, total: int) -> None:
    """The closure proof: BOTH axes sum to `total`, residual == 0, total == 323,198."""
    lane_sum = sum(by_lane.values())
    view_sum = sum(by_view.values())
    assert lane_sum == total, f"lane axis leaks {total - lane_sum} records"
    assert view_sum == total, f"view axis leaks {total - view_sum} records"
    assert total == 323_198,  f"record total drifted to {total}"
    print(f"COVERAGE COMPLETE: {total} records, residual 0 on both axes")

# by_lane, by_view, total = coverage_tally(JSON)
# assert_closure(by_lane, by_view, total)
#   -> by_lane  {pcie:54200, topsp+misc:20440, dma:175376, tpb:35896,
#                hbm:31604, intc:5676, root_view:6}
#   -> by_view  {secure_int:244040, user_int:79104, user_pciea:24,
#                secure_pciem:24, _view_node_:5, _root_:1}
#   -> COVERAGE COMPLETE: 323198 records, residual 0 on both axes

NOTE. classify() folds the ADDR-16 lane's topsp and misc rules into one physical lane (rule 2 + the catch-all) — matching §4.3's combined topsp/sync/misc = 20,440 row. Split them (return "misc" only for the catch-all) to recover the §4.5 sub-breakdown.

6. MAVERICK-vs-CAYMAN deltas for TOP_SP / sync [HIGH · OBSERVED + MED]

Read from the shipped CAYMAN address_map_flat.yaml (a different SoC instance — used only for the generational delta, per the WALL). Cayman's TOP_SP_0 is a 256 KiB container with explicit sub-blocks +0x0 NOTIFIC, +0x1000 RAM/RAM_CONFIG (top_sp_ram.json), +0x4000 TOP_SP_MISC_USER, +0x8000 NX_CORE (xtensa_nx.json). Cayman counts: TOP_SP ~1,860 lines / EVT_SEM 384 / COLLECTIVE 0 / SP_SHARED 0.

The TOP_SP core role is frozen Cayman==Maverick (engine-5 NX sequencer; EVT_SEM arrive/wait/dec; DMA-tail doorbell). The deltas are (a) security-tightening (MISC_USER removed) and (b) collective acceleration (explicit COLLECTIVE_SYNC + SP_SHARED + cluster cmd-inject tables added). The role-freeze is HIGH; the "acceleration" reading of the v5 additions is INFERRED.

7. Confidence ledger

HIGH · OBSERVED (off the name key; pkl == JSON mirror):

• TOP_SP family 5,912 (user_int 936 / secure_int 4,976); type split 4,984 / 800 / 128.
• SP_CLUSTER 2,688 ⊂ TOP_SP (not additive); DGE cmd-inject 1,152 + stream-to-AXI 960.
• TOP_SP CSR leaves match top_sp_amzn.json byte-for-byte; TOP_SP_MISC_AMZN 48.
• EVT_SEM 504 (24×21; views 288/216); the +0x1000/1400/1800/1C00 256-array windows byte-match evt-sem-regions.md.
• COLLECTIVE_SYNC 48 + SP_SHARED_RAM 144 (Maverick-new vs Cayman 0).
• MISC residual fully named: URB fabric (lane 11,592) + PEB peripherals (~2,240); all schemas on disk; no anonymous remainder; no EFUSE/BOOT block.
• GRAND TALLY: non-overlapping first-match partition sums EXACTLY 323,198, residual 0 on BOTH the lane axis and the independent access-domain-view axis. Clean lanes (DMA 175,376, HBM 31,604, TOP_SP 5,912) match their sibling-page headlines exactly.
• Absences: SDMA / RDM / SPAD / TSYNC / EFUSE / BOOT / TOP_SP_MISC_USER all 0. RDM lives in INTC (INTC_RDM), already in the ADDR-15 lane — no double-count.

MED:

• EVT_SEM SEMAPHORE_CNTR_INC @ +0x2000: observed in pkl; per-field semantics not Maverick-schema-verified.
• top_sp_ram.json TOP_SP-named binding absent in Maverick (aperture persists).
• "Collective acceleration" reading of the Maverick additions is INFERRED.
• Keyword-family vs physical-lane counts (TPB 42,360 vs 35,896; INTC 31,692 vs 5,676 lane; PCIe overlap) — both correct; they reconcile only via the §4.1 first-match distribution.

WALL: all v5 interior behavior is INFERRED — the Cayman YAML (§6) is the only byte-grounded behavioral cross-check and is a different SoC instance.

See also

• pkl-db.md — the safe-load primitive, 23-field schema, 5 views, type taxonomy
• evt-sem-regions.md — the EVT_SEM 256-event/256-semaphore data plane (Cayman byte-exact)
• ../csr/rdm-top-sp.md — the TOP_SP / rdm_model CSR layout
• ../../collectives/ops/top-sp-lowering.md — barrier→semaphore lowering onto engine 5
• Sibling carve pages: TPB · DMA · HBM · PCIe/D2D · INTC/SPROT
• block-schema-xref.md — the block→RTL-schema mapping