@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/memory/shared-memory-cache/apis.md

@@ -1,136 +0,0 @@
----
-title: Shared Memory Cache APIs
-status: draft
-source:
-- path: spec
-  anchor: Reference
-apis:
-- func_name: __shared__
-  namespace: cuda-language
-  kind: storage-class
-  signature: __shared__ T arr[N];
-  notes: Static (compile-time-known size) shared-memory declaration. Lives for block lifetime.
-- func_name: extern __shared__
-  namespace: cuda-language
-  kind: storage-class
-  signature: extern __shared__ T smem[];
-  notes: Dynamic shared-memory declaration; size passed as 3rd launch parameter.
-- func_name: __syncthreads
-  namespace: cuda-runtime
-  kind: barrier
-  signature: void __syncthreads();
-  notes: Block-level barrier; required after smem writes and before cross-warp smem reads.
-- func_name: __syncwarp
-  namespace: cuda-runtime
-  kind: barrier
-  signature: void __syncwarp(unsigned mask = 0xFFFFFFFF);
-  notes: Warp-level barrier; sufficient for intra-warp smem sharing.
-- func_name: cudaFuncSetAttribute
-  namespace: cuda-runtime
-  kind: host-config
-  signature: cudaError_t cudaFuncSetAttribute(const void* func, cudaFuncAttribute attr, int value);
-  notes: Sets per-kernel attributes including MaxDynamicSharedMemorySize and PreferredSharedMemoryCarveout.
-- func_name: cudaFuncAttributeMaxDynamicSharedMemorySize
-  namespace: cuda-runtime
-  kind: attr-enum
-  notes: Required opt-in for dynamic smem >48 KB per block.
-- func_name: cudaFuncAttributePreferredSharedMemoryCarveout
-  namespace: cuda-runtime
-  kind: attr-enum
-  notes: Integer percentage (0..100) or cudaSharedmemCarveoutMaxShared / MaxL1 / Default.
-- func_name: cudaFuncSetCacheConfig
-  namespace: cuda-runtime
-  kind: host-config
-  signature: cudaError_t cudaFuncSetCacheConfig(const void* func, cudaFuncCache cacheConfig);
-  notes: Legacy API; prefer cudaFuncSetAttribute because it does not force serialization between differently-configured launches (PG §3.2.6 note).
-- func_name: cudaOccupancyAvailableDynamicSMemPerBlock
-  namespace: cuda-runtime
-  kind: host-occupancy
-  signature: cudaError_t cudaOccupancyAvailableDynamicSMemPerBlock(size_t* dynSmemSize, const void* func, int numBlocks, int blockSize);
-  notes: Query max dynamic smem allowed if launching numBlocks per SM at blockSize.
-- func_name: cudaDeviceGetAttribute
-  namespace: cuda-runtime
-  kind: host-query
-  signature: cudaError_t cudaDeviceGetAttribute(int* value, cudaDeviceAttr attr, int device);
-  notes: Query cudaDevAttrMaxSharedMemoryPerBlockOptin for the architecture's hard ceiling.
-- func_name: ld.shared.{vec}.{type}
-  namespace: ptx
-  kind: ptx-load
-  notes: Shared-memory load. Generated automatically from C++ smem reads; inspect via -Xptxas=-v or SASS.
-- func_name: st.shared.{vec}.{type}
-  namespace: ptx
-  kind: ptx-store
-  notes: Shared-memory store.
-- func_name: cp.async.ca.shared.global
-  namespace: ptx
-  kind: ptx-async-copy
-  notes: Async global->shared copy (sm_80+). See the async-copy skill for orchestration.
-id: api-shared-memory-cache-ref
-type: api-definition
-vendor: nvidia
-func_name: Shared Memory Cache 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: L1130-L1170
-- source_id: cuda-official/toolkit-docs-13.2
-  path: CUDA Programming Guides/cuda-programming-guide/cuda_cuda-programming-guide_index.html.md
-  anchor: L4094-L4130
-- 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: L728-L732
-languages:
-- ptx
-- cuda-cpp
-hardware_features:
-- tma
-- cluster
-techniques:
-- cache-policy
-- shared-memory-optimization
-confidence: inferred
-evidence_level: inferred
-tags:
-- tma
-- cluster
-- cache-policy
-- shared-memory-optimization
-- ptx
-- cuda-cpp
-architectures:
-- sm90
-- sm90a
----
-## Core APIs
-
-| API / Instruction | Layer | Purpose |
-|-------------------|-------|---------|
-| `__shared__ T arr[N]` | C++/CUDA | Static shared-memory declaration |
-| `extern __shared__ T smem[]` | C++/CUDA | Dynamic shared-memory declaration |
-| `__syncthreads()` | Runtime | Block-scope barrier (required before cross-warp smem reads) |
-| `__syncwarp(mask)` | Runtime | Warp-scope barrier (sufficient intra-warp) |
-| `cudaFuncSetAttribute(func, attr, value)` | Host | Per-kernel attribute setter |
-| `cudaFuncAttributeMaxDynamicSharedMemorySize` | Enum | >48 KB dynamic-smem opt-in |
-| `cudaFuncAttributePreferredSharedMemoryCarveout` | Enum | L1/smem split per kernel |
-| `cudaSharedmemCarveoutMaxShared` / `MaxL1` / `Default` | Enum | Carveout convenience values |
-| `cudaOccupancyAvailableDynamicSMemPerBlock` | Host | Budget solver for dynamic smem vs blocks-per-SM |
-| `cudaDeviceGetAttribute(..., cudaDevAttrMaxSharedMemoryPerBlockOptin, ...)` | Host | Architecture hard ceiling for opt-in smem |
-
-## PTX-level
-
-| Instruction | Purpose |
-|-------------|---------|
-| `ld.shared[.vec][.type]` | Shared-memory load |
-| `st.shared[.vec][.type]` | Shared-memory store |
-| `cp.async.ca.shared.global[.vec]` | Async global->shared (sm_80+); overlaps with compute |
-| `cp.async.bulk` | TMA bulk async copy (sm_90+); see `wiki/nvidia/hardware/tma/` |
-
-## Cross-references
-
-- **Bank conflicts**: `wiki/nvidia/foundations/memory/bank-conflict/` — covers the `[TILE][TILE+1]` padding rule and 4 B vs 8 B stride rules that make the staged smem access itself fast.
-- **Coalescing**: `wiki/nvidia/foundations/memory/coalescing/` — the prerequisite for the global-to-smem load to be efficient.
-- **Async copy**: `wiki/nvidia/foundations/memory/async-copy/` — covers `cp.async` / `cuda::memcpy_async` that replace a blocking `load + __syncthreads` pair.
-- **Distributed shared memory (>one block)**: `wiki/nvidia/hardware/thread-block-cluster/` (pending bucket F bootstrap) — covers `cluster.map_shared_rank` and `ld.shared::cluster`.

