@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/compute/compiler-hints/apis.md

@@ -1,124 +0,0 @@
----
-func_name: __launch_bounds__
-namespace: runtime
-header: cuda_runtime.h
-signature: __launch_bounds__(maxThreadsPerBlock [, minBlocksPerMultiprocessor [, maxBlocksPerCluster]])
-status: documented
-has_end_to_end_example: true
-source:
-- path: spec
-  anchor: Reference
-id: api-compiler-hints-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: L22816-L22905
-architectures:
-- sm90
-- sm90a
-languages:
-- ptx
-- cuda-cpp
-hardware_features:
-- cluster
-techniques:
-- cache-policy
-- register-budgeting
-- loop-unrolling
-- shared-memory-optimization
-confidence: inferred
-evidence_level: inferred
-tags:
-- cluster
-- cache-policy
-- register-budgeting
-- loop-unrolling
-- shared-memory-optimization
-- ptx
-- cuda-cpp
----
-# Compiler Hints API Reference
-
-This file lists the APIs touched by the compiler-hints skill. Each entry records the function name, namespace, and signature as found in upstream documentation.
-
-## Launch Configuration Directives
-
-### `__launch_bounds__`
-
-- **Namespace**: runtime (CUDA C++ function qualifier)
-- **Header**: `cuda_runtime.h` (language built-in, no explicit include needed)
-- **Signature**: `__launch_bounds__(maxThreadsPerBlock [, minBlocksPerMultiprocessor [, maxBlocksPerCluster]])`
-- **PTX**: `.maxntid` (from maxThreadsPerBlock), `.minnctapersm` (from minBlocksPerMultiprocessor), `.maxclusterrank` (from maxBlocksPerCluster)
-- **Semantics**: Annotates a `__global__` function with launch configuration hints. The compiler derives a register ceiling L = registersPerSM / (maxThreadsPerBlock * minBlocksPerMultiprocessor) and adjusts code generation to fit within it. If only `maxThreadsPerBlock` is specified, the compiler uses it to determine register usage thresholds for occupancy transitions. If both parameters are specified, the compiler may increase register usage up to L to reduce instruction count.
-- **Runtime enforcement**: A kernel will fail to launch if invoked with more threads per block than `maxThreadsPerBlock` or more blocks per cluster than `maxBlocksPerCluster`.
-- **Source**: Programming guide L22816-L22905
-
-### `__maxnreg__`
-
-- **Namespace**: runtime (CUDA C++ function qualifier)
-- **Header**: `cuda_runtime.h` (language built-in)
-- **Signature**: `__maxnreg__(maxNumberRegistersPerThread)`
-- **PTX**: `.maxnreg`
-- **Semantics**: Directly caps the per-thread register count for a kernel. Mutually exclusive with `__launch_bounds__` on the same kernel.
-- **Source**: Programming guide L22890-L22905
-
-### `--maxrregcount=N`
-
-- **Namespace**: nvcc compiler flag
-- **Signature**: `nvcc --maxrregcount=N` or `nvcc -maxrregcount=N`
-- **Semantics**: Sets a per-file maximum register count for all `__global__` functions. Ignored for kernels that have `__maxnreg__`. Does not interact with `__launch_bounds__`.
-- **Source**: Best practices guide L2320
-
-## Pointer and Memory Hints
-
-### `__restrict__`
-
-- **Namespace**: runtime (CUDA C++ type qualifier)
-- **Header**: `cuda_runtime.h` (language built-in)
-- **Signature**: applied to pointer parameters, e.g., `const float* __restrict__ ptr`
-- **PTX effect**: Enables `ld.global.nc` (non-coherent / read-only cache) loads for `const __restrict__` pointers in `__global__` functions.
-- **Semantics**: Promises the compiler that the pointer does not alias any other pointer in scope. Enables code reordering, common sub-expression elimination, and register caching of loaded values. All pointer parameters should be annotated for the optimizer to be effective. Increases register pressure as a tradeoff.
-- **Source**: Programming guide L22292-L22365
-
-## Runtime Configuration
-
-### `cudaFuncSetAttribute`
-
-- **Namespace**: runtime
-- **Header**: `cuda_runtime_api.h`
-- **Signature**: `cudaError_t cudaFuncSetAttribute(const void* func, cudaFuncAttribute attr, int value)`
-- **Semantics**: Sets a per-kernel attribute at runtime. Key attributes:
-  - `cudaFuncAttributeMaxDynamicSharedMemorySize`: opt-in for dynamic shared memory exceeding 48KB. Must be called before the kernel launch. Required for kernels using large shared memory buffers.
-  - `cudaFuncAttributePreferredSharedMemoryCarveout`: hint for L1/shared memory partitioning. Accepted values include `cudaSharedmemCarveoutDefault`, `cudaSharedmemCarveoutMaxL1`, `cudaSharedmemCarveoutMaxShared`, or an integer percentage. The driver rounds up to the next supported capacity.
-  - `cudaFuncAttributeNonPortableClusterSizeAllowed`: enables non-portable cluster sizes.
-- **Source**: Programming guide L4094-L4130
-
-## Loop Control
-
-### `#pragma unroll`
-
-- **Namespace**: compiler pragma (not a function)
-- **Signature**: `#pragma unroll [N]`
-- **Semantics**: Controls loop unrolling for the immediately following loop.
-  - No argument: fully unrolls if trip count is known at compile time.
-  - N > 1: unrolls by factor N.
-  - N = 0 or 1: disables unrolling.
-  - Negative N: pragma is ignored (warning issued).
-  The expression can be a constexpr, e.g., `#pragma unroll (MyStruct::value)`.
-- **Source**: Programming guide L24765-L24810
-
-## Diagnostic Flags
-
-### `-Xptxas=-v`
-
-- **Namespace**: nvcc compiler flag
-- **Signature**: `nvcc -Xptxas=-v` or `nvcc --ptxas-options=-v`
-- **Semantics**: Passes `-v` (verbose) to the ptxas assembler, which reports per-kernel: register count, shared memory usage (static + dynamic), constant memory usage, stack frame size, and spill store/load byte counts. Essential for diagnosing register pressure.
-- **Source**: Best practices guide L2321
-
-## Related Probes
-
-- `cudaFuncSetAttribute` — end-to-end example, build command, and H200 measurement. See probe record.

