@kernaut/kernaut-resources 0.1.17-beta.1 → 0.1.18

package/resources/kop-2026-10-23-0.1.17-beta.1/product_capabilities/kernel_optflow/skills/KernelWiki-private/wiki/nvidia/foundations/sync/barrier-optimization.md

@@ -1,285 +0,0 @@
----
-title: Barrier Optimization (scope, async-split, arrive/wait)
-status: verified
-evidence_level: measured
-cuda_version_tested: '12.9'
-driver_version_tested: 570.124.06
-toolchain: nvcc 12.9.86 + ptxas 12.9
-measured_on: H200-SXM
-applies_to_pattern_class:
-- cuda-core
-applies_to_ops:
-- reduction
-- normalization
-- scan
-- synchronization
-requires_sm: '>=7.0'
-requires_features:
-- block-barrier
-- async-barrier
-single_kernel_useful: true
-source:
-- path: spec
-  anchor: Reference
-artifacts:
-  code: artifacts/experience/hw-probes/barrier-cost/barrier_cost_probe.cu
-  build: artifacts/experience/hw-probes/barrier-cost/build.sh
-  introspection: artifacts/experience/hw-probes/barrier-cost/device.json
-  profile: ''
-related_apis:
-- __syncthreads
-- __syncwarp
-- cuda::barrier
-- cuda::pipeline
-- mbarrier.init
-- mbarrier.arrive
-- mbarrier.try_wait
-related_skills:
-- memory-ordering
-- warp-primitives
-- async-copy
-- warp-divergence
-id: skill-barrier-optimization
-type: skill
-vendor: nvidia
-tags:
-- cuda-cpp
-- tma
-- mbarrier
-- cluster
-- pipeline-stages
-- shared-memory-optimization
-- communication-overlap
-- fused-kernel
-- ptx
-applies_to:
-- general
-source_refs:
-- source_id: cuda-official/toolkit-docs-13.2
-  path: CUDA Programming Guides/cuda-c-best-practices-guide/cuda_cuda-c-best-practices-guide_index.html.md
-  anchor: L1402-L1404
-- source_id: cuda-official/toolkit-docs-13.2
-  path: CUDA Programming Guides/cuda-programming-guide/cuda_cuda-programming-guide_index.html.md
-  anchor: L3647-L3704
-- source_id: cuda-official/toolkit-docs-13.2
-  path: CUDA Programming Guides/parallel-thread-execution/cuda_parallel-thread-execution_index.html.md
-  anchor: L19217-L19237
-- source_id: cuda-official/toolkit-docs-13.2
-  path: CUDA Programming Guides/parallel-thread-execution/cuda_parallel-thread-execution_index.html.md
-  anchor: L20580-L20600
-architectures:
-- sm90
-- sm90a
-languages:
-- ptx
-- cuda-cpp
-hardware_features:
-- tma
-- mbarrier
-- cluster
-techniques:
-- pipeline-stages
-- shared-memory-optimization
-- communication-overlap
-kernel_types:
-- fused-kernel
-confidence: experimental
-artifact_dir: artifacts/experience/hw-probes/barrier-cost
----
-## What
-
-A **barrier** is a synchronization primitive that forces a group of threads to all reach the same program point before any of them proceeds. CUDA offers a hierarchy of barriers, each with its own scope, memory backing, and hardware acceleration:
-
-- **`__syncwarp(mask)`** — 32-lane (or subset) warp barrier. The cheapest barrier available; on sm_70+ it is explicit hardware reconvergence after Independent Thread Scheduling diverges lanes.
-- **`__syncthreads()`** — whole-block barrier, backed by PTX `bar.sync` with 16 named barrier slots per SM. Per BP §12.1.3 (L1402-L1404), its **throughput is 16 ops/clock on sm_7.x and sm_8.x**; the per-call wall-clock cost is dominated by the "SM idles until all threads arrive" stall, not by the barrier instruction throughput.
-- **`cuda::barrier<thread_scope_block>` (mbarrier)** — memory-backed asynchronous barrier with separate `arrive` and `wait` phases (PG §3.2.4.2, L3647-L3704). Hardware-accelerated on sm_80+. The key advantage is **temporal splitting**: a thread signals arrival, does other work, and only blocks later when it actually needs the synchronization.
-- **`cuda::barrier` with `mbarrier.arrive.expect_tx`** — extension that tracks **byte counts** of async copies (TMA, `cp.async`), so the barrier completes when both thread arrivals and copy completions are satisfied. This is the correct synchronization primitive for pipelined producer-consumer patterns, replacing the deprecated `cuda::pipeline` shape.
-- **`barrier.cluster.arrive` / `barrier.cluster.wait`** — cluster scope barriers (sm_90+). Only required for distributed shared memory or multi-block coordination; out of scope for most cuda-core kernels.
-
-Correct choice depends on **who needs to synchronize with whom**. The pathological default is `__syncthreads()` everywhere; the optimized pattern narrows to the smallest group that actually needs to see the write.
-
-## Why
-
-Barrier cost shows up two ways:
-
-1. **Instruction cost** — the fixed cycles to issue and retire the barrier instruction itself. Small (single digits on sm_9.0a for `__syncwarp`, ~10s for `__syncthreads`).
-2. **Idle time** — the time spent waiting for the *slowest* thread (or async operation) to arrive. This is usually 10–100× the instruction cost. BP §12.1.3 (L1404) captures this: `__syncthreads` "can impact performance by forcing the multiprocessor to idle".
-
-The goal of this skill is **not** to reduce instruction cost (the barrier itself is cheap). It is to reduce **idle time** by (a) narrowing scope so fewer threads are ever waiting on one another, (b) splitting `arrive` from `wait` so each thread does useful work between the two, and (c) letting hardware (mbarrier with expect_tx) track async-copy progress without holding threads hostage.
-
-PG §3.2.4.2 (L3647-L3704) documents the mechanism explicitly: "separation [between arrive and wait] increases execution efficiency by allowing a thread to perform additional operations unrelated to the barrier". Sub-skills S1–S4 below are the four practical patterns for exploiting that.
-
-## When to use
-
-### S1. Narrow the scope to the smallest group that must actually sync
-
-The single highest-impact decision in barrier placement is **which group is synchronizing**. Prefer the narrowest scope that is correct:
-
-```
-warp-local work           → __syncwarp(0xFFFFFFFFu) (or nothing,
-                            if your warp intrinsic is already _sync)
-block-level work          → __syncthreads() or block.sync()
-sub-block subset          → cuda::barrier with expected_count < blockDim
-async-copy completion     → mbarrier with expect_tx
-cluster-level (sm_90+)    → barrier.cluster.arrive/wait
-```
-
-```cuda
-// Typical block-level reduction tail — __syncthreads is necessary
-// because the warp-partial-sums written to smem[warpId] must be
-// visible to warp 0.
-smem[warpId] = warp_reduce(val);
-__syncthreads();                    // block-wide
-if (warpId == 0) {
-    val = (laneId < NWARP) ? smem[laneId] : 0;
-    val = warp_reduce(val);         // _sync shuffles, no extra barrier
-}
-
-// BUT: if the reduction is purely intra-warp (N ≤ 32), no
-// __syncthreads is needed. Shuffle + _sync suffices.
-```
-
-Common smell: a kernel that only does intra-warp work uses `__syncthreads()` "to be safe". Each such call stalls 31 other warps on average. Replace with `__syncwarp()` if any barrier is needed at all (usually **none** is needed if the warp-shuffle is the `_sync` variant, per the warp-divergence skill's ITS discussion).
-
-### S2. Split arrive from wait with `cuda::barrier` (hw-accel on sm_80+)
-
-When the post-barrier consumer also has independent pre-wait work, split arrival from wait:
-
-```cuda
-#include <cuda/barrier>
-#include <cooperative_groups.h>
-namespace cg = cooperative_groups;
-
-__global__ void producer_consumer_kernel(const float* in, float* out, int N) {
-    __shared__ cuda::barrier<cuda::thread_scope_block> bar;
-    __shared__ float staging[BLOCK];
-    auto block = cg::this_thread_block();
-
-    if (block.thread_rank() == 0)
-        init(&bar, block.size());
-    block.sync();                            // one-time init sync
-
-    // ---- Produce phase ----
-    staging[threadIdx.x] = compute_A(in[threadIdx.x]);
-    auto token = bar.arrive();               // signal, do NOT block
-
-    // ---- Independent work between arrive and wait ----
-    float local = compute_B_independent(threadIdx.x);
-
-    // ---- Wait only when staging[] is actually needed ----
-    bar.wait(std::move(token));
-    out[threadIdx.x] = staging[(threadIdx.x + 1) % BLOCK] + local;
-}
-```
-
-The `compute_B_independent` body overlaps with other threads' producer work. On sm_80+ this overlap is hardware-accelerated: the barrier sits in shared memory and the `mbarrier.arrive` instruction returns immediately after incrementing the count.
-
-### S3. Use `mbarrier` with `expect_tx` for async-copy pipelines
-
-For kernels that stream data from global to shared memory via `cp.async` or TMA, the correct synchronization primitive is an mbarrier that tracks transaction byte counts. This is what the `async-copy` skill pairs with:
-
-```cuda
-// (Simplified; see async-copy skill for the full pipeline.)
-__shared__ cuda::barrier<cuda::thread_scope_block> bar;
-if (threadIdx.x == 0) init(&bar, 1);
-__syncthreads();
-
-// Declare total expected bytes, then kick off cp.async instructions.
-if (threadIdx.x == 0)
-    cuda::ptx::mbarrier_arrive_expect_tx(
-        cuda::device::barrier_native_handle(bar), BYTES_IN_TILE);
-
-// Every cp.async.* that targets smem also arrives on bar via the
-// .mbarrier.arrive suffix in PTX.
-
-bar.wait(bar.arrive());    // blocks until tx count is satisfied
-// smem[] is now safe to consume.
-```
-
-### S4. Prefer block-level reduction in smem over cross-block synchronization
-
-When a reduction / scan has to span more than one block, a common anti-pattern is a global counter with `atomicCAS`-based spin-locks. The right answer is almost always **two-pass launch** — each block reduces into a per-block slot, then a second kernel reduces the slots. See the `atomic-reduction` skill (S1 hierarchical pattern).
-
-The only time cluster-level `barrier.cluster.*` is appropriate is when the kernel uses distributed shared memory across blocks of the same cluster (sm_90+); that is a separate skill under `wiki/nvidia/hardware/thread-block-cluster/` (pending bucket F).
-
-## When NOT to use
-
-- **When the synchronization is already handled by `_sync` warp intrinsics.** `__shfl_down_sync` / `__ballot_sync` each embed their own warp-sync semantics; adding `__syncwarp` before them is pure overhead. Do it only if the preceding code diverged and needs explicit reconvergence (per the `warp-divergence` skill pitfall P1).
-- **When narrowing scope breaks correctness.** If warp 0 reads smem written by warp 3, you need `__syncthreads()`. Swapping to `__syncwarp()` is not an optimization, it is a bug.
-- **When the kernel is already memory-bound at a healthy SOL.** A barrier that currently contributes < 5 % of stall cycles is not the bottleneck. Check NCU `smsp__warps_issue_stalled_barrier.pct` first; if it is already low, the barrier is not the problem. This is the skill's own version of the "profile first" rule.
-- **When mbarrier would add more smem + instructions than it saves.** Legacy pitfall P6 (measured): `cuda::barrier` objects consume additional smem and emit more setup instructions; on small kernels with no independent work to overlap, plain `__syncthreads()` is cheaper.
-
-## Measured Characteristics
-
-Measured on H200-SXM (sm_90a, CUDA 12.9, driver 570.124.06) using sources/experience/hw-probes/barrier-cost/ — per-call cost of three barrier primitives at block sizes {128, 256, 512, 1024}. 10,000 barrier calls per inner loop, CUDA-events timing. Full record: sources/experience/hw-probes/barrier-cost.md.
-
-### ns per barrier call
-
-| Block | `__syncwarp` | `__syncthreads` | `mbarrier arrive+wait` | mbarrier / syncthreads |
-| ----- | -----------: | --------------: | ---------------------: | ---------------------: |
-| 128   |        14.61 |           31.81 |                  50.50 |                  1.59× |
-| 256   |        14.61 |           36.35 |                  52.53 |                  1.45× |
-| 512   |        15.43 |           44.44 |                  74.37 |                  1.67× |
-| 1024  |        22.13 |           61.51 |                 137.17 |              **2.23×** |
-
-### Scaling factor (cost at B=1024 ÷ cost at B=128)
-
-| Primitive              | Scaling factor |
-| ---------------------- | -------------: |
-| `__syncwarp`           |          1.51× |
-| `__syncthreads`        |          1.93× |
-| `mbarrier arrive+wait` |      **2.72×** |
-
-Key measured findings:
-
-- **Cost hierarchy is warp → block → mbarrier**, with measured ratios roughly 1 : 2–3 : 3–6 at typical block sizes. Skill §S1 "narrow the scope" is data-backed: `__syncthreads` → `__syncwarp` where correct saves ~2× per-call cost.
-- **`__syncthreads` scales sub-linearly with block size** (1.93× for 8× the threads), consistent with BP §12.1.3's "16 ops/clock" throughput on sm_8.x (no sm_9.0a-specific revision of the claim).
-- **mbarrier bare cost is a loss without overlap**: 1.6–2.2× slower than `__syncthreads` in a tight arrive+wait loop. The skill's §S2 (arrive/wait split) pays off **only** when there is real independent work of ≥ 100 cycles between arrive and wait — pitfall P6 upgraded from legacy-anecdotal to measured.
-- **NCU Compute SOL for single-block kernels sits near 0.11 %** — the 131 unused SMs idle. This is expected and the NCU pass is useful only as corroboration; wall-clock ns/call is the authoritative measurement for barrier primitives.
-
-The "arrive/wait overlap" variant of this probe (workload-dependent; real compute between `arrive` and `wait`) is a follow-up at `sources/experience/hw-probes/barrier-async-overlap/` (open).
-
-## Principles
-
-1. **Narrow scope, not fewer barriers.** Deleting a required barrier is a correctness bug; narrowing `__syncthreads` to `__syncwarp` is almost always correct and free.
-2. **Arrive is cheap, wait is expensive.** Splitting them only helps when there is real independent work between the two. Otherwise `__syncthreads` is cheaper.
-3. **Barriers report SM idle time, not instruction cost.** The NCU metric of interest is `smsp__warps_issue_stalled_barrier_per_issue_active.pct`, not instruction throughput.
-4. **Always re-converge before `mbarrier.arrive`.** Per PG §4.9.2.1 and pitfall P1, a divergent warp issues per-lane arrivals and the count completes too early.
-
-## Open questions
-
-- Q1. What is the actual per-call cycle cost of `__syncthreads` vs `mbarrier arrive+wait` on sm_90a H200 at block sizes 128 / 256 / 512 / 1024? Probe 2026-04-22 targets exactly this; measured section populated on completion.
-- Q2. For the overlap case (S2 with real independent work), what is the minimum independent-work size where mbarrier-split beats `__syncthreads`? Follow-up probe: `sources/experience/hw-probes/barrier-async-overlap/`.
-- Q3. Does `barrier.cluster.arrive` / `wait` on sm_90 add enough cost over `__syncthreads` that cluster-level kernels should budget one extra pass? Depends on DSMEM probe at `wiki/nvidia/hardware/thread-block-cluster/` (pending bucket F).
-
-## Legacy references
-
-- `legacy_sandbox_path`: `KernelPilot/optimization/synchronization/barrier-optimization/skill.md`. Legacy kept six sub-skills (S1–S6); this port keeps the four that are single-kernel-relevant (S1 async barriers → S2, S2 warp vs block → S1, S3 mbarrier expect_tx → S3, S6 minimize scope → S1 guidance). S4 cluster barriers is routed to the pending `wiki/nvidia/hardware/thread-block-cluster/` skill. S5 `__nanosleep` applies to spin-wait patterns (lock-based producer-consumer) and fits better under a future `wiki/nvidia/foundations/sync/spin-wait/` if one materializes — not migrated in this pass; pitfall P8 in `pitfalls.md` records the measurement caveat.
-- Legacy L3 sandbox findings P6–P9 are retained in `pitfalls.md` pending H200 re-measurement.
-- **Related but distinct**: `wiki/nvidia/foundations/sync/memory-ordering/` covers the *visibility* semantics around barriers; this skill covers the *cost and placement* of the barriers themselves. The two are complementary.
-
-## Grid-level synchronisation is a different cost class
-
-`__syncthreads()` synchronises one block on one SM. Synchronising the whole
-grid -- `cooperative_groups::this_grid().sync()` under a cooperative launch, or
-simply ending the kernel and starting another -- is a different mechanism with a
-different price:
-
-| Scope | Mechanism | What has to happen |
-|---|---|---|
-| Block | `bar.sync` (16 named barrier slots per SM) | warps of one block converge on one SM |
-| Cluster (sm_90+) | `barrier.cluster.arrive` / `wait` | blocks of one cluster converge across a few SMs |
-| Grid | cooperative launch + `grid.sync()`, or a kernel boundary | **every** block must be resident simultaneously, so the grid is capped at what fits on the device at once |
-
-The grid case carries a constraint the others do not: a cooperative launch
-cannot oversubscribe. The grid size is bounded by
-`cudaOccupancyMaxActiveBlocksPerMultiprocessor * SM_count`, which removes the
-scheduler's ability to hide a tail by running the next block.
-
-⚠️ *Ordering these three by measured cost is open -- see Q3 in the open questions
-of this page, which asks the same thing about the cluster barrier and is still
-unmeasured. What is stated above is mechanism and constraint, not a benchmark.*
-
-> The practical consequence is already recorded elsewhere on this page: when a
-> reduction needs a device-wide barrier, **two-pass launch is almost always the
-> right answer** rather than a cooperative launch or a hand-rolled spin lock.

package/resources/kop-2026-10-23-0.1.17-beta.1/product_capabilities/kernel_optflow/skills/KernelWiki-private/wiki/nvidia/foundations/sync/host-device-sync.md

@@ -1,124 +0,0 @@
----
-title: Host-Device Synchronization Cost
-status: draft
-evidence_level: anecdotal
-applies_to_pattern_class:
-- cuda-core
-applies_to_ops:
-- elementwise
-- reduction
-- gemm
-requires_sm: '>=6.0'
-requires_features: []
-single_kernel_useful: false
-source:
-- path: spec
-  anchor: Reference
-related_apis:
-- cudaDeviceSynchronize
-- cudaStreamSynchronize
-- cudaMemcpy
-- cudaMemcpyAsync
-- cudaEventSynchronize
-related_skills:
-- persistent-kernel
-- kernel-fusion
-id: skill-host-device-sync
-type: skill
-vendor: nvidia
-tags:
-- cuda-cpp
-- kernel-fusion
-applies_to:
-- general
-architectures:
-- sm90
-- sm90a
-- sm100
-- sm100a
-languages:
-- cuda-cpp
-techniques:
-- kernel-fusion
-confidence: experimental
-related: []
-sources: []
-aliases:
-- host-device sync
-- cudaDeviceSynchronize
-- implicit synchronization
-- pipeline bubble
----
-## What
-
-A **host-device synchronization** is any point where the CPU must wait for the GPU
-to finish work already submitted, or the GPU must wait for the CPU to submit more.
-Either direction produces a **pipeline bubble**: the GPU has capacity and no work.
-
-The explicit form is `cudaDeviceSynchronize()` or `cudaStreamSynchronize()`. The
-form that costs people more is the **implicit** one -- a blocking `cudaMemcpy`
-device-to-host is a synchronization even though nothing in the call name says so.
-
-> ⚠️ **This page is `draft` / `anecdotal`.** It records the shape of the problem
-> and the API surface, transcribed from an internal guideline document. **No
-> bubble cost has been measured on our hardware.** A measured version needs a
-> probe that times a fixed kernel sequence with and without a sync between
-> launches, on a named machine and CUDA version -- the way
-> [coalescing](../memory/coalescing.md) records its numbers.
-
-## Why
-
-GPU work is submitted asynchronously so the CPU can run ahead and keep the queue
-full. Every synchronization drains that queue: the run-ahead distance collapses to
-zero and has to be rebuilt. The cost therefore is not one API call's latency, it is
-**the launch pipeline you stop refilling while you wait**.
-
-This is why the damage scales with how control-flow-heavy the application is. A
-loop that launches one kernel, reads one scalar back to decide the next iteration,
-and repeats, pays the bubble once per iteration.
-
-## When it shows up
-
-- **Reading a scalar back to branch on it.** The classic: copy one `int` D2H to
-  decide whether to launch the next kernel.
-- **Timing instrumentation left in.** A `cudaDeviceSynchronize()` added to make a
-  timer meaningful, then never removed.
-- **Blocking `cudaMemcpy` in a loop.** The asynchronous variant plus a stream is
-  usually a drop-in replacement.
-- **Error checking after every launch.** `cudaGetLastError()` does not
-  synchronize; `cudaDeviceSynchronize()` inside an error-check macro does.
-
-## What to do instead
-
-Ranked by how much structure they demand:
-
-1. **`cudaMemcpyAsync` + streams** for the transfers that do not need to complete
-   before the next launch.
-2. **CUDA Graphs** when the launch sequence is fixed. This removes per-launch CPU
-   work as well as the sync, which is why it helps most in the
-   many-tiny-kernels regime.
-3. **Device-side control flow** -- keep the branch decision on the device instead
-   of round-tripping the scalar. Grouped GEMM APIs that take shapes from device
-   memory exist for exactly this reason; see the CUDA 13.2 notes on
-   [B200 Specs](../../hardware/foundation/b200-specs.md).
-4. **Kernel fusion** or a
-   [persistent kernel](../../techniques/persistent-kernels.md) -- if the launches
-   disappear, so do the syncs between them.
-
-## When NOT to worry about it
-
-- **One sync at the end of a long-running kernel** is not a bubble; there is
-  nothing left to overlap.
-- **Debugging.** `cudaDeviceSynchronize()` after a launch is how you get an error
-  attributed to the right kernel. Keep it under a debug flag, not in the hot path.
-- **Kernels that already saturate the device.** If the GPU is busy for
-  milliseconds per launch, a microsecond-scale bubble is noise. Measure before
-  restructuring.
-
-## How to see it
-
-There is **no NCU counter for this** -- NCU profiles a kernel, and the bubble is
-between kernels. It shows up as gaps in a timeline (Nsight Systems) or as a
-launch-rate ceiling. That asymmetry is worth stating plainly: a kernel-level
-profiler will report every individual kernel as healthy while the application
-wastes most of its wall clock waiting.

package/resources/kop-2026-10-23-0.1.17-beta.1/product_capabilities/kernel_optflow/skills/KernelWiki-private/wiki/nvidia/foundations/sync/memory-ordering/apis.md

@@ -1,151 +0,0 @@
----
-func_name: cuda::atomic
-namespace: runtime
-header: <cuda/atomic>
-signature: template <class T, cuda::thread_scope Scope = cuda::thread_scope_system> class cuda::atomic
-status: documented
-has_end_to_end_example: false
-source:
-- path: spec
-  anchor: Reference
-id: api-memory-ordering-ref
-type: api-definition
-vendor: nvidia
-title: Apis
-source_refs:
-- source_id: cuda-official/toolkit-docs-13.2
-  path: CUDA Programming Guides/cuda-programming-guide/cuda_cuda-programming-guide_index.html.md
-  anchor: L3534-L3551
-architectures:
-- sm90
-- sm90a
-languages:
-- ptx
-- cuda-cpp
-hardware_features:
-- cluster
-techniques:
-- cache-policy
-confidence: inferred
-evidence_level: inferred
-tags:
-- cluster
-- cache-policy
-- ptx
-- cuda-cpp
----
-# Memory Ordering API Reference
-
-This file lists the APIs touched by the memory-ordering skill. Each entry records the function or type name, namespace, and signature as found in upstream documentation.
-
-## Scoped Atomic Types (libcu++)
-
-### `cuda::atomic<T, Scope>`
-
-- **Namespace**: `cuda`
-- **Header**: `<cuda/atomic>`
-- **Signature**: `template <class T, cuda::thread_scope Scope = cuda::thread_scope_system> class cuda::atomic`
-- **Semantics**: An atomic type that provides atomic operations on `T` with C++ standard memory ordering semantics, scoped to the specified thread scope. Supports `store`, `load`, `exchange`, `compare_exchange_weak`, `compare_exchange_strong`, `fetch_add`, `fetch_sub`, `fetch_and`, `fetch_or`, `fetch_xor`. Each operation accepts a `cuda::memory_order` argument.
-- **Usable in**: Host and device code.
-- **Source**: Programming guide L3534-L3551, L23257-L23259
-
-### `cuda::atomic_ref<T, Scope>`
-
-- **Namespace**: `cuda`
-- **Header**: `<cuda/atomic>`
-- **Signature**: `template <class T, cuda::thread_scope Scope = cuda::thread_scope_system> class cuda::atomic_ref`
-- **Semantics**: A non-owning reference that provides atomic operations on an existing object of type `T`. Same operations and ordering semantics as `cuda::atomic`, but operates on externally managed storage. Useful for atomically accessing elements in existing arrays or `__shared__` variables without changing their type.
-- **Usable in**: Host and device code.
-- **Source**: Programming guide L1660-L1667, L28598-L28610
-
-## Thread Fences (libcu++)
-
-### `cuda::atomic_thread_fence`
-
-- **Namespace**: `cuda`
-- **Header**: `<cuda/atomic>`
-- **Signature**: `void cuda::atomic_thread_fence(cuda::memory_order order, cuda::thread_scope scope)`
-- **Semantics**: Establishes an ordering of memory accesses by the calling thread. The `order` parameter specifies the strength of the ordering (relaxed, acquire, release, acq_rel, seq_cst). The `scope` parameter specifies which threads observe the ordering effect. Equivalent to the legacy `__threadfence*` intrinsics when used with `memory_order_seq_cst`.
-- **Usable in**: Device code.
-- **Source**: Programming guide L23078-L23131
-
-## Legacy Fence Intrinsics
-
-### `__threadfence_block()`
-
-- **Namespace**: runtime (CUDA C++ intrinsic)
-- **Header**: `device_functions.h` (included via `cuda_runtime.h`)
-- **Signature**: `void __threadfence_block()`
-- **Semantics**: All writes by the calling thread before the call are observed by all threads in the same block as occurring before all writes after the call. All reads before the call are ordered before all reads after the call. Equivalent to `cuda::atomic_thread_fence(cuda::memory_order_seq_cst, cuda::thread_scope_block)`.
-- **Source**: Programming guide L23091-L23097
-
-### `__threadfence()`
-
-- **Namespace**: runtime
-- **Header**: `device_functions.h`
-- **Signature**: `void __threadfence()`
-- **Semantics**: No write by the calling thread after the call is observed by any thread in the device as occurring before any write before the call. Equivalent to `cuda::atomic_thread_fence(cuda::memory_order_seq_cst, cuda::thread_scope_device)`.
-- **Source**: Programming guide L23114-L23119
-
-### `__threadfence_system()`
-
-- **Namespace**: runtime
-- **Header**: `device_functions.h`
-- **Signature**: `void __threadfence_system()`
-- **Semantics**: All writes by the calling thread before the call are observed by all threads in the device, host threads, and peer device threads as occurring before all writes after the call. Equivalent to `cuda::atomic_thread_fence(cuda::memory_order_seq_cst, cuda::thread_scope_system)`.
-- **Source**: Programming guide L23136-L23141
-
-## Memory Orders
-
-### `cuda::memory_order_seq_cst`
-
-- **Value**: Sequentially consistent. Strongest ordering.
-- **Source**: Programming guide L23547 (`__NV_ATOMIC_SEQ_CST`)
-
-### `cuda::memory_order_acquire`
-
-- **Value**: Acquire ordering. Subsequent operations stay after.
-- **Source**: Programming guide L23547 (`__NV_ATOMIC_ACQUIRE`)
-
-### `cuda::memory_order_release`
-
-- **Value**: Release ordering. Prior operations stay before.
-- **Source**: Programming guide L23547 (`__NV_ATOMIC_RELEASE`)
-
-### `cuda::memory_order_relaxed`
-
-- **Value**: Relaxed ordering. Only atomicity guaranteed.
-- **Source**: Programming guide L23547 (`__NV_ATOMIC_RELAXED`)
-
-## Thread Scopes
-
-### `cuda::thread_scope_thread`
-
-- **PTX**: (none)
-- **Coherence point**: N/A (single thread)
-- **Source**: Programming guide L3486-L3489
-
-### `cuda::thread_scope_block`
-
-- **PTX**: `.cta`
-- **Coherence point**: L1
-- **Source**: Programming guide L3491-L3495
-
-### `cuda::thread_scope_cluster`
-
-- **PTX**: `.cluster`
-- **Coherence point**: L2
-- **Note**: Hopper+ (sm_90) only. Available at PTX level; exposed via built-in atomics as `__NV_THREAD_SCOPE_CLUSTER`.
-- **Source**: Programming guide L3497-L3499, L23564
-
-### `cuda::thread_scope_device`
-
-- **PTX**: `.gpu`
-- **Coherence point**: L2
-- **Source**: Programming guide L3501-L3505
-
-### `cuda::thread_scope_system`
-
-- **PTX**: `.sys`
-- **Coherence point**: L2 + connected caches
-- **Source**: Programming guide L3506-L3510