package/resources/kop-2026-10-23-0.1.17-beta.1/product_capabilities/kernel_optflow/skills/KernelWiki-private/wiki/nvidia/foundations/memory/shared-memory-cache/pitfalls.md

@@ -1,162 +0,0 @@
----
-title: Shared Memory Cache — Pitfalls
-status: draft
-id: pitfall-shared-memory-cache
-type: pitfall
-vendor: nvidia
-architectures:
-- sm90
-- sm90a
-languages:
-- ptx
-- cuda-cpp
-techniques:
-- pipeline-stages
-- cache-policy
-- data-reuse
-- shared-memory-optimization
-- tile-scheduling
-confidence: inferred
-evidence_level: inferred
-tags:
-- pipeline-stages
-- cache-policy
-- data-reuse
-- shared-memory-optimization
-- tile-scheduling
-- ptx
-- cuda-cpp
----
-# Shared Memory Cache — Pitfalls
-
-## P1. Missing `__syncthreads()` between smem write and cross-warp read
-
-**Symptom**: Intermittently incorrect results. `compute-sanitizer --tool racecheck` reports a hazard.
-
-**Root cause**: One warp writes into smem, another warp reads from that smem location without a block-level barrier. Warp schedulers run warps in arbitrary order; the reader may observe stale data.
-
-**Fix**: Place `__syncthreads()` after the write phase and before the read phase. Use `__syncwarp(mask)` only when the producer and consumer lanes are in the same warp (same-warp intra-tile shuffles).
-
-**Source**: Best Practices Guide §10.2.3.2 (L728-L732); CUDA C++ Programming Guide §2.2.3.2 (L1130-L1170).
-
-## P2. Excessive smem footprint collapses occupancy
-
-**Symptom**: Nsight Compute occupancy section shows shared memory as the limiting resource; only 1 block/SM reached; kernel is latency-bound rather than bandwidth-bound.
-
-**Root cause**: The chosen tile size claims more smem per block than the architecture's budget allows at the desired blocks-per-SM count. The unified L1/smem cache has a hard per-SM cap (228 KB on H100/H200 for opt-in).
-
-**Fix**: Shrink the tile, split into multiple passes, or process multiple output elements per thread with a smaller tile. Verify with `cudaOccupancyAvailableDynamicSMemPerBlock`. Profile with `-Xptxas=-v` and the NCU "Launch Statistics" section before and after.
-
-**Source**: Best Practices Guide §11.4 (L1132-L1150) — "Effects of Shared Memory".
-
-## P3. Dynamic smem alignment errors when partitioning one buffer into multiple arrays
-
-**Symptom**: Wrong results or CUDA illegal-memory-access when a dynamic-smem buffer is sliced into e.g. a `short` prefix and a `float` suffix.
-
-**Root cause**: The second pointer is computed as `(float*)&s_short[short_count]`. If `short_count` is odd, the pointer is not 4-byte aligned, and PTX `ld.shared.f32` will trap or silently load wrong data.
-
-**Fix**: Round partitions up to each type's alignment manually. Cast through `char*` to reason about bytes rather than elements:
-
-```cuda
-extern __shared__ char smem_raw[];
-short* s_short  = (short*)smem_raw;
-float* s_float  = (float*)(smem_raw + ROUND_UP(short_count * sizeof(short), 16));
-```
-
-**Source**: CUDA C++ Programming Guide §2.2.3.2.2 (dynamic smem allocation, L1173+).
-
-## P4. Forgetting the >48 KB opt-in for dynamic smem
-
-**Symptom**: `cudaLaunchKernel` returns `cudaErrorLaunchOutOfResources`; the same configuration worked at 48 KB but fails at 64 KB.
-
-**Root cause**: Per PG §3.2.6 (L4094-L4130), allocations above 48 KB per block require an explicit opt-in via `cudaFuncSetAttribute(kernel, cudaFuncAttributeMaxDynamicSharedMemorySize, bytes)`. The default cap is 48 KB for launch-safety across older architectures.
-
-**Fix**: Call `cudaFuncSetAttribute(kernel, cudaFuncAttributeMaxDynamicSharedMemorySize, max_bytes)` once after module load, before the first launch. Query the per-architecture ceiling with `cudaDeviceGetAttribute(&maxopt, cudaDevAttrMaxSharedMemoryPerBlockOptin, device)`.
-
-**Source**: CUDA C++ Programming Guide §3.2.6 (L4094-L4130), §18194.
-
-## P5. Staging smem for single-use data
-
-**Symptom**: Kernel latency rises after "optimizing" it by adding a smem tile. NCU shows no reduction in DRAM bytes; `smsp__warps_issue_stalled_barrier_per_issue_active.pct` rises.
-
-**Root cause**: Each element is loaded to smem and read exactly once, with no reuse, no reorder, and no cross-warp share. The `__syncthreads()` and smem round-trip are pure overhead; hardware L1 would have cached the load for free.
-
-**Fix**: Remove the smem stage. Load directly from global into a register; let L1 absorb the single-shot read. Reserve smem for the three justifying roles (reuse / reorder / cross-warp comm).
-
-**Source**: Best Practices Guide §10.2.3 (L719-L727) — "Effects of Shared Memory".
-
-## P6. Unconditional smem writes when only a subset of threads have real data
-
-**Symptom**: Silent correctness bugs if the "unused" slots contain garbage read by the reduction tail; wasted bandwidth in any case; potential bank conflicts if the unused writes alias banks.
-
-**Root cause**: Block-level load code writes `smem[tid] = in[blockIdx.x * blockDim.x + tid]` without guarding against `tid >= valid_count`.
-
-**Fix**: Guard the write with the validity predicate and pre-zero the unused region before the barrier:
-
-```cuda
-smem[tid] = (tid < valid_count) ? in[...] : 0.0f;   // zero-extend, not UB
-__syncthreads();
-```
-
-Or use `cuda::memcpy_async` with a size argument to do the tail-guarded load cooperatively.
-
-**Source**: CUDA C++ Programming Guide §4.11.1.1 (batching loads in conditional code).
-
-## P7. Occupancy crash from tripled smem in a reuse-thin kernel (legacy sandbox finding)
-
-**Symptom**: Smem footprint rose from 1 KB to 3 KB per block; the smem-limited block count fell from 32 to 21 blocks/SM; `smsp__warps_issue_stalled_barrier_per_issue_active.pct` rose from 0 % to 14 %.
-
-**Root cause**: The kernel's reuse factor was too low to amortize the additional `__syncthreads()` and the occupancy loss.
-
-**Fix**: Confirm a reuse factor ≥ 4× (each smem word read ≥ 4 times) before accepting the footprint increase. If reuse < 4×, either stay in registers or reduce tile size.
-
-**Source**: KernelPilot legacy L3 sandbox run (2026-04-05). Retained here as anecdotal; to be re-measured on H200 in a follow-up probe.
-
-## P8. Unpadded `[TILE][TILE]` smem causes 32-way bank conflicts on column access (measured on H200)
-
-**Symptom**: NCU `l1tex__data_bank_conflicts_pipe_lsu_mem_shared_op_ld.sum` spikes; `short_scoreboard` stalls rise to 30 %+ when column-indexing the smem tile.
-
-**Root cause**: 32 successive 32-bit words of a row map to 32 distinct banks, but 32 successive row-strided accesses (`smem[0..31][threadIdx.x]`) all land on the same bank.
-
-**Fix**: Declare the tile as `__shared__ float smem[TILE][TILE + 1];`. The extra column shifts each row by one bank, making column reads conflict-free. This is the default idiom for any 2-D smem tile intended to be read along both axes.
-
-**Measured on H200** (4096² fp32 transpose, sm_90a, CUDA 12.9, probe `sources/experience/hw-probes/smem-tile-reuse/`):
-
-| Kernel                         | Bank conflicts (ld.sum) | Warp cyc/issued | Median ms |
-|--------------------------------|------------------------:|----------------:|----------:|
-| `smem_tiled` (unpadded 32×32)  |              16,326,828 |           85.54 |    0.1363 |
-| `smem_tiled` (padded 32×33)    |                  33,449 |           42.09 |    0.0796 |
-
-Padding cuts bank-conflict count **488.4×** and delivers another **1.71×** speedup on top of the smem staging itself.
-
-**Source**: Best Practices Guide §10.2.3.1 (L722-L727); H200 probe `2026-04-21-smem-tile-reuse.md` (measured, supersedes earlier KernelPilot L3 sandbox anecdote).
-
-## P9. Dynamic smem is not free for compile-time-known tile sizes
-
-**Symptom**: Replacing `__shared__ float smem[128];` with `extern __shared__ float smem[];` added ~5 % kernel time in a small-tile kernel.
-
-**Root cause**: The compiler can constant-propagate static smem addresses through subsequent `ld.shared` / `st.shared` instructions, whereas dynamic smem forces address computation via base + offset. For small compile-time-known tiles the optimizer gap becomes measurable.
-
-**Fix**: Prefer static `__shared__` whenever the tile size is known at compile time. Only reach for `extern __shared__` when the size must be launch-time-selected, or when you intend to partition a single buffer into multiple typed arrays.
-
-**Source**: KernelPilot legacy L3 sandbox run (2026-04-05). Retained as anecdotal; warrants re-measurement on H200 once sm_90a compiler revs have settled.
-
-## P10. Carveout success without occupancy gain (register-limited kernel)
-
-**Symptom**: `cudaFuncSetAttribute(..., cudaFuncAttributePreferredSharedMemoryCarveout, MaxShared)` did change `launch__occupancy_limit_shared_mem` (e.g. from 3 to 25) but achieved occupancy did not budge because the kernel was register-limited (limit = 2).
-
-**Root cause**: Occupancy is the minimum of the per-resource limits. Lifting the smem ceiling is invisible unless smem was the binding constraint.
-
-**Fix**: Before tuning carveout, identify the binding resource. NCU "Occupancy" section lists `launch__occupancy_limit_{registers, shared_mem, blocks}`; carveout only helps when `shared_mem` is the tightest. Use `__launch_bounds__` or `-maxrregcount` to address a register-limited case instead.
-
-**Source**: KernelPilot legacy L3 sandbox run (2026-04-05). Same re-measurement caveat as above.
-
-## P11. Over-allocating dynamic smem zeros out L1 hit rate
-
-**Symptom**: L1 hit rate drops to near zero; DRAM read traffic rises; smem is only partially used.
-
-**Root cause**: Large dynamic smem claims (close to the 228 KB opt-in ceiling on H100/H200) leave no room for L1 in the unified data cache. If only part of the claim is actually written, the kernel pays the L1 cost for no benefit.
-
-**Fix**: Claim only what you will use. `cudaFuncAttributePreferredSharedMemoryCarveout` should reflect the *actually written* smem footprint, not the dynamic-smem *ceiling*.
-
-**Source**: KernelPilot legacy L3 sandbox run (2026-04-05). Same re-measurement caveat.

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