package/resources/kop-2026-10-23-0.1.17-beta.1/product_capabilities/kernel_optflow/skills/KernelWiki-private/wiki/nvidia/foundations/compute/compiler-hints/pitfalls.md

@@ -1,171 +0,0 @@
----
-title: Compiler Hints - Pitfalls
-status: draft
-evidence_level: measured
-applies_to_pattern_class:
-- cuda-core
-applies_to_ops:
-- elementwise
-- reduction
-- normalization
-- scan
-requires_sm: '>=3.0'
-single_kernel_useful: true
-source:
-- path: spec
-  anchor: Reference
-id: pitfall-compiler-hints
-type: pitfall
-vendor: nvidia
-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: L22833-L22841
-- source_id: cuda-official/toolkit-docs-13.2
-  path: CUDA Programming Guides/cuda-programming-guide/cuda_cuda-programming-guide_index.html.md
-  anchor: L22904
-- source_id: cuda-official/toolkit-docs-13.2
-  path: CUDA Programming Guides/cuda-programming-guide/cuda_cuda-programming-guide_index.html.md
-  anchor: L22346
-- source_id: cuda-official/toolkit-docs-13.2
-  path: CUDA Programming Guides/cuda-programming-guide/cuda_cuda-programming-guide_index.html.md
-  anchor: L22863-L22887
-- source_id: cuda-official/toolkit-docs-13.2
-  path: CUDA Programming Guides/cuda-programming-guide/cuda_cuda-programming-guide_index.html.md
-  anchor: L22324
-architectures:
-- sm90
-- sm90a
-languages:
-- cuda-cpp
-techniques:
-- cache-policy
-- register-budgeting
-- loop-unrolling
-- shared-memory-optimization
-- communication-overlap
-kernel_types:
-- fused-kernel
-confidence: experimental
-tags:
-- cache-policy
-- register-budgeting
-- loop-unrolling
-- shared-memory-optimization
-- communication-overlap
-- fused-kernel
-- cuda-cpp
----
-## P1: Register spilling from overly tight launch_bounds
-
-**Symptom**: Kernel performance degrades after adding `__launch_bounds__` despite higher theoretical occupancy. `-Xptxas=-v` output shows non-zero "spill stores" and "spill loads."
-
-**Cause**: The `minBlocksPerMultiprocessor` parameter is set too high, forcing the register cap L below what the kernel naturally requires. The compiler must spill excess registers to local memory, which resides in global memory (L1/L2 cached but still much slower than registers).
-
-**Example**: On H200 (sm_90a) with `__launch_bounds__(256, 8)`, the register cap is 65536 / (256 * 8) = 32 per thread. A kernel that naturally needs 56 registers would spill 24 registers' worth of data to local memory.
-
-**Detection**: Always compile with `-Xptxas=-v` and check:
-```
-ptxas info: Used 32 registers, 96 bytes spill stores, 96 bytes spill loads
-```
-Any non-zero spill count is a red flag. The cost of spilling typically outweighs the benefit of higher occupancy.
-
-**Fix**: Reduce `minBlocksPerMultiprocessor` until spill counts reach zero. Use the occupancy calculator or `cudaOccupancyMaxActiveBlocksPerMultiprocessor` to find the actual block count, then set `minBlocksPerMultiprocessor` to that value or one below.
-
-## P2: Combining __launch_bounds__ and __maxnreg__ on the same kernel
-
-**Symptom**: Compilation error.
-
-**Cause**: The programming guide explicitly states: "The `__launch_bounds__()` and `__maxnreg__()` qualifiers cannot be applied to the same kernel together." They are mutually exclusive approaches to controlling register allocation.
-
-**Fix**: Choose one approach. `__launch_bounds__` is generally preferred because it communicates occupancy intent (the compiler derives the register cap from the occupancy target). `__maxnreg__` directly controls register count but gives the compiler no occupancy information.
-
-## P3: __CUDA_ARCH__ undefined in host code for launch configuration
-
-**Symptom**: Kernel launches with the wrong thread count when `__launch_bounds__` parameters are architecture-conditional.
-
-**Cause**: The programming guide pattern uses `__CUDA_ARCH__` to set different launch bounds per architecture:
-```cuda
-#if __CUDA_ARCH__ >= 900
-    #define MY_KERNEL_MAX_THREADS  512
-#else
-    #define MY_KERNEL_MAX_THREADS  256
-#endif
-```
-But `__CUDA_ARCH__` is undefined in host code, so `kernel<<<grid, MY_KERNEL_MAX_THREADS>>>()` in host code always uses the else branch (256), even when targeting sm_90a.
-
-**Fix**: Either use a compile-time constant that does not depend on `__CUDA_ARCH__`, or determine the thread count at runtime via `cudaGetDeviceProperties`:
-```cuda
-int threadsPerBlock = (prop.major >= 9) ? 512 : 256;
-kernel<<<grid, threadsPerBlock>>>(...);
-```
-
-## P4: __restrict__ applied to aliased pointers
-
-**Symptom**: Silent incorrect results. The kernel produces wrong output for certain input patterns, especially when input and output buffers overlap.
-
-**Cause**: `__restrict__` is a promise to the compiler that the pointer does not alias any other pointer. If this promise is violated (e.g., in-place operations where `input == output`), the compiler may reorder loads and stores in ways that produce incorrect results. This is undefined behavior -- no compiler warning, no runtime error.
-
-**Fix**: Only use `__restrict__` when you can guarantee non-aliasing. For in-place kernels, do not mark both input and output as `__restrict__`. Review all call sites to ensure no aliasing.
-
-## P5: Partial __restrict__ annotation is ineffective
-
-**Symptom**: No performance improvement despite adding `__restrict__` to some pointer parameters.
-
-**Cause**: The programming guide states: "Note that all pointer arguments must be restricted for the compiler optimizer to be effective." If only some pointers are marked `__restrict__`, the compiler cannot safely assume non-aliasing between the annotated and unannotated pointers.
-
-**Fix**: Annotate all pointer parameters in the function, or none. For `__global__` functions, also use `const` on read-only pointers to enable the `ld.global.nc` read-only cache path.
-
-## P6: __restrict__ increasing register pressure
-
-**Symptom**: Adding `__restrict__` to all pointer parameters causes register count to increase (visible in `-Xptxas=-v` output), reducing occupancy and potentially harming performance.
-
-**Cause**: `__restrict__` enables the compiler to cache more loads in registers and perform common sub-expression elimination. This optimization trades memory accesses for register pressure. The programming guide warns: "The result is a reduced number of memory accesses and computations, balanced by an increase in register pressure from caching loads and common sub-expressions in registers."
-
-**Detection**: Compare register counts with and without `__restrict__` using `-Xptxas=-v`. If the increase crosses an occupancy threshold (causing fewer blocks to fit on an SM), the net effect may be negative.
-
-**Fix**: If register pressure is already high, consider not using `__restrict__` on some parameters, or combine with `__launch_bounds__` to cap the register count. Profile both variants to determine which is faster.
-
-## P7: Launching with more threads than maxThreadsPerBlock
-
-**Symptom**: Kernel launch fails at runtime with "invalid configuration argument" or "too many resources requested for launch."
-
-**Cause**: `__launch_bounds__(maxThreadsPerBlock)` sets a hard cap on the block size. The runtime enforces this: launching with more threads per block than the declared maximum results in a launch failure.
-
-**Detection**: Check `cudaFuncAttributes.maxThreadsPerBlock` at runtime. In the probe, `heavy_no_lb` reported `maxTPB=1024` while `heavy_lb_256_4` reported `maxTPB=256`.
-
-**Fix**: Ensure the launch configuration's block size does not exceed the declared `maxThreadsPerBlock`. When using architecture-conditional bounds, be especially careful with the host-side launch config (see P3).
-
-## P8: Forgetting cudaFuncSetAttribute for large dynamic shared memory
-
-**Symptom**: Kernel launch fails with "invalid configuration argument" when requesting more than 48KB of dynamic shared memory.
-
-**Cause**: By default, kernels are limited to 48KB of dynamic shared memory. Using more requires an explicit opt-in via `cudaFuncSetAttribute(kernel, cudaFuncAttributeMaxDynamicSharedMemorySize, bytes)` before the launch. This is a runtime requirement, not a compile-time one.
-
-**Fix**: Call `cudaFuncSetAttribute` with the required shared memory size before the first launch that needs it:
-```cuda
-int maxbytes = 98304;  // 96 KB
-cudaFuncSetAttribute(MyKernel,
-    cudaFuncAttributeMaxDynamicSharedMemorySize, maxbytes);
-MyKernel<<<gridDim, blockDim, maxbytes>>>(...);
-```
-
-## P9: Over-unrolling with #pragma unroll
-
-**Symptom**: Kernel performance degrades or register count spikes after adding `#pragma unroll` to a loop.
-
-**Cause**: Full unrolling of loops with large trip counts creates many copies of the loop body, increasing code size (instruction cache pressure) and register pressure (many live variables from all iterations simultaneously). The instruction cache on H200 is limited, and code that exceeds it incurs costly re-fetches.
-
-**Detection**: Compare register counts and instruction counts with and without the pragma using `-Xptxas=-v`.
-
-**Fix**: Use `#pragma unroll N` with a specific factor (e.g., 4 or 8) instead of unbounded `#pragma unroll`. The factor should balance ILP benefits against code size. For loops with variable or large trip counts, `#pragma unroll 1` explicitly disables unrolling.
-
-## P10: Assuming launch_bounds always reduces register count
-
-**Symptom**: Confusion when `__launch_bounds__(maxTPB, minBlocks)` results in the compiler using more registers, not fewer.
-
-**Cause**: When both parameters are specified, the compiler may intentionally increase register usage up to the limit L to "reduce the number of instructions and better hide the latency of single-threaded instructions." This was observed in the probe: `heavy_lb_256_4` used 56 registers vs 48 for `heavy_no_lb`.
-
-**This is not a bug** -- it is the documented behavior. The compiler trades occupancy headroom for instruction efficiency when it knows the occupancy floor.
-
-**Fix**: No action needed if spill counts remain zero. Verify with `-Xptxas=-v` that no spilling occurred. If register usage exceeds L, the compiler will spill and that is where problems start (see P1).

