Basic Setup

using DotCompute.Backends.CUDA;
using Microsoft.Extensions.Logging;

var logger = LoggerFactory.Create(builder => builder.AddConsole())
    .CreateLogger<CudaAccelerator>();

var accelerator = new CudaAccelerator(logger);

// Check availability before initialization
if (await accelerator.IsAvailableAsync())
{
    await accelerator.InitializeAsync();
    // GPU is ready for compute operations
}

Service Registration

services.AddSingleton<IAccelerator, CudaAccelerator>();
// OR
services.AddCudaBackend(); // Includes automatic GPU detection

Kernel Compilation and Execution

var kernelDef = new KernelDefinition
{
    Name = "VectorAdd",
    Source = @"
        extern ""C"" __global__ 
        void vector_add(float* a, float* b, float* result, int n)
        {
            int idx = blockIdx.x * blockDim.x + threadIdx.x;
            if (idx < n) {
                result[idx] = a[idx] + b[idx];
            }
        }
    ",
    EntryPoint = "vector_add"
};

var compiledKernel = await accelerator.CompileKernelAsync(kernelDef);

// Execute with launch parameters
var launchParams = new KernelLaunchParameters
{
    GridDim = new Dim3((uint)((length + 255) / 256), 1, 1),
    BlockDim = new Dim3(256, 1, 1),
    SharedMemorySize = 0
};

await compiledKernel.ExecuteAsync(parameters, launchParams);

Memory Management

// Allocate device memory
var deviceBuffer = await accelerator.AllocateAsync<float>(1_000_000);

// Copy data to GPU
await deviceBuffer.CopyFromAsync(hostData);

// Use in kernel execution
var parameters = new { 
    input = deviceBuffer,
    output = outputBuffer,
    length = 1_000_000
};

await compiledKernel.ExecuteAsync(parameters);

// Copy results back
await deviceBuffer.CopyToAsync(hostResults);

Architecture

Device Management

The CUDA backend automatically handles:

• Device Detection: Enumerates all CUDA-capable GPUs
• Capability Checking: Validates compute capability requirements
• Context Management: Creates and manages CUDA contexts
• Multi-GPU Coordination: Handles device selection and P2P setup

Compilation Pipeline

1. Source Validation: Validates OpenCL C/CUDA C kernel source
2. NVRTC Compilation: Compiles to PTX intermediate representation
3. Module Loading: Loads PTX into CUDA context
4. Function Extraction: Extracts kernel function references
5. Caching: Stores compiled modules for reuse

Memory System

• Device Allocation: cuMemAlloc for device memory
• Host-Pinned Memory: cudaMallocHost for efficient transfers
• Unified Memory: cudaMallocManaged for automatic migration
• P2P Transfers: Direct memory copying between GPUs

Performance Benchmarks

Tested on RTX 2000 Ada Generation (8GB VRAM, CC 8.9):

Memory Bandwidth

• Host to Device: ~12 GB/s (PCIe 4.0 x16)
• Device Memory: ~450 GB/s (GDDR6)
• P2P Transfer: ~25 GB/s (NVLink when available)

System Requirements

Hardware Requirements

• NVIDIA GPU: Compute Capability 5.0 or higher
• Memory: Minimum 2GB VRAM, 8GB+ recommended
• PCIe: PCIe 3.0 x16 or better for optimal performance

Software Requirements

• CUDA Toolkit: 12.0 or later
• Driver Version: 535.54 or later
• Operating System: Windows 10+, Linux, or WSL2

Supported GPUs

• RTX Series: RTX 2000+, RTX 3000+, RTX 4000+ (CC 7.5-8.9)
• GTX Series: GTX 1050+ (CC 6.1+)
• Quadro/Tesla: Most modern professional GPUs
• Data Center: A100, H100, V100 series

Configuration

Environment Variables

# CUDA installation path (auto-detected)
export CUDA_PATH="/usr/local/cuda"

# Enable additional logging
export DOTCOMPUTE_CUDA_VERBOSE=1

# Force specific GPU device
export CUDA_VISIBLE_DEVICES=0

Compilation Options

