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

@@ -1,147 +0,0 @@
----
-title: Non-aligned GEMM tail handling on Hopper via cutlass cooperative kernel
-status: partial
-evidence_level: measured
-applies_to_pattern_class:
-- tensor-core
-applies_to_ops:
-- gemm
-requires_sm: '>=9.0a'
-requires_features:
-- tma
-- wgmma
-- mbarrier
-single_kernel_useful: true
-cuda_version_tested: 12.9.86
-driver_version_tested: 570.124.06
-toolchain: nvcc 12.9 + ptxas 12.9
-measured_on: H200-SXM | sm_90a | cuda 12.9.86 | driver 570.124.06
-source:
-- path: spec
-  anchor: Reference
-artifacts:
-  code: artifacts/experience/api-probes/gemm/gemm_tail.cu
-  build: artifacts/experience/api-probes/gemm/build_tail.sh
-  introspection: artifacts/experience/api-probes/gemm/device.json
-  profile: artifacts/experience/api-probes/gemm/2026-04-28-gemm-tail.csv
-upstream_repo: cutlass@f74fea9c
-related_apis: []
-related_skills:
-- tma
-- wgmma
-- gemm-aligned
-id: skill-gemm
-type: skill
-vendor: nvidia
-tags:
-- cuda-cpp
-- wgmma
-- tma
-- mbarrier
-- cluster
-- warp-specialization
-- tile-scheduling
-- tma-multicast
-- gemm
-- attention
-- quantization
-- grouped-gemm
-- ptx
-- cute-dsl
-applies_to:
-- general
-source_refs:
-- source_id: source-code/cutlass
-  path: include/cutlass/gemm/collective/sm90_mma_tma_gmma_ss_warpspecialized.hpp
-  anchor: MainloopSm90TmaGmmaWarpSpecialized + can_implement
-- source_id: source-code/cutlass
-  path: examples/48_hopper_warp_specialized_gemm/48_hopper_warp_specialized_gemm.cu
-  anchor: Lall (gemm.can_implement(arguments) on line 415)
-- source_id: blogs/colfax
-  path: developing-cuda-kernels-for-gemm-on-nvidia-hopper-architecture-using-cutlass
-  anchor: Hopper warp-specialized cooperative GEMM
-architectures:
-- sm90
-- sm90a
-languages:
-- ptx
-- cuda-cpp
-- cute-dsl
-hardware_features:
-- wgmma
-- tma
-- mbarrier
-- cluster
-techniques:
-- warp-specialization
-- tile-scheduling
-- tma-multicast
-kernel_types:
-- gemm
-- attention
-- quantization
-- grouped-gemm
-confidence: experimental
-artifact_dir: artifacts/experience/api-probes/gemm
----
-# Non-aligned GEMM tail handling on Hopper
-
-## What it is
-
-The Hopper warp-specialized cooperative GEMM kernel from cutlass example 48 has a **predicate-based tail-handling code path** built into its `MainloopSm90TmaGmmaWarpSpecialized` mainloop: when the problem size is not an exact multiple of the CTA tile (`Shape<_128, _128, _32>` here), the boundary CTA tiles issue predicated loads that mask out elements past the problem boundary, so the kernel produces correct output without the user having to pad the tensors.
-
-What the kernel does NOT do is silently extend itself to handle every conceivable shape. Specifically, when the problem is smaller than the cluster's effective M-N footprint, `gemm.can_implement(arguments)` returns `kErrorInvalidProblem` and the kernel refuses to launch. The tail strategy is therefore **"predicate at the boundary tile + reject sub-tile problems"**, not "extend to arbitrary shape".
-
-## When to use it
-
-- GEMMs where the problem dimensions are reasonably close to the CTA tile size (≥ tile-M × tile-N elements per dim) but not necessarily exact multiples. The cooperative kernel's cost-of-tail is small as long as the boundary CTAs are a small fraction of the total grid.
-- LLM attention-projection layers where MNK are between several hundred and several thousand elements with non-power-of-two dimensions; this is the empirical sweet spot.
-
-## When NOT to use it
-
-- Problem sizes smaller than ~128×128 (sub-CtaTile in M and N) — the kernel will reject. Switch to a smaller CTA tile (e.g. `<64, 64, 32>` + the non-cooperative scheduler) or grouped GEMM.
-- Problem sizes where most of the grid is boundary tiles (e.g. shapes just above 128×128 — the entire grid is the tail path; throughput is launch-bound rather than compute-bound).
-
-## Measured Characteristics
-
-The cooperative kernel's behavior at three non-aligned categories, measured on H200-SXM at TF32 inputs / F32 accumulator, vs. the aligned baseline at similar problem sizes:
-
-The skill's primary hardware-probe evidence comes from the wgmma + TMA primitives the cooperative kernel composes. See:
-
-- TMA primitive (cutlass-API path): sources/experience/api-probes/gemm.md. Cutlass-free isolated TMA bandwidth: sources/experience/hw-probes/tma-ptx.md.
-- wgmma atom (cutlass-API path): sources/experience/api-probes/gemm.md. Cutlass-free isolated wgmma family (N-shape × dtype × layout × A-source): sources/experience/hw-probes/wgmma-ptx.md.
-- wgmma atom-shape sweep: sources/experience/api-probes/gemm.md.
-
-The non-aligned-shape-specific measurements live in the api-probe at sources/experience/api-probes/gemm.md:
-
-| Shape (MNK) | Category | Kernel template | cutlass result | cutlass μs | cutlass GFLOPS | cutlass-vs-cuBLAS direct diff |
-|---|---|---|---|---|---|---|
-| 80 × 80 × 80 | far smaller than tile (genuinely non-aligned in all 3 dims on small-tile kernel: 80 = 1.25 × CtaTile.M=64, 80 = 2.5 × CtaTile.K=32) | TileShape `<64, 64, 32>` + Cluster `<1, 1, 1>` (smaller-tile non-cooperative) | Passed | 5.52 | 185 | **max_abs=0, max_rel=0, 0 mismatches** (bit-identical) |
-| 200 × 200 × 200 | tile-misaligned (between 1 and 2 CtaTiles of 128) | TileShape `<128, 128, 32>` + Cluster `<4, 2, 1>` (cooperative) | Passed | 8.8 | 1,820 | **max_abs=0, max_rel=0, 0 mismatches** (bit-identical) |
-| 1440 × 1440 × 1440 | far larger with non-aligned tail | same cooperative template | Passed | 45.8 | 130,260 | **max_abs=0, max_rel=0, 0 mismatches** (bit-identical) |
-
-A/B comparison: the predicate-tail strategy is compiled unconditionally into `MainloopSm90TmaGmmaWarpSpecialized`; there is no runtime flag. A literal **same-shape on/off** measurement is **structurally infeasible** here: a kernel template that does NOT compile in tail handling cannot correctly run a non-aligned shape (it either rejects via `can_implement` or computes wrong output past the boundary). The closest practical measurement is **the same kernel binary at two adjacent shapes** — one where the predicates fire (boundary CTA tile present) and one where the predicates are compiled-in but never mask anything out (every CTA tile is full). This is recorded below as a proxy, not a closure-grade isolation of the boundary mechanism — see the report's confounders section.
-
-| Configuration | Shape | Predicate-tail active? | TFLOPS | Latency | Boundary-strategy cost |
-|---|---|---|---|---|---|
-| With boundary strategy active | 1440 × 1440 × 1440 | Yes (32-elt tail per dim, cluster non-aligned) | 130.2 | 45.86 μs | — |
-| Without boundary strategy active | 1536 × 1536 × 1536 | No (every CTA tile full, cluster aligned) | 149.4 | 48.51 μs | **12.85% throughput drop** when the predicate-tail path activates |
-
-Both runs use the same `gemm_compare` binary (same kernel template, same compile-time predicate logic). Both are bit-identical to cuBLAS (`max_abs=0, max_rel=0`). 1536³ is the smallest fully-tile-and-cluster-aligned shape ≥ 1440³ on this kernel; **the throughput delta is therefore an adjacent-shape proxy with documented confounders (cluster-multicast alignment delta, total-work delta, wave-quantization), not a clean isolation of the boundary mechanism**. The skill's overall `status: partial` reflects this — the three shape categories are correctness-verified, but the strategy A/B is a documented proxy.
-
-Other useful (but less tightly controlled) comparisons:
-
-| Shape | Aligned reference (different scale) | Aligned TFLOPS | Non-aligned TFLOPS | Note |
-|---|---|---|---|---|
-| 80³ (small-tile fallback) | n/a — different kernel template | n/a | 0.185 | Launch-bound (4-CTA grid). The predicate-tail path is active in M, N, and K; cost cannot be cleanly separated from per-launch overhead at this scale. |
-| 200³ | 512³ (cooperative aligned anchor) | 21.7 | 1.85 | Mostly absolute-size effect (launch-bound across scales), not isolated tail cost. |
-| 1440³ | 2048³ aligned | 188.7 | 130.2 | 31% gap — confounds scale + tail. The 1440-vs-1536 A/B above is the cleaner isolation. |
-| 30³ | smaller than supported domain | n/a | n/a | "Boundary strategy" at this scale is `kErrorInvalidProblem`; both the cooperative and small-tile templates refuse M < 64. |
-
-## Cross-references
-
-- Aligned baseline: `wiki/nvidia/foundations/compute/gemm.md`
-- Library-usage notes + tuning log: `wiki/nvidia/code-walkthroughs/cutlass-cute/gemm-tail/{README.md, tuning.md}`. Canonical buildable artifact at `artifacts/experience/api-probes/gemm/{gemm_tail.cu, gemm_tail_small.cu, helper.h, build_tail.sh, run_tail.sh}`.
-- Probe record: `sources/experience/api-probes/gemm.md`
-- Failure modes: `wiki/nvidia/foundations/compute/gemm/non-aligned-tail/pitfalls.md`
-- Tuning parameter space: tuning.md.