package/resources/kop-2026-10-23-0.1.17-beta.1/product_capabilities/kernel_optflow/skills/KernelWiki-private/wiki/nvidia/foundations/compute/compiler-hints.md

@@ -1,207 +0,0 @@
----
-title: Compiler Hints
-status: draft
-evidence_level: measured
-applies_to_pattern_class:
-- cuda-core
-applies_to_ops:
-- elementwise
-- reduction
-- normalization
-- scan
-requires_sm: '>=3.0'
-requires_features: []
-single_kernel_useful: true
-cuda_version_tested: '12.9'
-driver_version_tested: 570.124.06
-toolchain: nvcc 12.9 + ptxas 12.9
-measured_on: H200-SXM
-source:
-- path: spec
-  anchor: Reference
-artifacts:
-  code: artifacts/experience/hw-probes/compiler-hints/launch_bounds_probe.cu
-  build: nvcc -arch=sm_90a -O3 -std=c++17 -lineinfo -Xptxas=-v -o launch_bounds_probe launch_bounds_probe.cu
-  introspection: ''
-  profile: ''
-related_apis:
-- __launch_bounds__
-- __maxnreg__
-- __restrict__
-- cudaFuncSetAttribute
-related_skills:
-- ilp
-- warp-primitives
-- fast-math
-id: skill-compiler-hints
-type: skill
-vendor: nvidia
-tags:
-- cuda-cpp
-- cluster
-- cache-policy
-- register-budgeting
-- loop-unrolling
-- 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-programming-guide/cuda_cuda-programming-guide_index.html.md
-  anchor: L22816-L22905
-- source_id: cuda-official/toolkit-docs-13.2
-  path: CUDA Programming Guides/cuda-programming-guide/cuda_cuda-programming-guide_index.html.md
-  anchor: L22292-L22365
-- source_id: cuda-official/toolkit-docs-13.2
-  path: CUDA Programming Guides/cuda-programming-guide/cuda_cuda-programming-guide_index.html.md
-  anchor: L24765-L24810
-- source_id: cuda-official/toolkit-docs-13.2
-  path: CUDA Programming Guides/cuda-programming-guide/cuda_cuda-programming-guide_index.html.md
-  anchor: L22890-L22905
-- 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: L1064-L1099
-- 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: L2318-L2324
-- 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:
-- ptx
-- cuda-cpp
-hardware_features:
-- cluster
-techniques:
-- cache-policy
-- register-budgeting
-- loop-unrolling
-- shared-memory-optimization
-- communication-overlap
-kernel_types:
-- fused-kernel
-confidence: experimental
-artifact_dir: artifacts/experience/hw-probes/compiler-hints
----
-## What
-
-Compiler hints are source-level annotations and compiler flags that guide CUDA code generation without changing program semantics. They influence register allocation, occupancy, memory-access patterns, and loop structure. The key compiler hints covered by this skill are:
-
-**Launch configuration directives:**
-
-- `__launch_bounds__(maxThreadsPerBlock, minBlocksPerMultiprocessor)` -- Annotates a `__global__` function with the maximum block size and an optional minimum resident-block count. The compiler derives a register ceiling L from these parameters and adjusts code generation accordingly. Compiles to the `.maxntid` and `.minnctapersm` PTX directives. A third optional parameter `maxBlocksPerCluster` controls cluster launch limits (compiles to `.maxclusterrank`).
-
-- `__maxnreg__(N)` -- Directly caps the per-thread register count for a kernel. Compiles to the `.maxnreg` PTX directive. Cannot be used together with `__launch_bounds__` on the same kernel.
-
-- `--maxrregcount=N` -- nvcc flag that sets a per-file register cap for all `__global__` functions. Ignored for kernels that have `__maxnreg__`.
-
-**Pointer and memory hints:**
-
-- `__restrict__` -- Declares that a pointer does not alias other pointers, enabling the compiler to cache loads in registers, reorder memory operations, and eliminate redundant loads. When applied to `const` pointers in `__global__` functions, loads compile to `ld.global.nc` (read-only data cache path) instead of `ld.global`.
-
-**Loop control:**
-
-- `#pragma unroll` -- Controls loop unrolling. Without an argument, fully unrolls loops with known trip counts. With an integer argument N, unrolls by factor N. With argument 1, disables unrolling.
-
-**Runtime configuration:**
-
-- `cudaFuncSetAttribute` -- Host-side API to configure per-kernel properties at runtime, including `cudaFuncAttributeMaxDynamicSharedMemorySize` (opt-in for >48KB dynamic shared memory) and `cudaFuncAttributePreferredSharedMemoryCarveout` (L1/shared memory partitioning).
-
-**Diagnostic flags:**
-
-- `-Xptxas=-v` (or `--ptxas-options=-v`) -- Reports per-kernel register count, shared memory usage, constant memory usage, and spill stores/loads. This is the primary tool for diagnosing register pressure. The `--resource-usage` flag provides similar output.
-
-## Why
-
-Register allocation is the central tradeoff in CUDA kernel optimization. Each SM on H200 (sm_90a) has 65,536 32-bit registers shared among all resident threads. Using fewer registers per thread allows more concurrent warps (higher occupancy), which improves latency hiding. Using more registers per thread can reduce instruction count (avoiding recomputation) and eliminate register spills to local memory, but reduces occupancy.
-
-The compiler makes this tradeoff heuristically. Compiler hints let the programmer override or guide these heuristics based on knowledge the compiler lacks -- specifically, the intended launch configuration and whether pointer aliasing exists.
-
-On H200 with `__launch_bounds__(256, 4)`:
-- Register cap = 65536 / (256 * 4) = 64 registers per thread
-- The compiler can use up to 64 registers to reduce instruction count
-- If the kernel naturally needs >64 registers, the compiler spills to local memory (which has global memory latency)
-
-Without launch_bounds, the compiler uses its own heuristics to balance register usage against occupancy. The heuristic can be either too conservative (using fewer registers than optimal, increasing instruction count) or too aggressive (using too many registers, reducing occupancy).
-
-`__restrict__` eliminates aliasing analysis overhead and enables the read-only cache path (`ld.global.nc`), which uses the texture cache and avoids polluting the L1 data cache with read-only data.
-
-## When to use
-
-- **`__launch_bounds__` with one argument** -- Always include on production kernels as a forward-compatibility safeguard. The programming guide recommends: "developers should include the single argument `__launch_bounds__(maxThreadsPerBlock)` which specifies the largest block size with which the kernel will launch. Failure to do so could result in 'too many resources requested for launch' errors."
-
-- **`__launch_bounds__` with two arguments** -- When profiling shows that occupancy is limited by register usage and you know the minimum number of blocks needed per SM. Set `minBlocksPerMultiprocessor` to the desired occupancy floor. The compiler will then adjust register allocation to guarantee that many blocks can co-reside.
-
-- **`__restrict__`** -- On all pointer parameters in `__global__` and `__device__` functions where the programmer can guarantee no aliasing. Especially valuable when the kernel performs multiple reads from the same addresses (common sub-expressions) or when read-only data should use the texture cache path.
-
-- **`#pragma unroll`** -- On inner loops with small known trip counts where the compiler's default unrolling is insufficient. Also on reduction loops, ILP-generating loops, and loops over warp shuffle steps.
-
-- **`cudaFuncSetAttribute` for dynamic shared memory** -- Required when a kernel uses more than 48KB of dynamic shared memory. Must be called before the kernel launch.
-
-- **`-Xptxas=-v`** -- During development, always compile with this flag to monitor register and shared memory usage. Sudden register count increases across code changes indicate potential performance regressions.
-
-## When NOT to use
-
-- **Overly tight `__launch_bounds__`** -- Setting `minBlocksPerMultiprocessor` too high forces the compiler to reduce registers below what the kernel naturally needs, causing register spilling. Spills go to local memory (global memory latency), which can be far worse than reduced occupancy. Check `-Xptxas=-v` output for "spill stores" and "spill loads" after adding launch_bounds.
-
-- **`__restrict__` with aliased pointers** -- If two pointer arguments actually can point to overlapping memory, adding `__restrict__` produces undefined behavior. In-place operations (where input and output buffers overlap) must not use `__restrict__` on both pointers.
-
-- **`#pragma unroll` on large or variable-trip loops** -- Full unrolling of large loops increases code size, which can cause instruction cache misses and increase register pressure. Use `#pragma unroll N` with a specific factor instead of unbounded unrolling.
-
-- **`__maxnreg__` and `__launch_bounds__` together** -- These are mutually exclusive on the same kernel. The compiler rejects the combination.
-
-- **Blindly maximizing occupancy** -- Higher occupancy does not always mean higher performance. A kernel that is compute-bound may benefit from more registers (lower occupancy but less recomputation) rather than fewer registers (higher occupancy but more instructions). The best practices guide notes: "Higher occupancy does not always equate to higher performance -- there is a point above which additional occupancy does not improve performance."
-
-## Classical example: vector operation with compiler hints
-
-```cuda
-#define BLOCK_SIZE 256
-
-__global__ void
-__launch_bounds__(BLOCK_SIZE, 4)
-fused_scale_bias(const float* __restrict__ input,
-                 const float* __restrict__ scale,
-                 const float* __restrict__ bias,
-                 float*       __restrict__ output,
-                 int n) {
-    int i = blockIdx.x * blockDim.x + threadIdx.x;
-
-    // __restrict__ enables the compiler to:
-    //   1. Load input[i], scale[i], bias[i] via ld.global.nc (read-only cache)
-    //   2. Cache the loads in registers without worrying about aliasing
-    //   3. Reorder loads freely for ILP
-    if (i < n) {
-        float x = input[i];
-        float s = scale[i];
-        float b = bias[i];
-        output[i] = x * s + b;
-    }
-}
-
-// Host-side: opt-in for large dynamic shared memory
-// cudaFuncSetAttribute(fused_scale_bias,
-//     cudaFuncAttributeMaxDynamicSharedMemorySize, 98304);
-```
-
-Compile with diagnostics:
-```bash
-nvcc -arch=sm_90a -O3 -std=c++17 -Xptxas=-v -o kernel kernel.cu
-```
-
-Reading the `-Xptxas=-v` output:
-```
-ptxas info: Used 14 registers, 0 bytes spill stores, 0 bytes spill loads
-```
-- `Used 14 registers`: per-thread register count
-- `0 bytes spill stores/loads`: no register spilling (good)
-- If spill counts are non-zero, the kernel is over-pressured and `__launch_bounds__` may need loosening
-
-## Measured Characteristics
-
-- launch-bounds register-effect probe: On H200 (sm_90a, CUDA 12.9), a register-heavy kernel (32 accumulators, 3 rounds of cross-dependent FMA) showed that `__launch_bounds__(256, 4)` caused the compiler to allocate **56 registers** (vs 48 without launch bounds), with zero spills in both cases. The compiler increased register usage to reduce instruction count, staying within the 64-register occupancy cap. Latency was identical (0.120 ms) because both variants achieved 100% occupancy at block size 256. This confirms the programming guide statement that the compiler "may increase register usage up to L in order to reduce the number of instructions."