Document downstream custom CUDA kernels with nvcc and NVRTC

[shinaoka]

Summary

Add a downstream-facing guide that documents how external crates can define and launch custom CUDA kernels against tenferro GPU tensors using the public GPU extension API.

The guide should cover both precompiled CUDA kernels (nvcc → PTX/CUBIN) and runtime compilation with NVRTC.

Related design: #1597 and docs/design/gpu-extension-api.md.

Motivation

The public extension API now has a clear design for direct CUDA interoperability, including PTX/CUBIN/NVRTC module loading, typed tensor/stream borrowing, and scoped execution through CudaExecSession / cuda::raw.

What is still missing is a concise cookbook for downstream users. In particular, it should be possible to understand how to write a CUDA kernel in an external crate without reading the internal implementation of tenferro-gpu or tenferro-linalg.

This will also be useful for advanced downstream integrations such as cuBLAS/cuSOLVER/cuSOLVERDx-based kernels.

Proposed guide

Add something like:

docs/guides/custom-cuda-kernels.md

with the following sections.

1. Precompiled kernel with nvcc

Show a minimal external-crate example:

kernel.cu
  -> nvcc
  -> PTX or CUBIN
  -> tenferro `cuda::raw::Module`
  -> function lookup
  -> launch on the tenferro-owned CUDA stream

Document a practical build.rs setup or equivalent build step.

2. Runtime compilation with NVRTC

Show how to:

CUDA source string
  -> NVRTC
  -> PTX
  -> module load
  -> function lookup
  -> launch

The example should use only public downstream APIs.

3. Borrowing tenferro tensors and stream

Demonstrate the intended scoped execution pattern, e.g. through with_cuda_exec_session and with_raw, including:

• immutable and mutable tensor arguments,
• compact-layout requirements,
• device pointer / span access,
• launch configuration,
• stream ordering,
• explicit synchronization when required by the caller.

4. Lifetime and safety contract

Document the important rules for raw kernels:

• kernel launches must use the stream owned by the active tenferro execution session,
• raw pointers / native stream handles must not escape the session scope,
• tensor and module resources must remain alive until asynchronous work is complete,
• no implicit device-wide synchronization,
• aliasing and initialization requirements for mutable/output arguments,
• behavior for non-contiguous tensors.

5. cuSOLVERDx / device-library note

Include a short advanced note showing the intended architecture for CUDA kernels that call device-side libraries such as cuSOLVERDx:

external CUDA kernel
  -> device-side cuSOLVERDx / cuBLASDx call
  -> NVRTC/nvcc compilation
  -> tenferro raw module loading
  -> launch on tenferro stream

A full cuSOLVERDx example is not required initially, but the guide should make clear that this is a supported downstream pattern.

Deliverables

• Add the downstream custom CUDA kernel guide.
• Add a minimal nvcc PTX/CUBIN example.
• Add a minimal NVRTC example.
• Ensure both examples use only public extension APIs.
• Compile-check the examples on GPU-less CI where possible.
• Run the PTX/NVRTC examples on CUDA hardware CI.
• Cross-link the guide from docs/guides/devices-and-gpu.md and the GPU extension API design document.

Non-goals

• Do not expose additional raw CUDA handles merely to simplify the tutorial.
• Do not bypass CudaExecSession / cuda::raw ownership and ordering rules.
• Do not make downstream crates depend on private tenferro-gpu implementation details.
• A production-quality cuSOLVERDx wrapper is out of scope for this documentation issue.