technillogue/ptx-isa-markdown

Overview

This skill provides practical guidance for CUDA kernel development, debugging, and performance optimization tailored for Claude Code users. It focuses on concrete, repeatable workflows: reproduce minimal failures, use printf and compute-sanitizer for bugs, and follow a profile→hypothesize→change→verify loop for performance. It documents non-interactive debugging (cuda-gdb), binary inspection (cuobjdump), timeline profiling (nsys), and kernel analysis (ncu).

How this skill works

The skill inspects and prescribes step-by-step actions: isolate failing kernels, add guarded device printf statements, run compute-sanitizer tools for memory/race/init checks, and obtain backtraces with cuda-gdb in batch mode. For performance it directs you to establish a baseline, use nsys to find hot regions, then drill into specific kernels with ncu and NVTX instrumentation. It also includes compilation flags, PTX/assembly inspection, and guided interpretation of common metric patterns.

When to use it

• Writing or debugging CUDA kernels that crash, miscompute, or behave nondeterministically
• Profiling GPU workloads to find where time is spent (CPU/GPU interactions, transfers, kernel gaps)
• Deep-diving into a slow kernel to identify memory/compute/occupancy bottlenecks
• Inspecting compiled binaries or PTX with cuobjdump for register, instruction or resource info
• Instrumenting code with NVTX to correlate custom regions with timeline profiles

Best practices

• Measure before guessing: always profile before changing performance-critical code
• Make small, isolated changes and verify each change with a profile or test
• Use guarded device printf to trace execution when debuggers don’t help
• Compile debug builds with -g -G -lineinfo and production builds with -O3 -lineinfo for profiling
• Profile at realistic problem sizes; scale-dependent optimizations can reverse performance gains

Example use cases

• Fix a kernel that corrupts memory: reproduce minimally, run compute-sanitizer memcheck, add guarded printf to localize the fault
• Reduce end-to-end runtime: nsys to find GPU idle gaps, then fuse small kernels or batch transfers
• Recover a crashed run: cuda-gdb -batch -ex 'run' -ex 'bt' to gather a backtrace non-interactively
• Investigate a slow kernel: ncu --set memory or roofline to identify uncoalesced accesses or register pressure
• Inspect generated PTX/SASS with cuobjdump to confirm use of desired instructions or resource usage