@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/atomic-reduction.md

@@ -1,256 +0,0 @@
----
-title: Atomic Reduction Contention Control
-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
-- histogram
-- scan
-- synchronization
-requires_sm: '>=7.0'
-requires_features:
-- scoped-atomics
-single_kernel_useful: true
-source:
-- path: spec
-  anchor: Reference
-artifacts:
-  code: artifacts/experience/hw-probes/atomic-reduction-contention/atomic_reduction_probe.cu
-  build: artifacts/experience/hw-probes/atomic-reduction-contention/build.sh
-  introspection: artifacts/experience/hw-probes/atomic-reduction-contention/device.json
-  profile: ''
-related_apis:
-- atomicAdd
-- atomicCAS
-- cuda::atomic
-- cuda::atomic_ref
-- __shfl_down_sync
-related_skills:
-- memory-ordering
-- warp-primitives
-- bank-conflict
-id: skill-atomic-reduction
-type: skill
-vendor: nvidia
-tags:
-- cuda-cpp
-- cluster
-- pipeline-stages
-- vectorized-loads
-- cache-policy
-- kernel-fusion
-- shared-memory-optimization
-- fused-kernel
-- quantization
-- ptx
-applies_to:
-- general
-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: L3435-L3436
-- source_id: cuda-official/toolkit-docs-13.2
-  path: CUDA Programming Guides/cuda-programming-guide/cuda_cuda-programming-guide_index.html.md
-  anchor: L3524-L3610
-- source_id: cuda-official/toolkit-docs-13.2
-  path: CUDA Programming Guides/cuda-programming-guide/cuda_cuda-programming-guide_index.html.md
-  anchor: L3641-L3645
-- source_id: cuda-official/toolkit-docs-13.2
-  path: CUDA Programming Guides/cuda-programming-guide/cuda_cuda-programming-guide_index.html.md
-  anchor: L23252-L23295
-- source_id: cuda-official/toolkit-docs-13.2
-  path: CUDA Programming Guides/parallel-thread-execution/cuda_parallel-thread-execution_index.html.md
-  anchor: L19647-L19680
-architectures:
-- sm90
-- sm90a
-languages:
-- ptx
-- cuda-cpp
-hardware_features:
-- cluster
-techniques:
-- pipeline-stages
-- vectorized-loads
-- cache-policy
-- kernel-fusion
-- shared-memory-optimization
-kernel_types:
-- fused-kernel
-- quantization
-confidence: experimental
-artifact_dir: artifacts/experience/hw-probes/atomic-reduction-contention
----
-## What
-
-An **atomic reduction** combines values from many threads into a single location using atomic read-modify-write operations (`atomicAdd`, `atomicCAS`, `cuda::atomic::fetch_add`, the PTX `atom` / `red` instructions, and their libcu++ equivalents). Every concurrent atomic against the same address is **serialized** by the hardware: the programming guide (L3435-L3436) states that "each read/modify/write to that location occurs and they are all serialized, but the order in which they occur is undefined."
-
-The cost model for atomic reductions therefore has three knobs the author must actively control:
-
-1. **Contention**: how many threads target the same address per unit time. N threads hitting one address means ~N serial transactions.
-2. **Scope** (`cta` / `cluster` / `gpu` / `sys`): which level of the memory hierarchy has to agree on the ordering. A narrower scope resolves at a closer cache level and is cheaper.
-3. **Memory ordering** (`relaxed` / `acquire` / `release` / `acq_rel` / `seq_cst`): what fence semantics surround the atomic. Weaker orderings emit fewer fence instructions.
-
-The three knobs combine into one rule of thumb from PG 3.2.4.1.2 (L3641-L3645): **narrowest scope, weakest ordering, resolved as close to the compute as possible**.
-
-## Why
-
-Atomic reductions are the default pattern whenever multiple threads must accumulate into a shared counter (sums, histograms, argmax, bounding-box reductions, free-list heads). When implemented naively -- every thread issuing one global atomicAdd to a single address -- they become the dominant cost of the kernel, because each atomic serializes at the L2 cache.
-
-The programming guide (L3435-L3436) is explicit that concurrent atomics from the same warp are serialized. On realistic reductions this serialization extends across all active warps and all active blocks, so a single-global-address reduction behaves like an O(threads) sequential chain.
-
-The per-scope latency difference is documented directly in PG 3.2.4.1.2 (L3641-L3645): block scope is "much faster" than system scope, shared-memory atomics are faster than global-memory atomics, weaker orderings skip memory fences. The techniques in this skill are all applications of those three statements.
-
-## When to use
-
-Apply these techniques whenever a kernel:
-
-- Uses `atomicAdd` / `atomicMin` / `atomicMax` / `atomicCAS` against a global-memory location touched by many threads.
-- Uses `cuda::atomic` with `thread_scope_device` or `thread_scope_system` where a narrower scope would suffice.
-- Builds a histogram, a counter, or a reduction whose final value lives in a single scalar (or a small fixed array like a 256-bucket histogram).
-- Uses a "first thread commits the block result" pattern with a single global atomic per block -- this is already the good pattern, but the block-local side of the reduction must also be efficient (shared-memory atomics or warp shuffles, not all-threads-to-one global atomic).
-
-### S1. Hierarchical reduction (warp -> block -> grid)
-
-Replace one global atomic per thread with **one global atomic per block**. Reduce inside a warp with `__shfl_down_sync` (zero memory traffic), reduce across warps through shared memory, then have a single thread of the block commit the block's partial sum:
-
-```cuda
-__global__ void hierarchicalSum(const float* input, float* output, int N) {
-    int tid = blockIdx.x * blockDim.x + threadIdx.x;
-    float val = (tid < N) ? input[tid] : 0.0f;
-
-    // Warp-level reduction via shuffle (no shared memory, no atomics)
-    for (int offset = 16; offset > 0; offset >>= 1)
-        val += __shfl_down_sync(0xFFFFFFFF, val, offset);
-
-    __shared__ float warpSums[32];          // at most 32 warps per block
-    int lane   = threadIdx.x & 31;
-    int warpId = threadIdx.x >> 5;
-    if (lane == 0) warpSums[warpId] = val;
-    __syncthreads();
-
-    // One warp reduces the per-warp partial sums
-    if (warpId == 0) {
-        int nWarps = (blockDim.x + 31) >> 5;
-        val = (lane < nWarps) ? warpSums[lane] : 0.0f;
-        for (int offset = 16; offset > 0; offset >>= 1)
-            val += __shfl_down_sync(0xFFFFFFFF, val, offset);
-        if (lane == 0)
-            atomicAdd(output, val);          // exactly one global atomic per block
-    }
-}
-```
-
-Traffic profile: `blockDim.x` threads per block, one `atomicAdd` per block. If the grid has `G` blocks, only `G` atomics contend for the destination address -- typically 10^2-10^4 instead of 10^6-10^8.
-
-### S2. Narrowest scope that is correct
-
-Choose the scope based on who must observe the atomic, not on "what feels safe":
-
-- `cuda::thread_scope_block` -- intra-block counters (partial sums in shared memory, per-block histograms).
-- `cuda::thread_scope_device` -- inter-block counters on the same GPU. This is what plain `atomicAdd` already uses.
-- `cuda::thread_scope_system` -- only required when a CPU thread or another GPU participates in the atomic sequence.
-
-```cuda
-#include <cuda/atomic>
-
-// Block scope: resolves within the SM's L1/shared-memory hierarchy
-__shared__ cuda::atomic<int, cuda::thread_scope_block> blockCounter;
-
-// Device scope: resolves at L2 (the default for atomicAdd())
-__device__ cuda::atomic<int, cuda::thread_scope_device> deviceCounter;
-```
-
-The programming guide (L3641-L3645) states that block-scoped atomics are "much faster" than system-scoped atomics; in a single-kernel H200 context system scope is almost never what you want.
-
-### S3. Weakest ordering that is correct
-
-If the only requirement is "this counter is incremented atomically," use `memory_order_relaxed`. The stronger orderings (`acquire` / `release` / `acq_rel` / `seq_cst`) emit fence instructions that pessimize surrounding memory traffic.
-
-```cuda
-// Pure counter: atomicity only, no ordering required
-counter.fetch_add(1, cuda::memory_order_relaxed);
-
-// Producer-consumer flag: release on producer side, acquire on consumer
-flag.store(true, cuda::memory_order_release);               // producer
-while (!flag.load(cuda::memory_order_acquire)) { /* wait */ }  // consumer
-```
-
-For a deeper treatment of memory ordering semantics (what each order actually guarantees), see the sibling `memory-ordering` skill; this skill is scoped to the contention/throughput side.
-
-### S4. Shared-memory atomics before global-memory atomics
-
-When the reduction's output set is small and fits in shared memory (the classic case is a 256-bin histogram), do the entire block-local aggregation with shared-memory atomics and commit only the final per-bin result to global memory:
-
-```cuda
-__global__ void histogram256(const uint8_t* data, int n, unsigned* hist) {
-    __shared__ unsigned sHist[256];
-    if (threadIdx.x < 256) sHist[threadIdx.x] = 0;
-    __syncthreads();
-
-    // Block-local histogram lives in shared memory (one 32-bit atomic per sample)
-    for (int i = blockIdx.x * blockDim.x + threadIdx.x;
-         i < n;
-         i += gridDim.x * blockDim.x) {
-        atomicAdd(&sHist[data[i]], 1u);
-    }
-    __syncthreads();
-
-    // Commit to global memory: 256 atomics per block regardless of n
-    if (threadIdx.x < 256)
-        atomicAdd(&hist[threadIdx.x], sHist[threadIdx.x]);
-}
-```
-
-PG 3.2.4.1.2 (L3641-L3645) states shared-memory atomics are faster than global-memory atomics; the kernel above exploits that by moving the per-sample atomic into shared memory and issuing only `256` global atomics per block instead of `n/blockDim.x`.
-
-## When NOT to use
-
-- **When the reduction is not actually atomic-bound.** If the kernel is memory-bandwidth-bound (load-heavy, atomics are <5% of issued instructions), optimizing the atomic path is invisible on wall-clock. Profile first: check whether `stall_long_scoreboard` or `stall_mio_throttle` on atomic instructions is actually material before rewriting.
-- **When the output is large and dense.** If every thread writes to a distinct address (e.g., elementwise `out[tid] = ...`), no atomic is needed; use a plain store. Atomic instructions on an uncontended address are still more expensive than a plain store.
-- **When correctness requires stronger ordering.** `relaxed` is not a default for producer-consumer flags, lock-free queues, or any pattern where one thread's write must be visible before another thread's read. See the `memory-ordering` skill.
-- **For device-wide reductions with a pre-existing tuned reduction path available.** Custom code is justified when the reduction must be fused with surrounding ops or the task requires kernel-side control over the final accumulation stage.
-
-## Measured Characteristics
-
-Measured on H200-SXM (sm_90a, CUDA 12.9, driver 570.124.06), summing `N = 33,554,432` floats (128 MB) to one scalar. Full record: sources/experience/hw-probes/atomic-reduction-contention.md.
-
-| Kernel             | Median ms | Eff. BW GB/s | DRAM SoL | Warp cyc/issue |
-| ------------------ | --------: | -----------: | -------: | -------------: |
-| `naive_atomic`     |   58.8769 |         2.28 |    0.05% |     **39,148** |
-| `hierarchical_s1`  |    0.2376 |       564.89 |   11.74% |           65.6 |
-| `grid_stride_s1`   | **0.0393**|  **3415.56** | **75.58%** |         67.4 |
-
-- **S1 hierarchical beats naive by 247.8x**; with a grid-stride loop on top of S1, the factor rises to **1498x** and the kernel becomes essentially HBM-bound (75.58% DRAM Speed-of-Light out of H200's ~4.8 TB/s peak).
-- The NCU signature of the atomic-contention pathology on `naive_atomic` is *Warp Cycles Per Issued Instruction ~ 39K* with DRAM SoL near 0, not a conventional memory-bound stall profile.
-- Legacy KernelPilot-sandbox runs for this skill (`KernelPilot/experience/2026-04-04-optimization-synchronization-atomic-reduction-*`) were performed on ~4 KB inputs and reported underutilized memory/compute SoL; they are retained as anecdotal only, **not** as measured evidence. The H200 probe above supersedes them for all `evidence_level: measured` claims in this skill.
-
-## Correctness finding: naive atomic reduction is also numerically wrong
-
-The H200 probe uncovered a second reason to avoid the naive single-global-atomic pattern beyond performance. Summing the same input with `naive_atomic` produced a result 5.03% below the double-precision reference (`rel_err = 5.029e-02`, correctness FAIL). The root cause is **FP32 accumulation loss** in the single global scalar: once the running sum grows past ~5x10^4, subsequent per-sample adds of magnitude ~10^-4 to ~10^-3 fall below the 24-bit mantissa's resolution and are quantized to zero.
-
-Hierarchical S1 cures this as a side effect: warp-lane partial sums stay in O(32) units, block partial sums stay in O(8,192) units, and only the final per-block partials (already in the thousands) land in the global scalar. Each accumulation stage therefore mixes values of comparable magnitude, preserving precision. In the same probe, `hierarchical_s1` returned rel_err 7.5e-05 and `grid_stride_s1` returned rel_err 1.4e-05.
-
-**Takeaway**: the naive pattern is not merely slow -- it is **incorrect** for any sum larger than ~10^5 FP32 samples. This is the strongest possible argument for S1 in pure-float accumulation contexts; for higher-precision accumulation see the `hardware-microbench.md` follow-up on FP32-in-FP64 reduction.
-
-## Principles
-
-1. **Minimize contention before minimizing per-op cost.** Dropping the per-block atomic count from 1024 to 1 is a larger win than switching `seq_cst` to `relaxed`.
-2. **Scope narrows the cache level; ordering narrows the fence.** Both are independent, and both contribute to the final cost.
-3. **Shared memory is a first-class reduction staging area.** S1 and S4 compose: block-local reduction in shared memory, then one global atomic per block.
-
-## Open questions
-
-- Q1. On H200, what is the measured per-atomic cost at scope `cta` / `gpu` / `sys` for a `fetch_add<int>` with relaxed ordering? (Feeds `sources/experience/hw-probes/atomic-reduction/scope-latency/`.)
-- Q2. Does `atom.add.v2.f32` (vectorized FP32 atomic, PTX ISA L19647-L19680) beat two scalar `atomicAdd` calls on H200, and at what alignment?
-- Q3. For FP16 gradient accumulation, does `atom.add.noftz.f16` (PTX ISA L19647-L19680) preserve enough precision vs. accumulating in FP32 on the block side and committing in FP16 at block commit?
-
-## Legacy references
-
-- `legacy_sandbox_path`: `KernelPilot/experience/2026-04-04-optimization-synchronization-atomic-reduction-skill{1,2,3,4}.md`. Treat as anecdotal only; environment (toolchain / driver / clock policy) was not recorded, and input sizes were too small to exercise the reduction path.

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

@@ -1,192 +0,0 @@
----
-title: Barrier Optimization APIs
-status: draft
-source:
-- path: spec
-  anchor: Reference
-apis:
-- func_name: __syncthreads
-  namespace: cuda-runtime
-  kind: block-barrier
-  signature: void __syncthreads();
-  notes: 'Block-level barrier; backed by PTX bar.sync. BP §12.1.3 throughput: 16 ops/clk on sm_7.x / sm_8.x. Per-call cost dominated by idle-until-slowest-thread stall.'
-- func_name: __syncthreads_count
-  namespace: cuda-runtime
-  kind: block-barrier-reduction
-  signature: int __syncthreads_count(int predicate);
-  notes: Block barrier + popcount of predicate across block. Useful for collective decisions without an extra reduction pass.
-- func_name: __syncthreads_and
-  namespace: cuda-runtime
-  kind: block-barrier-reduction
-  signature: int __syncthreads_and(int predicate);
-  notes: Block barrier + AND-reduce of predicate.
-- func_name: __syncthreads_or
-  namespace: cuda-runtime
-  kind: block-barrier-reduction
-  signature: int __syncthreads_or(int predicate);
-  notes: Block barrier + OR-reduce of predicate.
-- func_name: __syncwarp
-  namespace: cuda-runtime
-  kind: warp-barrier
-  signature: void __syncwarp(unsigned mask = 0xFFFFFFFFu);
-  notes: Warp-level barrier (or subset via mask). Cheapest barrier; required before warp-synchronous code on sm_70+ (ITS).
-- func_name: cuda::barrier
-  namespace: cuda
-  kind: async-barrier
-  signature: template<thread_scope S> class cuda::barrier;
-  notes: 'libcu++ async barrier with arrive/wait split. Scopes: block, cluster, device, system. Hardware-accelerated on sm_80+ for block/cluster scope.'
-- func_name: cuda::barrier::arrive
-  namespace: cuda
-  kind: async-barrier-method
-  signature: arrival_token arrive(ptrdiff_t update = 1);
-  notes: Signal arrival, return token for the current phase. Does not block.
-- func_name: cuda::barrier::wait
-  namespace: cuda
-  kind: async-barrier-method
-  signature: void wait(arrival_token&& token);
-  notes: Block until the phase identified by token completes. Token must be from current or immediately previous phase (pitfall P2).
-- func_name: cuda::barrier::init
-  namespace: cuda
-  kind: async-barrier-init
-  signature: friend void init(barrier*, ptrdiff_t expected);
-  notes: One-time initialization; must be called from exactly one thread and followed by block.sync() before any arrive.
-- func_name: cuda::device::barrier_native_handle
-  namespace: cuda::device
-  kind: async-barrier-ptx-bridge
-  signature: uint64_t* barrier_native_handle(cuda::barrier<S>& b);
-  notes: Get the underlying PTX mbarrier handle so you can call cuda::ptx::mbarrier_* directly. Used for expect_tx and TMA integration.
-- func_name: thread_block::sync
-  namespace: cooperative_groups
-  kind: cg-block-barrier
-  signature: void cg::thread_block::sync();
-  notes: Cooperative-groups block barrier; equivalent to __syncthreads at the SASS level.
-- func_name: thread_block_tile::sync
-  namespace: cooperative_groups
-  kind: cg-tile-barrier
-  signature: void cg::thread_block_tile<N>::sync();
-  notes: Sub-block barrier for a tile of N threads (N ∈ {1,2,4,8,16,32}). N=32 == __syncwarp.
-- func_name: bar.sync
-  namespace: ptx
-  kind: ptx-block-barrier
-  signature: bar.sync a{, b};
-  notes: PTX block barrier, 16 named barriers (a = 0..15). 'b' optional thread count for subset sync.
-- func_name: bar.arrive
-  namespace: ptx
-  kind: ptx-block-arrive
-  signature: bar.arrive a, b;
-  notes: Arrive on a named barrier without waiting. Pairs with later bar.sync.
-- func_name: barrier.cta.sync.aligned
-  namespace: ptx
-  kind: ptx-block-barrier-aligned
-  notes: Aligned form; compiler uses when it can prove all warps participate fully. Has higher throughput than the non-aligned bar.sync.
-- func_name: mbarrier.init
-  namespace: ptx
-  kind: ptx-mbarrier
-  signature: mbarrier.init.shared::cta.b64 [mbar], expected_count;
-  notes: Initialize a 64-bit mbarrier object in shared memory.
-- func_name: mbarrier.arrive
-  namespace: ptx
-  kind: ptx-mbarrier
-  signature: mbarrier.arrive.shared::cta.b64 token, [mbar] {, increment};
-  notes: Signal arrival; returns a token identifying the current phase.
-- func_name: mbarrier.arrive.expect_tx
-  namespace: ptx
-  kind: ptx-mbarrier-expect-tx
-  signature: mbarrier.arrive.expect_tx.shared::cta.b64 token, [mbar], tx_count;
-  notes: Arrive AND declare that `tx_count` bytes of async transactions will complete on this barrier. Enables hw-tracked TMA/cp.async synchronization.
-- func_name: mbarrier.try_wait
-  namespace: ptx
-  kind: ptx-mbarrier
-  signature: mbarrier.try_wait.shared::cta.b64 pred, [mbar], token, suspendTimeHint;
-  notes: Blocking wait on the phase identified by token; returns 1 when phase completes.
-- func_name: mbarrier.test_wait
-  namespace: ptx
-  kind: ptx-mbarrier
-  signature: mbarrier.test_wait.shared::cta.b64 pred, [mbar], token;
-  notes: Non-blocking check; returns 1 if phase already complete, else 0. Useful for interleaving.
-- func_name: cp.async.mbarrier.arrive
-  namespace: ptx
-  kind: ptx-async-copy-mbarrier-bridge
-  notes: Issued from a cp.async instruction target; increments the mbarrier transaction count when the async copy retires.
-- func_name: barrier.cluster.arrive
-  namespace: ptx
-  kind: ptx-cluster-barrier
-  notes: Cluster-scope barrier arrival (sm_90+). For DSMEM / multi-block kernels. See wiki/nvidia/hardware/thread-block-cluster/ (pending).
-- func_name: barrier.cluster.wait
-  namespace: ptx
-  kind: ptx-cluster-barrier
-  notes: Cluster-scope barrier wait (sm_90+).
-- func_name: __nanosleep
-  namespace: cuda-runtime
-  kind: spin-wait-backoff
-  signature: void __nanosleep(unsigned int ns);
-  notes: Suspend the thread for ~ns nanoseconds. Used in spin-wait loops to reduce SM resource pressure. Legacy pitfall P8 documents the no-contention case where this adds minor overhead without benefit.
-id: api-barrier-optimization-ref
-type: api-definition
-vendor: nvidia
-func_name: Barrier Optimization APIs
-namespace: runtime
-header: cuda_runtime.h
-signature: See documentation
-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: 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-L19482
-- source_id: cuda-official/toolkit-docs-13.2
-  path: CUDA Programming Guides/parallel-thread-execution/cuda_parallel-thread-execution_index.html.md
-  anchor: L20580-L21555
-languages:
-- ptx
-- cuda-cpp
-hardware_features:
-- tma
-- mbarrier
-- cluster
-techniques:
-- shared-memory-optimization
-confidence: inferred
-evidence_level: inferred
-tags:
-- tma
-- mbarrier
-- cluster
-- shared-memory-optimization
-- ptx
-- cuda-cpp
-architectures:
-- sm90
-- sm90a
----
-## Core APIs
-
-| API / Instruction | Layer | Purpose |
-|-------------------|-------|---------|
-| `__syncthreads()` | Runtime | Block-level barrier (bar.sync backing) |
-| `__syncwarp(mask)` | Runtime | Warp-level barrier (cheapest) |
-| `cuda::barrier<thread_scope>` | libcu++ | Async barrier with arrive/wait split |
-| `cuda::barrier::arrive()` / `.wait(token)` | libcu++ | Arrival and wait separated |
-| `cg::thread_block_tile<N>::sync()` | coop-groups | Sub-block barrier (N threads) |
-| `__syncthreads_count/and/or(pred)` | Runtime | Block barrier + collective reduction |
-
-## PTX-level
-
-| Instruction | Purpose |
-|-------------|---------|
-| `bar.sync a{, b}` / `barrier.cta.sync.aligned` | CTA barrier, 16 named slots |
-| `bar.arrive a, b` | Non-blocking arrive on named barrier |
-| `mbarrier.init` | Initialize shared-memory mbarrier |
-| `mbarrier.arrive` / `.arrive.expect_tx` | Signal arrival / with tx-count tracking |
-| `mbarrier.try_wait` / `.test_wait` | Blocking / non-blocking phase-complete check |
-| `cp.async.mbarrier.arrive` | Async-copy-retire bridge to mbarrier |
-| `barrier.cluster.arrive` / `.wait` | Cluster-scope barrier (sm_90+) |
-
-## Cross-references
-
-- **`memory-ordering` skill**: the fence/visibility side of sync — what writes are guaranteed visible after the barrier.
-- **`warp-primitives` skill**: warp shuffles are `_sync` variants with an embedded barrier; usually removes the need for explicit `__syncwarp`.
-- **`async-copy` skill**: `cp.async` / TMA + `mbarrier.arrive.expect_tx` is the canonical producer-consumer shape on sm_80+.
-- **`warp-divergence` skill** (pitfall P1): re-converge divergent warps with `__syncwarp` before `mbarrier.arrive` to avoid per-lane arrivals.
-- **`wiki/nvidia/hardware/thread-block-cluster/`** (pending bucket F): cluster-scope barriers belong there.

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

@@ -1,163 +0,0 @@
----
-title: Barrier Optimization — Pitfalls
-status: draft
-id: pitfall-barrier-optimization
-type: pitfall
-vendor: nvidia
-architectures:
-- sm90
-- sm90a
-languages:
-- ptx
-- cuda-cpp
-hardware_features:
-- mbarrier
-techniques:
-- vectorized-loads
-- shared-memory-optimization
-- communication-overlap
-kernel_types:
-- quantization
-confidence: inferred
-evidence_level: inferred
-tags:
-- mbarrier
-- vectorized-loads
-- shared-memory-optimization
-- communication-overlap
-- quantization
-- ptx
-- cuda-cpp
----
-# Barrier Optimization — Pitfalls
-
-## P1. Divergent warp causes per-lane mbarrier arrivals
-
-**Symptom**: An `mbarrier.arrive` or `cuda::barrier::arrive` completes the barrier too early. The barrier's arrival count is reached before all *logical* participants have produced their output, producing race conditions in the consumer phase.
-
-**Root cause**: When a warp reaches `mbarrier.arrive` while diverged (some lanes active, others masked off), each active lane issues its own arrival. If the warp was expected to contribute `arrival_count = blockDim / 32` but the warp is split into e.g. 16 active + 16 masked lanes, only 16 arrivals happen from that warp — *or*, worse, if later the masked lanes continue and also arrive, you get double-counting. ITS on sm_70+ makes this non-deterministic across runs.
-
-**Fix**: Always `__syncwarp(0xFFFFFFFFu)` to re-converge the warp before `mbarrier.arrive`. PG §4.9.2.1: "If the invoking warp is fully diverged, then 32 individual updates are applied to the barrier." The warp-divergence skill's pitfall P1 also covers this under the correctness-on-Volta+ lens.
-
-```cuda
-// WRONG: diverged warp arrives multiple times
-if (lane_local_ready) {
-    auto token = bar.arrive();     // only active lanes count
-    bar.wait(std::move(token));
-}
-
-// RIGHT: all 32 lanes arrive together
-__syncwarp(0xFFFFFFFFu);            // re-converge
-auto token = bar.arrive();          // always 1 arrival per thread
-// ... later ...
-bar.wait(std::move(token));
-```
-
-**Source**: CUDA C++ Programming Guide §4.9.2.1.
-
-## P2. Using an arrive token from the wrong phase
-
-**Symptom**: `bar.wait(std::move(token))` either hangs (future phase) or returns immediately (stale past phase), producing silent correctness bugs.
-
-**Root cause**: The token returned by `bar.arrive()` is specific to the barrier's current phase. If the barrier advances phases between arrive and wait (because other threads have completed the phase), the token becomes invalid.
-
-**Fix**: Keep arrive and wait in the same lexical scope and same phase. Never save a token across `bar.wait`. Per PG §4.9.2: "bar.wait() must only be called using a token object of the current phase or the immediately preceding phase." The "immediately preceding" part is the only legal cross-phase case.
-
-**Source**: CUDA C++ Programming Guide §4.9.2.
-
-## P3. `__syncthreads()` inside a divergent branch deadlocks the kernel
-
-**Symptom**: Kernel hangs indefinitely. `nvidia-smi` shows the GPU busy with no progress. Timeouts.
-
-**Root cause**: `__syncthreads` is a *collective* barrier — every thread in the block must execute it. If some threads skip the call because they took a different branch, the remaining threads wait forever.
-
-**Fix**: Move `__syncthreads` outside the branch so every thread reaches it.
-
-```cuda
-// WRONG: threads with tid >= 128 never reach the barrier
-if (threadIdx.x < 128) {
-    smem[tid] = compute(tid);
-    __syncthreads();            // DEADLOCK — only half the block is here
-}
-
-// RIGHT: all threads reach the barrier; predicate only the work
-if (threadIdx.x < 128) {
-    smem[tid] = compute(tid);
-}
-__syncthreads();                // all threads reach this point
-```
-
-**Source**: CUDA C++ Programming Guide §5.4.4.1.
-
-## P4. Excessive `__syncthreads` calls dominate SM throughput
-
-**Symptom**: NCU shows `smsp__warps_issue_stalled_barrier_per_issue_active.pct` above 20 %. Instruction throughput is low; kernel is mostly idle at barriers.
-
-**Root cause**: Each `__syncthreads` stalls the SM until the slowest warp arrives. A kernel with many small phases separated by `__syncthreads` pays this "wait for slowest" cost once per phase. The problem compounds when occupancy is low (one block per SM) — there are no other warps to cover the idle.
-
-**Fix (in order)**:
-1. Merge adjacent barrier-separated phases when correctness allows.
-2. Increase blocks-per-SM (smaller blocks or smaller smem footprint) so warps from other blocks run during a barrier wait.
-3. Split the reduction into warp-local + one block-level merge (atomic-reduction S1 pattern).
-4. For producer-consumer shapes, convert to async-barrier (S2 in this skill) so the consumer warp does real work between arrive and wait.
-
-**Source**: Best Practices Guide §12.1.3 (L1402-L1404).
-
-## P5. Forgetting to initialize `mbarrier` before first use
-
-**Symptom**: Sporadic deadlocks, or barrier completes immediately on first phase with no threads having arrived. Non-reproducible bugs that only appear on some inputs or with some block sizes.
-
-**Root cause**: `mbarrier`'s 64-bit state is memory-backed. Without `mbarrier.init`, the state is garbage and the first `arrive`/`wait` works against whatever values happen to be in that shared memory slot.
-
-**Fix**: Always initialize from a single thread and `__syncthreads` before first use:
-
-```cuda
-__shared__ cuda::barrier<cuda::thread_scope_block> bar;
-if (threadIdx.x == 0) init(&bar, blockDim.x);
-__syncthreads();                  // all threads see initialized bar
-// ... now safe to call bar.arrive() / bar.wait() ...
-```
-
-**Source**: CUDA C++ Programming Guide §4.9.1.
-
-## P6. `cuda::barrier` arrive+wait is slower than `__syncthreads` in bare cost (measured on H200)
-
-**Symptom**: Replacing `__syncthreads` with `cuda::barrier` + arrive/wait split *increases* per-barrier wall-clock on kernels that don't have independent work to overlap.
-
-**Root cause**: `cuda::barrier<thread_scope_block>` lives in shared memory as a 64-bit mbarrier object. Each `arrive` + `wait` pair emits multiple PTX instructions (`mbarrier.arrive.shared::cta.b64` returning a token, then `mbarrier.try_wait.shared::cta.b64` that blocks on the token), plus a read-modify-write to the shared-memory phase state. `__syncthreads` uses the SM's dedicated named-barrier hardware (16 slots per SM) without touching smem. The overlap benefit only materializes when there is real independent work to run between arrive and wait (~100+ cycles of compute).
-
-**Fix**: Reach for `cuda::barrier` only when (a) the kernel has independent producer/consumer work that can overlap across arrive/wait, OR (b) you need `expect_tx` for async-copy tracking. For simple fence-between-phases, `__syncthreads` is still the right tool.
-
-**Measured on H200 sm_90a** (`sources/experience/hw-probes/barrier-cost.md`): bare arrive+wait cost per call is 1.59× (at B=128) to **2.23× (at B=1024) slower** than `__syncthreads`. Scaling factor across 128→1024 is 2.72× for mbarrier vs 1.93× for `__syncthreads` — the mbarrier gap widens with block size, so the "no overlap" loss is worst at exactly the block sizes where barrier cost matters most.
-
-**Source**: H200 probe (measured, 2026-04-22), supersedes KernelPilot legacy L3 sandbox (2026-04-04) which was directionally correct but un-quantified.
-
-## P7. Removing barriers shifts the bottleneck to memory latency (legacy-measured)
-
-**Symptom**: After removing `__syncthreads` stalls, `smsp__warps_issue_stalled_long_scoreboard_per_issue_active.pct` rises from 24.8 % to 30.5 %. The NCU "barrier stall" metric went down but a new stall metric went up.
-
-**Root cause**: The barrier stall was *hiding* the memory-latency stall. Once the barrier no longer serializes warps, the warps discover the memory wait that had been happening in parallel with the barrier. The total wall-clock is still better, but the NCU stall profile looks different.
-
-**Fix**: Read wall-clock, not just the stall %. If wall-clock improved, the optimization worked — the "rising long_scoreboard" is just the next bottleneck showing itself. Follow with memory-side optimizations (coalescing, vectorized access, async-copy).
-
-**Source**: KernelPilot legacy L3 sandbox (2026-04-04). Consistent with the "metric shape shift" observation from the warp-divergence skill pitfall P7.
-
-## P8. `__nanosleep` requires actual spin-wait contention to be useful
-
-**Symptom**: Adding `__nanosleep(N)` into a spin-wait loop shows no wall-clock improvement — sometimes a small regression (`short_scoreboard` stall rose from 5.21 % to 6.17 %).
-
-**Root cause**: `__nanosleep` is a thread-throttle that reduces SM resource pressure **when the spin is actually contending for a lock or flag**. In a synthetic microbench with no real contention, the nanosleep instruction itself adds latency without saving anything.
-
-**Fix**: Only apply `__nanosleep` in spin loops that have real contention (lock-based producer-consumer, CAS-based free lists, spinlock-guarded data structures). For plain phase-waiting, `mbarrier.try_wait` with its implicit hardware throttling is the right answer.
-
-**Source**: KernelPilot legacy L3 sandbox (2026-04-04).
-
-## P9. `smsp__warps_issue_stalled_barrier` metric drops after a bottleneck shift
-
-**Symptom**: Combined "stall barrier + stall scoreboard" rose from 36.25 % to 49.37 % after a barrier optimization — looks like a regression.
-
-**Root cause**: Same as P7 — the optimization shifted the stall shape, not the underlying bottleneck intensity. Individual stall categories add up to total idle time; making one go down can make another appear to "rise" simply because the total is redistributed.
-
-**Fix**: Use wall-clock as the final judge. Only use NCU stall percentages to identify **which category to address next**, never to grade the success of an already-applied optimization.
-
-**Source**: KernelPilot legacy L3 sandbox (2026-04-04).