TheRock/rocm-systems/docs/superpowers/specs/2026-07-24-msc-atomic-alias-coherence-design.md

MSC Atomic Alias Coherence Design

Context

L2Cache::atomic_rmw acquires the device-wide atomic boundary before accessing backing memory. The boundary flushes every registered L2 and then advances the global coherence epoch while holding the L2 maintenance locks.

The direct-memory path therefore observes the flushed value. The linked-port path instead reads through MemorySideCache (MSC). MSC is write-through and keys clean cache lines by (VMID, GPU virtual address). If two such keys alias the same host storage, a clean line under one key can remain stale after another key publishes dirty L2 data. An atomic RMW through the stale key can consequently use the old value.

Goals

• Make linked-port atomic RMWs observe the authoritative value after all L2 dirty data has been published.
• Ensure stale MSC aliases are not visible after a coherence epoch change.
• Preserve the existing device-wide atomic serialization and L2 locking model.
• Avoid scanning or invalidating the entire 128 MiB MSC on every atomic.
• Add regression coverage for two L2s sharing one MSC and HBM through aliased VMID/virtual-address mappings.
• Remove the unused register_cache helper so there is one L2 registration implementation and one ordering invariant.

Design

Each MSC cache tag will record the device-coherence epoch at which its line was filled or refreshed. MSC already protects tag lookup and replacement with the corresponding stripe lock, so the epoch metadata will use that same protection.

On an MSC access:

1. Look up the (VMID, GPU virtual address) cache line under its stripe lock.
2. Compare the tag's recorded epoch with DeviceCacheCoherence::current_epoch().
3. If the epochs differ, require the old entry to be clean, invalidate it, and refill the line from backing HBM.
4. Stamp a newly filled or refreshed entry with the current epoch.
5. Continue the requested read or write.

The atomic boundary's existing order remains unchanged:

1. Acquire the global exclusive coherence lock.
2. Lock every registered L2 maintenance mutex in sorted address order.
3. Flush dirty L2 data through MSC to HBM.
4. Advance the global coherence epoch.
5. Perform the linked-port RMW while the boundary remains held.

After step 4, any MSC alias retained from an earlier epoch is stale. The RMW read therefore invalidates and refills that alias from HBM, where step 3 published the authoritative value. Other old aliases are invalidated lazily on their next access.

MSC is write-through, so an epoch-stale entry is expected to be clean and can be discarded without losing data. No MSC registration or new global lock is needed.

Alternatives

Eagerly flush and invalidate the entire MSC

Registering MSC with the atomic boundary and calling flush_all() would be simple, but it scans 1,048,576 tags and locks all 256 stripes for every atomic. That cost is disproportionate to an individual RMW.

Bypass MSC only for atomic backing accesses

Sending the RMW directly to HBM would obtain the correct operand, but clean MSC aliases could remain stale and be returned after the atomic. A generation or invalidation mechanism would still be required, while the backing protocol would become more complex.

Validation

Add a regression with two L2 caches linked to one MSC and HBM controller:

1. Map different (VMID, GPU virtual address) pairs to the same host word.
2. Read through the second alias to retain a clean MSC value of 0.
3. Dirty 40 through the first L2 without immediately publishing it.
4. Increment through the second L2's atomic RMW.
5. Verify the callback observes 40, the atomic result and host word are 41, and subsequent reads through both aliases return 41.

Run the focused L2/MSC tests in Release and under TSan, followed by the relevant non-benchmark test suite.

Measure end-to-end performance against commit b685943638 using representative large kernels from rocjitsu-test-corpus, including a large softmax, a large pack/unpack case, and a large matrix multiplication. Use the same pinned-CPU, alternating-run methodology as the previously published PR benchmark where the harness permits it.