From e5ba31a5e1af823b900e5204cb7bedb8f4e425c5 Mon Sep 17 00:00:00 2001
From: Helen Kwok <107752876+helenkwok@users.noreply.github.com>
Date: Thu, 17 Sep 2026 21:54:51 +0930
Subject: [PATCH] docs(guide): warn that the default NvvmArch fails silently on
 pre-Turing GPUs

CudaBuilder defaults to NvvmArch::Compute75, chosen for CUDA 13
compatibility. Following the getting-started example as-is on any
older GPU (Maxwell/Pascal/Volta) produces PTX that fails to load at
runtime with a bare InvalidPtx error, with nothing pointing at the
architecture mismatch. Add a note pointing readers at .arch(...) and
nvidia-smi's compute_cap query.

Hit this firsthand on a GTX 1070 (sm_61); see #410 for the runtime
diagnostics side of this.
---
 guide/src/guide/getting_started.md | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/guide/src/guide/getting_started.md b/guide/src/guide/getting_started.md
index c5d792c8..f643aa5a 100644
--- a/guide/src/guide/getting_started.md
+++ b/guide/src/guide/getting_started.md
@@ -198,6 +198,13 @@ The compile target determines which GPU features are available. See the [Compute
 Gating](./compute_capabilities.md) guide for details on writing code that adapts to different GPU
 capabilities.
 
+> **Note:** `CudaBuilder`'s default target is `NvvmArch::Compute75` (Turing and later). If your
+> GPU is older than Turing (Maxwell, Pascal, or Volta — e.g. a GTX 10-series card), the PTX
+> produced by the default will fail to load at runtime with a generic `InvalidPtx` error and no
+> indication that the architecture is the problem. Set `.arch(...)` explicitly to match your GPU,
+> e.g. `.arch(cuda_builder::NvvmArch::Compute61)` for a GTX 1070. You can find your GPU's compute
+> capability with `nvidia-smi --query-gpu=compute_cap --format=csv`.
+
 ### `src/main.rs`
 
 The final file contains `main`, which ties everything together.