var options = new CompilationOptions
{
    OptimizationLevel = OptimizationLevel.O3, // Maximum optimization
    EnableDebugInfo = false, // Disable for production
    TargetArchitecture = "compute_75", // Target specific CC
    CustomOptions = new[] { "--use_fast_math" }
};

var kernel = await accelerator.CompileKernelAsync(definition, options);

Troubleshooting

Common Issues

GPU Not Detected

1. Check Driver: Verify NVIDIA drivers are installed and up-to-date
2. CUDA Toolkit: Ensure CUDA Toolkit is properly installed
3. System Path: Verify CUDA binaries are in system PATH
4. Compute Mode: Check GPU is not in prohibited compute mode

Compilation Failures

1. Kernel Source: Validate OpenCL C/CUDA C syntax
2. Include Paths: Ensure CUDA headers are accessible
3. Compute Capability: Match target architecture to GPU capabilities
4. Memory Limits: Check kernel doesn't exceed resource limits

Performance Issues

1. Memory Bandwidth: Optimize memory access patterns
2. Occupancy: Balance threads per block with resource usage
3. Data Transfer: Minimize host-device memory copies
4. Kernel Launch: Reduce kernel launch overhead with batching

Debug Tools

// Enable detailed CUDA logging
var logger = LoggerFactory.Create(builder => 
    builder.AddConsole().SetMinimumLevel(LogLevel.Trace));

// Get detailed GPU information
var info = await accelerator.GetDeviceInfoAsync();
Console.WriteLine($"GPU: {info.Name}, Memory: {info.TotalMemory / (1024*1024*1024)}GB");

// Profile kernel execution
var stopwatch = Stopwatch.StartNew();
await kernel.ExecuteAsync(parameters);
await accelerator.SynchronizeAsync();
stopwatch.Stop();
Console.WriteLine($"Kernel time: {stopwatch.ElapsedMilliseconds}ms");

Advanced Features

Multi-GPU Programming

// Enumerate all available GPUs
var devices = await CudaAccelerator.GetAvailableDevicesAsync();

// Create accelerators for each GPU
var accelerators = new List<CudaAccelerator>();
foreach (var device in devices)
{
    var acc = new CudaAccelerator(device, logger);
    await acc.InitializeAsync();
    accelerators.Add(acc);
}

// Enable P2P access between GPUs
await CudaAccelerator.EnablePeerAccessAsync(accelerators[0], accelerators[1]);

Unified Memory

// Allocate unified memory (accessible from CPU and GPU)
var unifiedBuffer = await accelerator.AllocateUnifiedAsync<float>(size);

// CPU can access directly
for (int i = 0; i < size; i++)
    unifiedBuffer[i] = i * 2.0f;

// GPU kernels can access the same memory
await kernel.ExecuteAsync(new { data = unifiedBuffer, size });

// Results automatically available on CPU
Console.WriteLine($"Result: {unifiedBuffer[0]}");

Documentation & Resources

Comprehensive documentation is available for DotCompute:

Architecture Documentation

• Backend Integration - CUDA implementation and P2P architecture
• Memory Management - GPU memory pooling and transfers

Developer Guides

• Getting Started - Installation and CUDA setup
• Backend Selection - When to use GPU acceleration
• Multi-GPU Programming - P2P transfers and multi-GPU coordination
• Performance Tuning - GPU optimization techniques
• Troubleshooting - CUDA-specific issues

Examples

• Image Processing - GPU-accelerated filters (15-80x speedup)
• Matrix Operations - GPU matrix multiplication (1000x with tiling)

API Documentation

• API Reference - Complete API documentation
• Diagnostic Rules - DC001-DC012 analyzer reference

Support

• Documentation: Comprehensive Guides
• Issues: GitHub Issues
• Discussions: GitHub Discussions

Contributing

The CUDA backend welcomes contributions in:

• New GPU architecture support (Ada Lovelace, Hopper)
• Advanced CUDA features (streams, events, graphs)
• Performance optimizations and benchmarks
• Multi-GPU coordination improvements

See CONTRIBUTING.md for development guidelines.