@@ -1,295 +0,0 @@
----
-title: Shared Memory as User-Managed Cache
-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
-- pooling
-- scan
-- transpose
-- elementwise
-requires_sm: '>=7.0'
-requires_features:
-- static-shared-memory
-- dynamic-shared-memory
-- smem-l1-carveout
-single_kernel_useful: true
-source:
-- path: spec
-  anchor: Reference
-artifacts:
-  code: artifacts/experience/hw-probes/smem-tile-reuse/smem_tile_reuse_probe.cu
-  build: artifacts/experience/hw-probes/smem-tile-reuse/build.sh
-  introspection: artifacts/experience/hw-probes/smem-tile-reuse/device.json
-  profile: ''
-related_apis:
-- __syncthreads
-- cudaFuncSetAttribute
-- cudaFuncAttributeMaxDynamicSharedMemorySize
-- cudaFuncAttributePreferredSharedMemoryCarveout
-- cudaOccupancyAvailableDynamicSMemPerBlock
-related_skills:
-- bank-conflict
-- coalescing
-- async-copy
-- occupancy-tuning
-- layout-transform
-id: skill-shared-memory-cache
-type: skill
-vendor: nvidia
-tags:
-- cuda-cpp
-- cluster
-- pipeline-stages
-- cache-policy
-- data-reuse
-- loop-unrolling
-- shared-memory-optimization
-- fused-kernel
-- gemm
-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: L719-L727
-- 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: L728-L732
-- 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: L1132-L1150
-- source_id: cuda-official/toolkit-docs-13.2
-  path: CUDA Programming Guides/cuda-programming-guide/cuda_cuda-programming-guide_index.html.md
-  anchor: L1130-L1170
-- source_id: cuda-official/toolkit-docs-13.2
-  path: CUDA Programming Guides/cuda-programming-guide/cuda_cuda-programming-guide_index.html.md
-  anchor: L1484-L1540
-- source_id: cuda-official/toolkit-docs-13.2
-  path: CUDA Programming Guides/cuda-programming-guide/cuda_cuda-programming-guide_index.html.md
-  anchor: L4094-L4130
-architectures:
-- sm90
-- sm90a
-languages:
-- cuda-cpp
-hardware_features:
-- cluster
-techniques:
-- pipeline-stages
-- cache-policy
-- data-reuse
-- loop-unrolling
-- shared-memory-optimization
-kernel_types:
-- fused-kernel
-- gemm
-confidence: experimental
-artifact_dir: artifacts/experience/hw-probes/smem-tile-reuse
----
-## What
-
-**Shared memory** is an on-SM SRAM partition of the unified data cache, addressable only from inside a thread block. A kernel uses it as a **user-managed cache**: the programmer decides which global data to stage into shared memory, when to synchronize, and when to discard the staged copy. Per BP §10.2.3 (L719-L727) "shared memory has much higher bandwidth and lower latency than local and global memory — provided there are no bank conflicts."
-
-Three distinct roles justify the cost of the `__syncthreads()` barrier that almost always accompanies shared memory:
-
-1. **Temporal reuse** — the same global value is read by multiple threads in the block, or by the same thread multiple times (BP §10.2.3.2, L728-L732: "shared memory can be used to access the data from global memory only once").
-2. **Coalescing transform** — a required access pattern would be non-coalesced in global memory. Load coalesced into smem, then read in the desired pattern at no bandwidth penalty (PG §2.2.4.2.1, L1484-L1540, matrix transpose).
-3. **Inter-warp communication** — one warp computes, another warp consumes. Shared memory is the natural staging area because warp shuffles do not cross warps.
-
-If none of these three roles apply, the extra `__syncthreads()` and shared-memory footprint are pure overhead (see pitfall P5).
-
-## Why
-
-Shared memory is the only CUDA storage that simultaneously satisfies: **low latency**, **high bandwidth**, **indexable by lane**, **sized in tens of KB per block**, and **survives across `__syncthreads()` within a kernel**. Warp shuffles beat it on latency but are warp-scoped; global memory beats it on capacity but is an order of magnitude slower on SM-local latency. For reduction, stencil, GEMM, normalization, and any axis-switching operation, the tile-in-smem pattern is the default building block.
-
-The programming guide's own matrix-transpose worked example (PG §2.2.4.2.1, L1484-L1540) makes the point explicit: the naive `c[col*m + row] = a[row*m + col]` pattern writes non-coalesced; staging the tile through `__shared__ float smem[32][32]` restores coalesced reads *and* coalesced writes. The skill below is a generalization of that single example to four sub-patterns.
-
-## When to use
-
-### S1. Tile reuse — cache a tile of global memory for in-block reuse
-
-When multiple threads of the block read the same tile of global data multiple times (e.g. a row of matrix A that participates in every column of the output tile):
-
-```cuda
-#define TILE 32
-__global__ void tiledMultiply(const float* __restrict__ A,
-                              const float* __restrict__ B,
-                              float*       __restrict__ C,
-                              int N) {
-    __shared__ float aTile[TILE][TILE];
-    __shared__ float bTile[TILE][TILE];
-    int row = blockIdx.y * TILE + threadIdx.y;
-    int col = blockIdx.x * TILE + threadIdx.x;
-    float sum = 0.0f;
-
-    for (int k = 0; k < N; k += TILE) {
-        aTile[threadIdx.y][threadIdx.x] = A[row * N + (k + threadIdx.x)];
-        bTile[threadIdx.y][threadIdx.x] = B[(k + threadIdx.y) * N + col];
-        __syncthreads();
-        #pragma unroll
-        for (int i = 0; i < TILE; i++)
-            sum += aTile[threadIdx.y][i] * bTile[i][threadIdx.x];
-        __syncthreads();
-    }
-    C[row * N + col] = sum;
-}
-```
-
-Each A element is read `TILE` times from smem instead of global. BP §10.2.3.2 (L728-L732) documents a direct reduction from `N` global reads per element to `1` global read per element.
-
-### S2. Coalescing transform — coalesce on load, then reorder in smem
-
-When the natural access pattern would be non-coalesced in global (the canonical case is matrix transpose), load coalesced into smem, sync, then read in the transposed order. Pad the second dimension to `TILE+1` to avoid 32-way bank conflicts on column access.
-
-```cuda
-#define TILE 32
-__global__ void transpose(const float* __restrict__ in,
-                          float*       __restrict__ out,
-                          int width, int height) {
-    __shared__ float smem[TILE][TILE + 1];        // +1 breaks column-bank conflict
-    int x = blockIdx.x * TILE + threadIdx.x;
-    int y = blockIdx.y * TILE + threadIdx.y;
-    if (x < width && y < height)
-        smem[threadIdx.y][threadIdx.x] = in[y * width + x];   // coalesced read
-    __syncthreads();
-    x = blockIdx.y * TILE + threadIdx.x;          // swap the block coords
-    y = blockIdx.x * TILE + threadIdx.y;
-    if (x < height && y < width)
-        out[y * height + x] = smem[threadIdx.x][threadIdx.y]; // coalesced write
-}
-```
-
-Both sides (global read and global write) become coalesced. This is the worked example in PG §2.2.4.2.1 (L1484-L1540).
-
-### S3. Dynamic shared memory — tile size chosen at launch
-
-When the tile size depends on runtime arguments, declare `extern __shared__` and pass the byte count as the kernel's third launch parameter:
-
-```cuda
-extern __shared__ float smem[];
-__global__ void dyn_kernel(const float* in, float* out, int tile_w) {
-    int tid = threadIdx.x;
-    if (tid < tile_w) smem[tid] = in[blockIdx.x * tile_w + tid];
-    __syncthreads();
-    if (tid < tile_w) out[blockIdx.x * tile_w + tid] = smem[tid] * 2.f;
-}
-
-// host:
-int tile_w = runtime_chosen();
-dyn_kernel<<<grid, block, tile_w * sizeof(float)>>>(in, out, tile_w);
-```
-
-For >48 KB per block, also call `cudaFuncSetAttribute(kernel, cudaFuncAttributeMaxDynamicSharedMemorySize, bytes)` before launch (PG §3.2.6, L4094-L4130, "must use dynamic shared memory and require an explicit opt-in"). When partitioning one buffer into multiple typed arrays, align each partition manually (see P3).
-
-### S4. L1/Shared carveout — give the kernel the split it actually needs
-
-On Volta+, L1 cache and shared memory share one physical SRAM. A kernel that uses little or no shared memory should let the hardware use the area as L1; a kernel that lives and dies by its smem tile should claim most of it for shared. Control per-kernel with:
-
-```cuda
-// Prefer maximum shared memory (typical for GEMM/normalization tiling)
-cudaFuncSetAttribute(my_kernel,
-    cudaFuncAttributePreferredSharedMemoryCarveout,
-    cudaSharedmemCarveoutMaxShared);
-
-// Or integer percentage (PG §3.2.6, L4094-L4130):
-cudaFuncSetAttribute(my_kernel,
-    cudaFuncAttributePreferredSharedMemoryCarveout, 50);
-```
-
-The driver rounds up to the next supported capacity. PG §3.2.6 notes the setter is a **hint** — the driver may override if the kernel cannot otherwise launch.
-
-## When NOT to use
-
-- **No reuse, no coalescing problem, no cross-warp communication.** If each smem element is read exactly once per block and the global access pattern is already coalesced, the smem stage adds a `__syncthreads()` barrier and a register round-trip for zero benefit. Let the hardware L1 handle the one-shot read (BP §10.2.3 L719-L727 — "effects of shared memory" cautions against this exact case, and pitfall P5 describes the symptom).
-- **Tile size forces occupancy below the bandwidth knee.** When the per-block smem claim drops occupancy to 1 block/SM, memory-latency hiding collapses. Budget the tile to keep ≥2 blocks/SM on the target device (BP §11.4, L1132-L1150). For the H200-specific breakpoint, see the measured section below.
-- **`cp.async` would do the job better.** For a fresh tile used once, `cuda::memcpy_async` + `cuda::pipeline` overlaps the load with compute and avoids blocking the warp on the barrier (see the `async-copy` skill). Shared memory is still the destination, but the path is different.
-- **DSMEM access wants the same discipline as global.** Reads of another block's
-  shared memory should be coalesced and aligned to 32-byte segments; a non-unit
-  stride is as bad here as it is against HBM. If the access pattern is genuinely
-  random, copy the tile into local shared memory first and randomize there.
-  DSMEM and L2 bandwidth are usable **at the same time**, so a kernel that splits
-  its traffic between them gets the sum rather than the max.
-  ⚠️ *Both statements are transcribed from a guideline document, unverified here.*
-- **Distributed smem fits the shape better.** Histograms / reductions that need >one-block smem can use sm_90 distributed shared memory via thread-block clusters (`cluster.map_shared_rank`). That is not covered by this skill — see the `thread-block-cluster` entry under `wiki/nvidia/hardware/` once bootstrapped.
-
-## Measured Characteristics
-
-Measured on H200-SXM (sm_90a, CUDA 12.9, driver 570.124.06) using `sources/experience/hw-probes/smem-tile-reuse/` — S2 coalescing-transform variant on matrix transpose, N = 4096×4096 fp32, default L1/smem carveout, unlocked clock logged at 1980 MHz. Full record: sources/experience/hw-probes/smem-tile-reuse.md.
-
-| Kernel                          | Median ms | Eff. BW GB/s | DRAM SoL | Warp cyc/issue | Bank conflicts (ld) |
-| ------------------------------- | --------: | -----------: | -------: | -------------: | ------------------: |
-| `naive_transpose`               |    0.2544 |       527.65 |    9.64% |         163.48 |                   0 |
-| `smem_tiled` (unpadded 32×32)   |    0.1363 |       984.81 |   14.96% |          85.54 |      **16,326,828** |
-| `smem_tiled` (padded 32×33)     | **0.0796**|  **1685.14** | **29.10%**|     **42.09** |              33,449 |
-
-- **S2 alone gives 1.87× over the naive non-coalesced-store baseline** (coalescing transform via smem), even before bank-conflict fixes.
-- **`[TILE][TILE+1]` padding contributes another 1.71×** on top of S2 for **3.19× total**; bank conflicts drop **488.4×** (16.3 M → 33.4 K).
-- **Warp cycles / issued instruction** is the cleanest NCU signature: 163 → 86 → 42 tracks the two optimizations exactly.
-- DRAM SOL rises from 9.6 % (naive, L2-replay-limited) to 29.1 % (padded, memory-balanced). The padded kernel is now DRAM-bound on this 64 MB working set, not smem-pipe-limited.
-- Pitfall P8 ("unpadded `[TILE][TILE]` causes 32-way bank conflicts") is upgraded to measured on the strength of this probe.
-- Sub-skills **S1 (temporal reuse)**, **S3 (dynamic vs static smem)**, **S4 (carveout sweep)** are **not yet probed**; they remain `inferred` against PG / BP Guide until follow-up probes land.
-
-## Principles
-
-1. **Pay `__syncthreads()` only for reuse, reorder, or cross-warp communication.** Absent one of the three, stay in registers or let L1 do its job.
-2. **Padding is how smem layouts stop being bank-pathological.** A `[TILE][TILE+1]` declaration turns a column access from 32-way conflict into conflict-free. Treat this as the default for any 2-D smem tile you intend to read by column.
-3. **Smem footprint is an occupancy knob, not just a correctness choice.** Per BP §11.4 (L1132-L1150), tile size decisions must be paired with a check on "how many blocks/SM does this buy me."
-4. **Carveout API is a hint, not a contract.** Ship with a verified default (often `MaxShared` for GEMM/LN kernels, default for elementwise) and measure. Do not write a runtime heuristic that flips carveout per launch unless profiling demands it.
-
-## Open questions
-
-- Q1. On H200, what is the smem-carveout break-even point where L1 pressure costs more than the reuse gain from extra shared memory? Planned follow-up probe: `smem-tile-reuse/carveout-sweep/`.
-- Q2. Does `[TILE][TILE+1]` padding still strictly dominate on sm_90a for 16-bit tile elements (where 4 bf16 share one 32-bit bank)? Planned follow-up: bf16 variant inside the same probe family.
-- Q3. Break-even between static and dynamic smem for tiles under 16 KB — is there a measurable compiler-optimization penalty as old KB pitfall P9 claims (see `pitfalls.md`)?
-
-## Legacy references
-
-- `legacy_sandbox_path`: `KernelPilot/optimization/memory/shared-memory-cache/skill.md`. Original source had six sub-skills; this MVP port keeps S1–S4 and routes Skill 5 (large dynamic smem >48 KB) into S3 as the opt-in footnote, and Skill 6 (distributed shared memory) to the `wiki/nvidia/hardware/thread-block-cluster/` skill (pending bucket F bootstrap).
-- Legacy Level-3 sandbox findings are retained in `pitfalls.md` as P7 through P11; they were run on small inputs and do not constitute measured evidence until re-run on the H200 probe.
-
-## Health thresholds
-
-Staging data through shared memory pays off only when the data is read more
-than once. The precondition is arithmetic:
-
-```
-reuse factor = (reads of a datum by the block) / (times it is loaded from global)
-```
-
-**reuse > 1 is the entry condition.** At reuse == 1 the staging adds a global
-load, a shared store, a barrier and a shared load, and returns nothing — this
-is why element-wise kernels correctly use no shared memory at all.
-
-The complementary signal comes from the DRAM side: when
-`dram__throughput.avg.pct_of_peak_sustained_elapsed` is near peak while SM
-throughput is not, the kernel is memory-bound and reducing DRAM traffic — which
-is what staging does — is the lever that applies.
-
-## Shared vs global: two different ratios, routinely conflated
-
-Both numbers below come from the [H200 memory hierarchy](../../hardware/foundation/memory-hierarchy.md)
-table; neither is a new measurement.
-
-| Ratio | Shared | HBM | Factor |
-|---|---|---|---|
-| **Bandwidth** | ~19 TB/s aggregate | 4.8 TB/s | **≈ 4x** |
-| **Latency** | ~20-30 cycles | ~400-600 cycles (L2 hit ~200) | **≈ 15-30x** |
-
-⚠️ **These get swapped.** Guideline material in circulation says "shared memory
-bandwidth is 10-20x global" -- that figure is close to the *latency* ratio and
-roughly 4x too large for bandwidth. If you are deciding whether staging is worth
-a barrier, the ratio you want depends on what limits you: a bandwidth-bound
-kernel gains ~4x on the reuse it actually achieves, while a latency-bound one
-gains far more per access.
-
-⚠️ *The 4x and 15-30x here are divisions of numbers already in the hierarchy
-table, not fresh probes. The underlying H200 figures carry that page's own
-evidence level.*