package/resources/kop-2026-10-23-0.1.17-beta.1/product_capabilities/kernel_optflow/skills/KernelWiki-private/wiki/nvidia/foundations/compute/half-precision-math/apis.md

@@ -1,247 +0,0 @@
----
-title: Half-Precision Math APIs
-status: draft
-source:
-- path: spec
-  anchor: Reference
-apis:
-- func_name: __hadd
-  namespace: cuda-runtime
-  kind: fp16-arith-scalar
-  signature: __half __hadd(__half a, __half b);
-  notes: Scalar fp16 add. Emits add.f16. Same throughput as fp32 on sm_9.0a scalar path (45 TFLOPS measured).
-- func_name: __hadd2
-  namespace: cuda-runtime
-  kind: fp16-arith-packed
-  signature: __half2 __hadd2(__half2 a, __half2 b);
-  notes: Packed fp16 add (2 lanes). Emits add.f16x2. Measured 1.16x scalar __hadd throughput on H200, not 2x (see probe).
-- func_name: __hmul
-  namespace: cuda-runtime
-  kind: fp16-arith-scalar
-  signature: __half __hmul(__half a, __half b);
-  notes: Scalar fp16 multiply. Emits mul.f16.
-- func_name: __hmul2
-  namespace: cuda-runtime
-  kind: fp16-arith-packed
-  signature: __half2 __hmul2(__half2 a, __half2 b);
-  notes: Packed fp16 multiply. Emits mul.f16x2.
-- func_name: __hfma
-  namespace: cuda-runtime
-  kind: fp16-arith-scalar
-  signature: __half __hfma(__half a, __half b, __half c);
-  notes: 'Scalar fp16 fused multiply-add (a*b + c). Emits fma.rn.f16. Measured on H200: 45351 GFLOPS (scalar op count), 1.58x scalar fp32 FMA.'
-- func_name: __hfma2
-  namespace: cuda-runtime
-  kind: fp16-arith-packed
-  signature: __half2 __hfma2(__half2 a, __half2 b, __half2 c);
-  notes: 'Packed fp16 FMA (2 lanes). Emits fma.rn.f16x2. Measured on H200: 52608 GFLOPS (scalar op count), 1.16x scalar __hfma — the residual after nvcc''s auto-packing of scalar chains into HFMA2.MMA.'
-- func_name: __hfma_relu
-  namespace: cuda-runtime
-  kind: fp16-fused-activation
-  signature: __half __hfma_relu(__half a, __half b, __half c);
-  notes: Scalar fp16 max(a*b + c, 0). Emits fma.rn.relu.f16. ~4% instruction reduction over explicit max; wall-clock benefit only in compute-bound kernels (see pitfall P11).
-- func_name: __hfma2_relu
-  namespace: cuda-runtime
-  kind: fp16-fused-activation-packed
-  signature: __half2 __hfma2_relu(__half2 a, __half2 b, __half2 c);
-  notes: Packed fp16 max(a*b + c, 0). Emits fma.rn.relu.f16x2.
-- func_name: __halves2half2
-  namespace: cuda-runtime
-  kind: fp16-pack
-  signature: __half2 __halves2half2(__half lo, __half hi);
-  notes: Build a half2 from two existing halves. Zero-cost on most paths (just register alias).
-- func_name: __floats2half2_rn
-  namespace: cuda-runtime
-  kind: fp16-pack-from-float
-  signature: __half2 __floats2half2_rn(float lo, float hi);
-  notes: Build a half2 from two fp32 values with round-to-nearest-even. One cvt.rn.f16.f32 per lane, then packed.
-- func_name: __float2half_rn
-  namespace: cuda-runtime
-  kind: fp16-cast
-  signature: __half __float2half_rn(float x);
-  notes: fp32 -> fp16 round-to-nearest-even. Emits cvt.rn.f16.f32.
-- func_name: __half2float
-  namespace: cuda-runtime
-  kind: fp16-cast
-  signature: float __half2float(__half x);
-  notes: fp16 -> fp32 widening. Emits cvt.f32.f16. No rounding needed (exact).
-- func_name: hexp
-  namespace: cuda-runtime
-  kind: fp16-transcendental
-  signature: __half hexp(__half x);
-  notes: Scalar fp16 exp. May decompose into fp32 ops on some arches (see pitfall P10); sm_9.0a coverage not re-measured by this probe.
-- func_name: h2exp
-  namespace: cuda-runtime
-  kind: fp16-transcendental-packed
-  signature: __half2 h2exp(__half2 x);
-  notes: Packed fp16 exp. Expected to map to dedicated ex2.approx.f16x2 but not re-measured.
-- func_name: hlog
-  namespace: cuda-runtime
-  kind: fp16-transcendental
-  signature: __half hlog(__half x);
-  notes: Scalar fp16 log. Emits lg2.approx + scale.
-- func_name: h2log
-  namespace: cuda-runtime
-  kind: fp16-transcendental-packed
-  signature: __half2 h2log(__half2 x);
-- func_name: hrsqrt
-  namespace: cuda-runtime
-  kind: fp16-transcendental
-  signature: __half hrsqrt(__half x);
-  notes: Scalar fp16 reciprocal sqrt. Emits rsqrt.approx.f16.
-- func_name: h2rsqrt
-  namespace: cuda-runtime
-  kind: fp16-transcendental-packed
-  signature: __half2 h2rsqrt(__half2 x);
-- func_name: __hadd
-  namespace: cuda-runtime
-  kind: bf16-arith-scalar
-  signature: __nv_bfloat16 __hadd(__nv_bfloat16 a, __nv_bfloat16 b);
-  notes: Overloaded for bf16 on sm_80+. Emits add.bf16. Same scalar throughput as fp16 (45 TFLOPS measured on H200).
-- func_name: __hfma
-  namespace: cuda-runtime
-  kind: bf16-arith-scalar
-  signature: __nv_bfloat16 __hfma(__nv_bfloat16 a, __nv_bfloat16 b, __nv_bfloat16 c);
-  notes: Overloaded for bf16. Emits fma.rn.bf16.
-- func_name: __hfma2
-  namespace: cuda-runtime
-  kind: bf16-arith-packed
-  signature: __nv_bfloat162 __hfma2(__nv_bfloat162 a, __nv_bfloat162 b, __nv_bfloat162 c);
-  notes: 'Overloaded packed bf16 FMA. Emits fma.rn.bf16x2. Measured on H200: 46478 GFLOPS — **12% slower** than fp16 packed (52608 GFLOPS); only **1.02x** scalar bf16 (the compiler already auto-packs scalar bf16 into HFMA2.MMA.BF16_V2, so explicit packing adds essentially nothing for bf16).'
-- func_name: __float2bfloat16_rn
-  namespace: cuda-runtime
-  kind: bf16-cast
-  signature: __nv_bfloat16 __float2bfloat16_rn(float x);
-  notes: fp32 -> bf16 round-to-nearest-even. Emits cvt.rn.bf16.f32.
-- func_name: __bfloat162float
-  namespace: cuda-runtime
-  kind: bf16-cast
-  signature: float __bfloat162float(__nv_bfloat16 x);
-  notes: bf16 -> fp32 widening. Emits cvt.f32.bf16.
-- func_name: __floats2bfloat162_rn
-  namespace: cuda-runtime
-  kind: bf16-pack-from-float
-  signature: __nv_bfloat162 __floats2bfloat162_rn(float lo, float hi);
-- func_name: add.f16
-  namespace: ptx
-  kind: ptx-fp16-add-scalar
-- func_name: add.f16x2
-  namespace: ptx
-  kind: ptx-fp16-add-packed
-  notes: 2-way SIMD fp16 add. Throughput on sm_9.0a measured at 1.16x scalar add.f16.
-- func_name: fma.rn.f16
-  namespace: ptx
-  kind: ptx-fp16-fma-scalar
-- func_name: fma.rn.f16x2
-  namespace: ptx
-  kind: ptx-fp16-fma-packed
-  notes: Emitted by __hfma2. Measured 52.6 TFLOPS on H200 (scalar op count).
-- func_name: fma.rn.relu.f16
-  namespace: ptx
-  kind: ptx-fp16-fma-relu
-  notes: Fused FMA + ReLU. Single instruction; max(a*b + c, 0).
-- func_name: fma.rn.relu.f16x2
-  namespace: ptx
-  kind: ptx-fp16-fma-relu-packed
-- func_name: fma.rn.bf16
-  namespace: ptx
-  kind: ptx-bf16-fma-scalar
-- func_name: fma.rn.bf16x2
-  namespace: ptx
-  kind: ptx-bf16-fma-packed
-  notes: Emitted by __hfma2 on __nv_bfloat162. Lowers to SASS HFMA2.MMA.BF16_V2 (audit 2026-04-23) — distinct opcode from fp16's HFMA2.MMA, stays within the half-precision family (NOT a FFMA fallback). Measured 46.5 TFLOPS on H200 — 12% below fma.rn.f16x2.
-- func_name: tanh.approx.f16
-  namespace: ptx
-  kind: ptx-fp16-tanh
-  notes: Single-instruction fp16 tanh approximation.
-- func_name: tanh.approx.bf16
-  namespace: ptx
-  kind: ptx-bf16-tanh
-- func_name: cvt.rn.f16.f32
-  namespace: ptx
-  kind: ptx-cvt-fp32-to-fp16
-- func_name: cvt.f32.f16
-  namespace: ptx
-  kind: ptx-cvt-fp16-to-fp32
-  notes: fp16 -> fp32 widening. Exact; no rounding mode needed.
-- func_name: cvt.rn.bf16.f32
-  namespace: ptx
-  kind: ptx-cvt-fp32-to-bf16
-- func_name: cvt.f32.bf16
-  namespace: ptx
-  kind: ptx-cvt-bf16-to-fp32
-- func_name: atom.add.noftz.f16
-  namespace: ptx
-  kind: ptx-fp16-atomic-add
-  notes: Native fp16 atomicAdd. `.noftz` preserves denormals. Contention throughput is worse than fp32 atomicAdd (see pitfall P12); prefer hierarchical fp32 fan-in via the atomic-reduction skill.
-- func_name: atom.add.noftz.bf16
-  namespace: ptx
-  kind: ptx-bf16-atomic-add
-  notes: Native bf16 atomicAdd (sm_80+).
-id: api-half-precision-math-ref
-type: api-definition
-vendor: nvidia
-func_name: Half-Precision Math 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: L25350-L25420
-- source_id: cuda-official/toolkit-docs-13.2
-  path: CUDA Programming Guides/parallel-thread-execution/cuda_parallel-thread-execution_index.html.md
-  anchor: L11000-L11200
-architectures:
-- sm90
-- sm90a
-languages:
-- ptx
-- cuda-cpp
-techniques:
-- vectorized-loads
-- kernel-fusion
-kernel_types:
-- gemm
-- fused-kernel
-confidence: inferred
-evidence_level: inferred
-tags:
-- vectorized-loads
-- kernel-fusion
-- gemm
-- fused-kernel
-- ptx
-- cuda-cpp
----
-## Scalar FMA throughput table (H200 sm_9.0a, measured)
-
-| intrinsic   | PTX emit          | SASS emit             | scalar GFLOPS | vs fp32 |
-|-------------|-------------------|-----------------------|--------------:|--------:|
-| `fmaf`      | `fma.rn.f32`      | `FFMA`                |         28633 |   1.00× |
-| `__hfma`    | `fma.rn.f16`      | `HFMA2.MMA` (auto-packed by nvcc) |  45351 | **1.58×** |
-| `__hfma2`   | `fma.rn.f16x2`    | `HFMA2.MMA`           |         52608 | **1.84×** |
-| `__hfma` (bf16) | `fma.rn.bf16` | `HFMA2.MMA.BF16_V2`   |         45381 |   1.59× |
-| `__hfma2` (bf16)| `fma.rn.bf16x2` | `HFMA2.MMA.BF16_V2` | 46478 |   1.62× |
-
-Compute SOL (fp32 variant) = 78% at 4-chain ILP × 2048 FMAs/chain.
-
-## Precision quick table (for caller annotation)
-
-| format | exp | mantissa | max finite | min normal | eps at 1.0 | accum safe? |
-|--------|----:|---------:|-----------:|-----------:|-----------:|:-----------:|
-| fp32   |   8 |       23 |    3.4e38 |   1.18e-38 |   1.19e-7  |     yes     |
-| fp16   |   5 |       10 |    6.55e4 |   6.10e-5  |   4.88e-4  |     **no**  |
-| bf16   |   8 |        7 |    3.4e38 |   1.18e-38 |   7.81e-3  |     **no**  |
-
-## Cross-references
-
-- **`fast-math` skill**: `-use_fast_math` only affects fp32 paths; it does NOT change fp16/bf16 code generation.
-- **`vectorized-access` skill**: `__half2` packs naturally to 4-byte aligned loads; use vectorized-access to widen LDS/STS instructions.
-- **`ilp` skill**: the half2-throughput probe 4-chain FMA harness is the same pattern as the ILP skill's throughput methodology.
-- **`register-pressure` skill**: `__half2` doubles accumulator width; a compute-bound kernel adopting §S2 must verify regs-per-thread.
-- **`atomic-reduction` skill**: hierarchical fp32 fan-in + cast-to-fp16 at the final store is preferred over native fp16 `atomicAdd` under contention (skill §S6 + pitfall P12).
-
-## Related Probes
-
-- sources/experience/hw-probes/half2-throughput.md — 5-variant FMA throughput sweep. Load-bearing results: __hfma2 = 1.16× __hfma (not 2×); bf16-packed = 0.88× fp16-packed (not equal).

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

@@ -1,160 +0,0 @@
----
-title: Half-Precision Math — Pitfalls
-status: verified
-related_skill: wiki/nvidia/foundations/compute/half-precision-math/skill.md
-source:
-- path: spec
-  anchor: Reference
-experience_refs:
-- sources/experience/hw-probes/half2-throughput.md
-id: pitfall-half-precision-math
-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: L25350-L25420
-- source_id: cuda-official/toolkit-docs-13.2
-  path: CUDA Programming Guides/parallel-thread-execution/cuda_parallel-thread-execution_index.html.md
-  anchor: L11000-L11200
-architectures:
-- sm90
-- sm90a
-languages:
-- ptx
-- cuda-cpp
-techniques:
-- pipeline-stages
-- vectorized-loads
-- kernel-fusion
-- shared-memory-optimization
-- software-exp
-kernel_types:
-- gemm
-- fused-kernel
-confidence: inferred
-evidence_level: inferred
-tags:
-- pipeline-stages
-- vectorized-loads
-- kernel-fusion
-- shared-memory-optimization
-- software-exp
-- gemm
-- fused-kernel
-- ptx
-- cuda-cpp
----
-Pitfalls group: P1–P6 are numerical-format and availability facts grounded in PG §5.5.2 / PTX ISA; P13 is a build-system fact; P14–P16 are measured on H200 sm_9.0a by the half2-throughput probe 2026-04-23. P10/P11/P12 are open risks not re-measured by the probe — each records what to look for in SASS / wall-clock and flags a follow-up probe.
-
-## P1. FP16 overflow in accumulation
-
-**Symptom**: NaN or Inf in reduction / dot-product outputs using fp16 accumulation.
-**Detection**: Output contains NaN/Inf even when inputs are bounded. fp16 max is ~**65504**; any sum of ~1000 terms of magnitude ~100 exceeds it.
-**Fix**: Always accumulate in FP32. Convert fp16 inputs via `__half2float` before summation, cast back with `__float2half_rn` at the final store. Skill §S3 is the canonical pattern.
-**Numerical grounding**: fp16 mantissa ULP at 1.0 is 4.88e-4; summing 1000 terms of magnitude 1.0 accumulates rounding error ~0.5 per unit of sum, hitting 1 ULP at sum ≈ 2000. **Do not use fp16 for reductions.**
-**Source**: PG §5.5.2; skill §Precision.
-
-## P2. BF16 precision loss in computation
-
-**Symptom**: BF16 computations show larger relative errors than fp16 for the same operation despite equivalent dynamic range.
-**Detection**: Numerical comparison shows ~**7-bit mantissa** precision for bf16 vs ~**10-bit** for fp16 (16× coarser eps).
-**Fix**: Understand bf16's mantissa limit. Use it for storage (weights, activations) where range matters more than precision; **not** for full-precision arithmetic chains. Promote to fp32 for accumulation (skill §S3).
-**Measured on H200 sm_9.0a**: bf16 scalar FMA throughput equals fp16 scalar (both ~45 TFLOPS), so the choice of bf16 vs fp16 is precision/range-driven, not throughput-driven — see skill §Precision table.
-**Source**: PG §5.5.2; half2-throughput probe 2026-04-23.
-
-## P3. Mixing `__half` and `__half2` alignment
-
-**Symptom**: Misaligned memory-access errors or performance degradation when switching between scalar `__half` and packed `__half2` access patterns.
-**Detection**: NCU reports uncoalesced access or unaligned load warnings; wall-clock regresses after packing.
-**Fix**: When using `__half2`, ensure the base pointer is **4-byte aligned** (natural alignment for 2× 16-bit). Use `reinterpret_cast<__half2*>` only on properly aligned pointers. Pad arrays to even lengths so tail elements don't require scalar fixup.
-**Source**: PTX `ld.global` alignment requirements (PTX ISA §8.5); storage-format property not H200-specific.
-
-## P4. FP16 denormal handling differs from FP32
-
-**Symptom**: Very small fp16 values (below ~6.1e-5, the min-normal threshold) behave differently than expected — especially with `-ftz=true` (flush-to-zero) compiler option.
-**Detection**: Results differ between GPU and CPU reference for near-zero values; normalisation kernels with eps < 6e-5 produce unexpected zeros.
-**Fix**: Know that fp16 has a **larger denormal range relative to its precision** than fp32. With `-ftz=true`, denormals flush to zero. PTX `.noftz` variants (e.g. `atom.add.noftz.f16`) preserve denormals through that specific instruction. Verify your epsilons: for fp16 use eps ≥ 1e-4; for bf16 the min-normal is fp32-level so not a concern.
-**Source**: PTX ISA `atom.add.noftz.f16`; skill §Precision.
-
-## P5. Implicit type-conversion overhead
-
-**Symptom**: Kernel is slower than expected because the compiler inserts many `cvt` instructions between fp16 and fp32.
-**Detection**: SASS dump shows excessive `F2F` (float-to-float conversion) instructions; NCU reports high instruction count relative to arithmetic intensity.
-**Fix**: Minimise conversions by keeping data in fp16/bf16 through the computation pipeline. Use packed `half2` / `bfloat162` operations where helpful. Convert to fp32 **only** at the accumulation boundary. Consider mixed-precision FMA (`fma.rn.f32.f16` available via some intrinsics) when the hardware supports it.
-**Measured on H200 sm_9.0a (indirect)**: the half2-throughput probe scalar fp16 variant runs at 45.4 TFLOPS — if implicit conversions dominated, we would see scalar fp16 closer to scalar fp32 (28.6 TFLOPS). Absence of that collapse is weak evidence that the compiler is not conversion-bound in a pure FMA chain. In mixed workloads the risk remains.
-**Source**: PG §5.5.2; half2-throughput probe 2026-04-23.
-
-## P6. BF16 is sm_80+ only
-
-**Symptom**: Compilation error or runtime failure when using `__nv_bfloat16` operations on sm_70 / sm_75.
-**Detection**: Compile error or `CUDA_ERROR_INVALID_SOURCE` at runtime.
-**Fix**: Guard bf16 code with `#if __CUDA_ARCH__ >= 800`. Fall back to fp16 for older architectures. BF16 native arithmetic requires Compute Capability 8.0+.
-**Measured on H200 sm_9.0a**: all bf16 intrinsics tested (`__hadd`, `__hfma`, `__hfma2`, `__float2bfloat16_rn`, `__floats2bfloat162_rn`) compile and execute correctly — consistent with sm_9.0a ⊇ sm_8.0. The "not available on sm_70/75" side is a documented constraint inherited from the PTX ISA.
-**Source**: PG §5.5.2; half2-throughput probe 2026-04-23.
-
-## P10. `h2exp` may decompose into fp32 on some architectures
-
-**Symptom**: `h2exp` does not map to a single native instruction; it decomposes into a multi-step fp32 approximation that increases instruction count rather than reducing it.
-**Detection**: Inspect SASS; expect a single `ex2.approx.f16x2` but may see `ex2.approx.f32` + conversions.
-**Fix**: Verify per architecture. If the decomposition happens on your target, either do the exp in fp32 explicitly (saves the wrapper overhead) or use `__expf` + cast at the boundary.
-**Status**: Not re-measured on H200 sm_9.0a. Follow-up probe `sources/experience/hw-probes/half-transcendental/` (open).
-**Source**: PG §5.4.11.2 (documents the packed intrinsics but does not guarantee single-instruction lowering on all SMs).
-
-## P11. `__hfma2_relu` benefit invisible in memory-bound kernels
-
-**Symptom**: Switching to `__hfma2_relu` reduces instruction count by ~4% but produces no measurable wall-clock speedup.
-**Detection**: Compare wall-clock of (FMA then max) vs `__hfma2_relu` variants on your actual kernel, not a microbench.
-**Fix**: Use `__hfma2_relu` only when the kernel is compute-bound (skill §S5). In the memory-bound regime the activation epilogue is a tiny fraction of wall-clock; code complexity not worth the 4% instruction saving.
-**Status**: Not re-measured on H200 sm_9.0a. Follow-up probe `sources/experience/hw-probes/half-fma-relu/` (open).
-**General principle**: instruction-count reduction ≠ wall-clock speedup; always measure end-to-end before committing to a fused intrinsic.
-
-## P12. Native fp16 atomicAdd has worse contention than fp32
-
-**Symptom**: `atomicAdd(__half*, __half)` on a contended destination has lower effective throughput than `atomicAdd(float*, float)` on the same address.
-**Detection**: Compare the contended-atomic throughput of fp16 vs fp32 destinations under the same launch shape.
-**Fix**: Use the hierarchical fan-in pattern from `atomic-reduction` skill — accumulate per-block in shared memory in fp32, then atomicAdd a **single fp32 partial per block** into the global reducer. Cast to fp16/bf16 only at the final store.
-**Status**: Not re-measured on H200 sm_9.0a. Follow-up probe (open).
-**Source**: Documented architectural constraint that native half-precision atomics share a lower-throughput atomic pipe vs fp32; exact H200 ratio unmeasured by the half2-throughput probe.
-
-## P13. the external framework extension build disables half operators
-
-**Symptom**: Compile errors like `no operator ">" matches these operands` or `no suitable constructor from "float" to "__half"` when using `__half` in CUDA kernels built via `framework extension build`.
-**Root cause**: Framework extension build adds
-- `-D__CUDA_NO_HALF_OPERATORS__` — disables `__half + __half`, `__half > __half`, etc.
-- `-D__CUDA_NO_HALF_CONVERSIONS__` — disables implicit `float` → `__half`.
-- `-D__CUDA_NO_HALF2_OPERATORS__` — disables `__half2` arithmetic operators.
-**Fix**: Use explicit function calls instead of operators:
-
-```cpp
-// Not: a > b, a + b, __half h = 3.14f;
-// Use:
-bool cond = __hgt(a, b);
-__half s = __hadd(a, b);
-__half h = __float2half_rn(3.14f);
-```
-
-For `__half2` use `__hadd2`, `__hmul2`, `__hfma2`. Always `#include <cuda_fp16.h>`. Do **not** use `__half` types in `.cpp` files — keep them strictly in `.cu` sources compiled by nvcc.
-**Source**: Framework extension build build flags (external framework constraint, not H200-specific).
-
-## P14. `__hfma2` is 1.16× scalar `__hfma` on H200, not 2× (measured)
-
-**Symptom (measured on H200 sm_9.0a, 2026-04-23)**: Packed `__hfma2` runs at **52608 GFLOPS** (scalar op count), only **1.16×** the scalar `__hfma` rate of 45351 GFLOPS. Documentation and folklore often imply a 2× advantage from packing.
-**Cause (SASS-confirmed 2026-04-23)**: `cuobjdump --dump-sass` on the probe binary shows BOTH `fma_bench_fp16_scalar` AND `fma_bench_fp16_packed` emit the SAME `HFMA2.MMA` SASS opcode. nvcc auto-packs the 4 independent scalar `__hfma` chains into `HFMA2.MMA` instructions at codegen time, so "scalar vs packed" at C-source is largely erased at the hardware opcode level. The residual 1.16× is register-layout / alignment overhead on the explicit-packed path, not the packing gain itself. **The scalar fp16's 1.58× vs fp32 is itself the packing gain** — just made invisible by the compiler.
-**Fix**: Do not promise 2× throughput from packing to downstream callers. The real multiplier over scalar fp32 is **1.84×**, and most of that (1.58×) comes from just switching fp32 → fp16, with packing as a secondary 16% gain. In memory-bound kernels, skip packing entirely — the win is not measurable.
-**Source**: half2-throughput probe 2026-04-23.
-
-## P15. BF16 packed is 12% slower than FP16 packed on H200 (measured)
-
-**Symptom (measured on H200 sm_9.0a, 2026-04-23)**: `__hfma2` on `__nv_bfloat162` runs at **46478 GFLOPS**, **12% slower** than the same intrinsic on `__half2` at **52608 GFLOPS**. Scalar bf16 and scalar fp16 match at 45 TFLOPS; the divergence is only on the packed path.
-**Cause (SASS-confirmed 2026-04-23)**: `fma.rn.bf16x2` lowers to `HFMA2.MMA.BF16_V2` SASS, a distinct opcode from fp16 packed's `HFMA2.MMA`. Both stay within the half-precision HFMA2 family — not a fall-through to `FFMA`. The BF16_V2 variant simply has lower throughput than the base HFMA2.MMA on sm_9.0a hardware; root cause (pipeline width, multiplier latency, register port allocation) requires an isolated-instruction microbench to resolve and is out of scope here.
-**Fix**: Prefer fp16 packed when the workload's dynamic range fits fp16 (values in [6e-5, 6.5e4]). If range forces bf16 — training, un-normalised activations, deep transformers — accept the 12% cost as the price of the wider dynamic range.
-**Source**: half2-throughput probe 2026-04-23.
-
-## P16. `__hfma` / `__hfma2` overloads must come from `<cuda_bf16.h>` for bf16 (methodology)
-
-**Symptom**: Using `__hfma(a, b, c)` where `a, b, c` are `__nv_bfloat16` without `#include <cuda_bf16.h>` triggers ambiguous overload or cast-to-fp16 at compile time. Runtime result is either zero or garbage (values silently truncated through fp16).
-**Detection**: Compile warning "implicit conversion from __nv_bfloat16 to __half"; measured kernel produces wrong numerics at ~1e-4 scale.
-**Fix**: Always `#include <cuda_bf16.h>` alongside `<cuda_fp16.h>` when the kernel uses both types. The bf16 header defines overloads of `__hfma`, `__hadd`, `__hmul` for the bf16 argument types.
-**Discovered while writing the half2-throughput probe harness**: the probe's bf16 variants would have silently converted to fp16 without the header guard — the bf16-packed 46 TFLOPS result depends on the correct overload resolution.
-**Source**: half2-throughput probe 2026-04-23 methodology note.