knowledge/cuda_mappings.py

"""
ROCm Forge — CUDA to ROCm/HIP Comprehensive Mapping Database
Contains all API, library, package, environment variable, and header mappings
needed for autonomous CUDA-to-AMD migration.
"""

# =============================================================================
# CUDA Runtime API → HIP Runtime API Mappings
# =============================================================================
CUDA_TO_HIP_API = {
    # Memory Management
    "cudaMalloc": "hipMalloc",
    "cudaFree": "hipFree",
    "cudaMemcpy": "hipMemcpy",
    "cudaMemcpyAsync": "hipMemcpyAsync",
    "cudaMemset": "hipMemset",
    "cudaMemsetAsync": "hipMemsetAsync",
    "cudaMemcpyHostToDevice": "hipMemcpyHostToDevice",
    "cudaMemcpyDeviceToHost": "hipMemcpyDeviceToHost",
    "cudaMemcpyDeviceToDevice": "hipMemcpyDeviceToDevice",
    "cudaMallocManaged": "hipMallocManaged",
    "cudaMallocHost": "hipHostMalloc",
    "cudaFreeHost": "hipHostFree",
    "cudaHostAlloc": "hipHostMalloc",
    "cudaMemGetInfo": "hipMemGetInfo",
    "cudaMemcpy2D": "hipMemcpy2D",
    "cudaMallocPitch": "hipMallocPitch",
    "cudaPointerGetAttributes": "hipPointerGetAttributes",
    
    # Device Management
    "cudaGetDevice": "hipGetDevice",
    "cudaSetDevice": "hipSetDevice",
    "cudaGetDeviceCount": "hipGetDeviceCount",
    "cudaGetDeviceProperties": "hipGetDeviceProperties",
    "cudaDeviceReset": "hipDeviceReset",
    "cudaDeviceSynchronize": "hipDeviceSynchronize",
    "cudaDeviceGetAttribute": "hipDeviceGetAttribute",
    "cudaChooseDevice": "hipChooseDevice",
    
    # Stream Management
    "cudaStreamCreate": "hipStreamCreate",
    "cudaStreamCreateWithFlags": "hipStreamCreateWithFlags",
    "cudaStreamDestroy": "hipStreamDestroy",
    "cudaStreamSynchronize": "hipStreamSynchronize",
    "cudaStreamWaitEvent": "hipStreamWaitEvent",
    "cudaStreamQuery": "hipStreamQuery",
    
    # Event Management
    "cudaEventCreate": "hipEventCreate",
    "cudaEventCreateWithFlags": "hipEventCreateWithFlags",
    "cudaEventRecord": "hipEventRecord",
    "cudaEventSynchronize": "hipEventSynchronize",
    "cudaEventElapsedTime": "hipEventElapsedTime",
    "cudaEventDestroy": "hipEventDestroy",
    "cudaEventQuery": "hipEventQuery",
    
    # Kernel Launch
    "cudaLaunchKernel": "hipLaunchKernel",
    "cudaFuncSetCacheConfig": "hipFuncSetCacheConfig",
    "cudaFuncGetAttributes": "hipFuncGetAttributes",
    
    # Error Handling
    "cudaGetLastError": "hipGetLastError",
    "cudaGetErrorString": "hipGetErrorString",
    "cudaPeekAtLastError": "hipPeekAtLastError",
    
    # Type Mappings
    "cudaError_t": "hipError_t",
    "cudaSuccess": "hipSuccess",
    "cudaStream_t": "hipStream_t",
    "cudaEvent_t": "hipEvent_t",
    "cudaDeviceProp": "hipDeviceProp_t",
    "cudaMemcpyKind": "hipMemcpyKind",
    
    # Texture & Surface (limited)
    "cudaCreateTextureObject": "hipCreateTextureObject",
    "cudaDestroyTextureObject": "hipDestroyTextureObject",
}


# =============================================================================
# CUDA Library → ROCm Library Mappings
# =============================================================================
CUDA_TO_ROCM_LIBS = {
    "cuBLAS": "rocBLAS",
    "cublas": "rocblas",
    "cublasCreate": "rocblas_create_handle",
    "cublasDestroy": "rocblas_destroy_handle",
    "cublasSgemm": "rocblas_sgemm",
    "cublasDgemm": "rocblas_dgemm",
    "cuDNN": "MIOpen",
    "cudnn": "miopen",
    "cudnnCreate": "miopenCreate",
    "cudnnDestroy": "miopenDestroy",
    "cuFFT": "rocFFT",
    "cufft": "rocfft",
    "cufftPlan1d": "rocfft_plan_create",
    "cufftExecC2C": "rocfft_execute",
    "cuSPARSE": "rocSPARSE",
    "cusparse": "rocsparse",
    "cuRAND": "rocRAND",
    "curand": "rocrand",
    "curandCreateGenerator": "rocrand_create_generator",
    "cuSOLVER": "rocSOLVER",
    "cusolver": "rocsolver",
    "NCCL": "RCCL",
    "nccl": "rccl",
    "ncclCommInitRank": "ncclCommInitRank",  # Same API in RCCL
    "Thrust": "rocThrust",
    "thrust": "rocthrust",
    "CUB": "hipCUB",
    "cub": "hipcub",
    "nvcc": "hipcc",
    "NVCC": "HIPCC",
}


# =============================================================================
# PyTorch-Specific CUDA → ROCm Patterns
# =============================================================================
PYTORCH_PATTERNS = {
    # These work on ROCm but may need attention
    "torch.backends.cudnn.benchmark": {
        "replacement": "torch.backends.cudnn.benchmark",
        "note": "Works on ROCm via MIOpen backend. Consider setting to True for performance.",
        "action": "info",
    },
    "torch.backends.cudnn.deterministic": {
        "replacement": "torch.backends.cudnn.deterministic",
        "note": "Works on ROCm via MIOpen backend.",
        "action": "info",
    },
    "torch.backends.cudnn.enabled": {
        "replacement": "torch.backends.cudnn.enabled",
        "note": "Controls MIOpen on ROCm. Works transparently.",
        "action": "info",
    },
    "torch.cuda.amp": {
        "replacement": "torch.cuda.amp",
        "note": "AMP works on ROCm. GradScaler and autocast are supported.",
        "action": "compatible",
    },
    "torch.cuda.is_available()": {
        "replacement": "torch.cuda.is_available()",
        "note": "Returns True on ROCm when HIP is available. Works transparently.",
        "action": "compatible",
    },
    ".cuda()": {
        "replacement": ".cuda()",
        "note": "Works on ROCm. Moves tensors to HIP device.",
        "action": "compatible",
    },
    "torch.cuda.device_count()": {
        "replacement": "torch.cuda.device_count()",
        "note": "Returns number of AMD GPUs on ROCm.",
        "action": "compatible",
    },
    "torch.cuda.set_device": {
        "replacement": "torch.cuda.set_device",
        "note": "Works on ROCm.",
        "action": "compatible",
    },
    "torch.cuda.current_device()": {
        "replacement": "torch.cuda.current_device()",
        "note": "Works on ROCm.",
        "action": "compatible",
    },
    "torch.cuda.empty_cache()": {
        "replacement": "torch.cuda.empty_cache()",
        "note": "Works on ROCm.",
        "action": "compatible",
    },
    "torch.cuda.memory_allocated": {
        "replacement": "torch.cuda.memory_allocated",
        "note": "Works on ROCm for memory tracking.",
        "action": "compatible",
    },
}


# =============================================================================
# pip Package Migration Mappings
# =============================================================================
PIP_PACKAGE_MAPPINGS = {
    # Nvidia runtime packages (remove)
    "nvidia-cuda-runtime-cu11": {"action": "remove", "note": "Not needed on ROCm. GPU runtime is provided by ROCm stack."},
    "nvidia-cuda-runtime-cu12": {"action": "remove", "note": "Not needed on ROCm. GPU runtime is provided by ROCm stack."},
    "nvidia-cuda-nvrtc-cu11": {"action": "remove", "note": "Not needed on ROCm."},
    "nvidia-cuda-nvrtc-cu12": {"action": "remove", "note": "Not needed on ROCm."},
    "nvidia-cublas-cu11": {"action": "remove", "note": "Replaced by rocBLAS (system package)."},
    "nvidia-cublas-cu12": {"action": "remove", "note": "Replaced by rocBLAS (system package)."},
    "nvidia-cudnn-cu11": {"action": "remove", "note": "Replaced by MIOpen (system package)."},
    "nvidia-cudnn-cu12": {"action": "remove", "note": "Replaced by MIOpen (system package)."},
    "nvidia-cufft-cu11": {"action": "remove", "note": "Replaced by rocFFT (system package)."},
    "nvidia-cufft-cu12": {"action": "remove", "note": "Replaced by rocFFT (system package)."},
    "nvidia-cusparse-cu11": {"action": "remove", "note": "Replaced by rocSPARSE (system package)."},
    "nvidia-cusparse-cu12": {"action": "remove", "note": "Replaced by rocSPARSE (system package)."},
    "nvidia-cusolver-cu11": {"action": "remove", "note": "Replaced by rocSOLVER (system package)."},
    "nvidia-cusolver-cu12": {"action": "remove", "note": "Replaced by rocSOLVER (system package)."},
    "nvidia-nccl-cu11": {"action": "remove", "note": "Replaced by RCCL (system package)."},
    "nvidia-nccl-cu12": {"action": "remove", "note": "Replaced by RCCL (system package)."},
    "nvidia-nvtx-cu11": {"action": "remove", "note": "ROCm has rocTracer for profiling."},
    "nvidia-nvtx-cu12": {"action": "remove", "note": "ROCm has rocTracer for profiling."},
    
    # PyTorch ecosystem (replace with ROCm builds)
    "torch": {
        "action": "replace",
        "replacement": "torch (ROCm 6.2 build)",
        "install": "pip install torch --index-url https://download.pytorch.org/whl/rocm6.2",
    },
    "torchvision": {
        "action": "replace",
        "replacement": "torchvision (ROCm 6.2 build)",
        "install": "pip install torchvision --index-url https://download.pytorch.org/whl/rocm6.2",
    },
    "torchaudio": {
        "action": "replace",
        "replacement": "torchaudio (ROCm 6.2 build)",
        "install": "pip install torchaudio --index-url https://download.pytorch.org/whl/rocm6.2",
    },
    
    # Quantization & optimization libraries
    "bitsandbytes": {
        "action": "replace",
        "replacement": "bitsandbytes-rocm",
        "install": "pip install bitsandbytes-rocm",
    },
    "auto-gptq": {
        "action": "warning",
        "note": "ROCm support varies. Check https://github.com/AutoGPTQ/AutoGPTQ for ROCm-compatible releases.",
    },
    "awq": {
        "action": "warning",
        "note": "Limited ROCm support. Consider using GPTQ or native quantization instead.",
    },
    
    # Attention & kernel libraries
    "xformers": {
        "action": "warning",
        "note": "Limited ROCm support. Use PyTorch native SDPA (torch.nn.functional.scaled_dot_product_attention) instead.",
    },
    "flash-attn": {
        "action": "warning",
        "note": "Flash Attention has experimental ROCm support. Use PyTorch SDPA as a reliable alternative.",
    },
    
    # Compiler
    "triton": {
        "action": "replace",
        "replacement": "triton (ROCm build)",
        "install": "pip install triton --index-url https://download.pytorch.org/whl/rocm6.2",
    },
    
    # Serving
    "vllm": {
        "action": "replace",
        "replacement": "vllm (ROCm build)",
        "install": "pip install vllm",
        "note": "vLLM supports ROCm natively. Use ROCm-compatible PyTorch.",
    },
    
    # Distributed training
    "deepspeed": {
        "action": "info",
        "note": "DeepSpeed supports ROCm. Install with ROCm-compatible PyTorch and set DS_BUILD_OPS=1.",
    },
    "horovod": {
        "action": "info",
        "note": "Horovod has ROCm support. Build from source with HOROVOD_GPU=ROCM.",
    },
}


# =============================================================================
# Environment Variable Mappings
# =============================================================================
ENV_VAR_MAPPINGS = {
    "CUDA_VISIBLE_DEVICES": "HIP_VISIBLE_DEVICES",
    "CUDA_HOME": "ROCM_HOME",
    "CUDA_PATH": "ROCM_PATH",
    "CUDA_ROOT": "ROCM_PATH",
    "CUDA_LAUNCH_BLOCKING": "HIP_LAUNCH_BLOCKING",
    "CUDA_DEVICE_ORDER": "HIP_DEVICE_ORDER",
    "NCCL_DEBUG": "NCCL_DEBUG",  # Same in RCCL
    "NCCL_SOCKET_IFNAME": "NCCL_SOCKET_IFNAME",  # Same in RCCL
    "CUDA_DEVICE_MAX_CONNECTIONS": "GPU_MAX_HW_QUEUES",
}


# =============================================================================
# C/C++ Header Mappings
# =============================================================================
HEADER_MAPPINGS = {
    "cuda_runtime.h": "hip/hip_runtime.h",
    "cuda.h": "hip/hip_runtime.h",
    "cuda_runtime_api.h": "hip/hip_runtime_api.h",
    "cuda_fp16.h": "hip/hip_fp16.h",
    "cuda_bf16.h": "hip/hip_bf16.h",
    "cublas_v2.h": "rocblas/rocblas.h",
    "cublas.h": "rocblas/rocblas.h",
    "cudnn.h": "miopen/miopen.h",
    "cufft.h": "rocfft/rocfft.h",
    "cusparse.h": "rocsparse/rocsparse.h",
    "curand.h": "rocrand/rocrand.h",
    "curand_kernel.h": "rocrand/rocrand_kernel.h",
    "cusolver_common.h": "rocsolver/rocsolver.h",
    "cusolverDn.h": "rocsolver/rocsolver.h",
    "nccl.h": "rccl/rccl.h",
    "nvToolsExt.h": "roctracer/roctx.h",
    "cooperative_groups.h": "hip/hip_cooperative_groups.h",
    "thrust/device_vector.h": "thrust/device_vector.h",  # rocThrust compatible
    "thrust/host_vector.h": "thrust/host_vector.h",
}


# =============================================================================
# CUDA Kernel Syntax → HIP Kernel Syntax
# =============================================================================
KERNEL_SYNTAX_MAPPINGS = {
    "__global__": "__global__",  # Same in HIP
    "__device__": "__device__",  # Same in HIP
    "__host__": "__host__",      # Same in HIP
    "__shared__": "__shared__",  # Same in HIP
    "__constant__": "__constant__",  # Same in HIP
    "__syncthreads()": "__syncthreads()",  # Same in HIP
    "threadIdx": "threadIdx",  # Same in HIP
    "blockIdx": "blockIdx",    # Same in HIP
    "blockDim": "blockDim",    # Same in HIP
    "gridDim": "gridDim",      # Same in HIP
    "warpSize": "warpSize",    # Same in HIP (but check: 64 on AMD vs 32 on NVIDIA)
}


# =============================================================================
# Hardware-Aware Mappings (Tough Engineering)
# =============================================================================
HARDWARE_AWARE_MAPPINGS = {
    # Warp vs Wavefront rewriting
    "32": {
        "context": ["__syncwarp", "warp_size", "warpSize"],
        "replacement": "__AMDGCN_WAVEFRONT_SIZE",
        "note": "Hardware-Aware Refactoring: Hardcoded Warp Size (32) replaced with dynamic AMD Wavefront Size (64)."
    },
    # NVIDIA Tensor Core -> AMD Matrix Core
    "wmma::mma_sync": {
        "replacement": "__builtin_amdgcn_mfma_f32_32x32x1f32",
        "note": "Intrinsic Lowering: Translated NVIDIA Tensor Core mma.sync to AMD Matrix Core (MFMA) intrinsic."
    },
    "nvcuda::wmma": {
        "replacement": "rocwmma",
        "note": "Library Abstraction: Replaced nvcuda::wmma namespace with rocwmma."
    },
    "wmma::": {
        "replacement": "rocwmma::",
        "note": "Library Abstraction: Replaced NVIDIA wmma namespace with AMD rocwmma. Verification required."
    }
}


# =============================================================================
# Known Incompatibilities & Warnings
# =============================================================================
KNOWN_ISSUES = {
    "warp_size": {
        "pattern": "warpSize",
        "severity": "warning",
        "message": "AMD GPUs use warp size 64 (wavefront) vs NVIDIA's 32. Code assuming warpSize==32 will break.",
        "fix": "Use __builtin_amdgcn_wavefrontsize() or check warpSize at runtime.",
    },
    "cooperative_groups": {
        "pattern": "cooperative_groups",
        "severity": "warning",
        "message": "Cooperative groups have limited support in HIP. Test thoroughly.",
        "fix": "Use basic __syncthreads() where possible, or check HIP cooperative groups API.",
    },
    "dynamic_parallelism": {
        "pattern": "cudaLaunchKernel.*<<<",
        "severity": "error",
        "message": "Dynamic parallelism (launching kernels from kernels) is not supported on most AMD GPUs.",
        "fix": "Restructure code to launch all kernels from the host.",
    },
    "tensor_cores": {
        "pattern": "wmma|mma\\.sync|tensor_core",
        "severity": "warning",
        "message": "NVIDIA Tensor Core operations need to be replaced with AMD Matrix Core (MFMA) operations.",
        "fix": "Use rocWMMA library or PyTorch's native mixed precision.",
    },
    "cudnn_specific": {
        "pattern": "cudnnSetConvolution|cudnnFindConvolution",
        "severity": "info",
        "message": "cuDNN convolution APIs map to MIOpen but with different tuning behavior.",
        "fix": "MIOpen auto-tunes by default. Set MIOPEN_FIND_MODE for control.",
    },
}


# =============================================================================
# CLI Tool Mappings
# =============================================================================
CLI_TOOL_MAPPINGS = {
    "nvidia-smi": "rocm-smi",
    "nvcc": "hipcc",
    "cuda-memcheck": "rocm-debug-agent",
    "nvprof": "rocprof",
    "nsight-compute": "omniperf",
    "nsight-systems": "omnitrace",
    "cuda-gdb": "rocgdb",
    "deviceQuery": "rocminfo",
}


# =============================================================================
# Docker Base Image Mappings
# =============================================================================
DOCKER_IMAGE_MAPPINGS = {
    "nvidia/cuda:11.8.0-devel-ubuntu22.04": "rocm/dev-ubuntu-22.04:6.2-complete",
    "nvidia/cuda:12.1.0-devel-ubuntu22.04": "rocm/dev-ubuntu-22.04:6.2-complete",
    "nvidia/cuda:12.2.0-devel-ubuntu22.04": "rocm/dev-ubuntu-22.04:6.2-complete",
    "nvidia/cuda:11.8.0-runtime-ubuntu22.04": "rocm/dev-ubuntu-22.04:6.2",
    "nvidia/cuda:12.1.0-runtime-ubuntu22.04": "rocm/dev-ubuntu-22.04:6.2",
    "pytorch/pytorch:2.1.0-cuda11.8-cudnn8-devel": "rocm/pytorch:rocm6.2_ubuntu22.04_py3.10_pytorch_release_2.3.0",
    "pytorch/pytorch:2.2.0-cuda12.1-cudnn8-devel": "rocm/pytorch:rocm6.2_ubuntu22.04_py3.10_pytorch_release_2.3.0",
}


# =============================================================================
# Implicit CUDA Assumptions — Curiosity-Driven Exploration Scan
# (Inspired by curiosity-driven RL: detect patterns that AREN'T explicitly
# CUDA API calls but silently assume NVIDIA hardware behavior)
# =============================================================================
IMPLICIT_CUDA_PATTERNS = {
    "hardcoded_warp_32": {
        "regex": r"\b32\b",
        "context_required": ["thread", "warp", "lane", "mask", "shuffle", "ballot", "shfl", "__syncwarp", "blockDim"],
        "severity": "critical",
        "message": "Hardcoded value 32 in thread/warp context. AMD wavefronts are 64-wide — this WILL produce silent wrong results.",
        "fix": "Replace with warpSize or __builtin_amdgcn_wavefrontsize() for portability.",
    },
    "hardcoded_sm_count": {
        "regex": r"(?:num_sm|sm_count|multiprocessor|SM_COUNT)\s*=\s*\d+",
        "context_required": [],
        "severity": "warning",
        "message": "Hardcoded Streaming Multiprocessor count. AMD uses Compute Units (CUs) with different counts per GPU.",
        "fix": "Query device properties at runtime: hipDeviceGetAttribute(&val, hipDeviceAttributeMultiprocessorCount, dev).",
    },
    "shared_mem_bank_32": {
        "regex": r"(?:bank|BANK).*\b32\b|__shfl(?:_sync)?",
        "context_required": [],
        "severity": "warning",
        "message": "Shared memory bank conflict assumptions. AMD GCN/RDNA shared memory has 32 banks (same) but different conflict resolution.",
        "fix": "Test for bank conflicts using rocprof. AMD LDS has different padding requirements.",
    },
    "l2_cache_residency": {
        "regex": r"cudaAccessPolicyWindow|cudaStreamAttrValue|accessPolicyWindow|l2_cache|L2_CACHE",
        "context_required": [],
        "severity": "warning",
        "message": "CUDA L2 cache residency controls have no direct AMD equivalent.",
        "fix": "AMD uses different L2 cache hierarchy. Remove L2 residency hints; use rocprof to tune.",
    },
    "ptx_inline_asm": {
        "regex": r"asm\s*\(\s*\".*(?:mov|ld|st|add|mul|setp|bar|shfl|atom).*\"",
        "context_required": [],
        "severity": "critical",
        "message": "Inline PTX assembly detected. PTX is NVIDIA-specific ISA — completely incompatible with AMD.",
        "fix": "Replace with HIP C++ intrinsics or AMD GCN inline assembly (__builtin_amdgcn_*).",
    },
    "cuda_graph_capture": {
        "regex": r"cudaStreamBeginCapture|cudaGraphLaunch|cuda\.CUDAGraph|with\s+torch\.cuda\.graph",
        "context_required": [],
        "severity": "warning",
        "message": "CUDA Graphs have limited and experimental support on ROCm. May cause hangs or errors.",
        "fix": "Use enforce_eager=True in vLLM. For custom code, test hipGraphLaunch carefully or remove graph capture.",
    },
    "tensor_core_mma": {
        "regex": r"mma\.sync|wmma::|nvcuda::wmma|__hmma|mma_sync",
        "context_required": [],
        "severity": "critical",
        "message": "NVIDIA Tensor Core (WMMA/MMA) intrinsics detected. These require complete rewrite for AMD Matrix Cores (MFMA).",
        "fix": "Use rocWMMA library or replace with __builtin_amdgcn_mfma_* intrinsics.",
    },
    "occupancy_calculator": {
        "regex": r"cudaOccupancyMaxPotentialBlockSize|cudaOccupancyMaxActiveBlocksPerMultiprocessor",
        "context_required": [],
        "severity": "warning",
        "message": "CUDA occupancy API. AMD has different occupancy characteristics due to 64-wide wavefronts and different register files.",
        "fix": "Use hipOccupancyMaxPotentialBlockSize. Note: optimal block sizes differ on AMD (prefer multiples of 64).",
    },
}


# =============================================================================
# ROCm Build Error Runbook — Incident Copilot Database
# (Inspired by incident-response copilots: maps common build/runtime errors
# to root causes and automatic fixes)
# =============================================================================
ROCM_BUILD_ERROR_RUNBOOK = {
    "hip_not_found": {
        "error_pattern": r"hip/hip_runtime\.h.*No such file|cannot find -lhip",
        "root_cause": "ROCm SDK not installed or not in PATH",
        "fix_steps": [
            "Install ROCm: sudo apt install rocm-dev",
            "Set environment: export ROCM_HOME=/opt/rocm",
            "Add to PATH: export PATH=$ROCM_HOME/bin:$PATH",
        ],
        "severity": "critical",
    },
    "hipcc_not_found": {
        "error_pattern": r"hipcc.*not found|hipcc.*No such file",
        "root_cause": "HIP compiler not installed or not in PATH",
        "fix_steps": [
            "Install HIP: sudo apt install hip-dev",
            "Verify: which hipcc",
            "Add to PATH: export PATH=/opt/rocm/bin:$PATH",
        ],
        "severity": "critical",
    },
    "unsupported_gpu_arch": {
        "error_pattern": r"unsupported gpu architecture|Cannot determine AMD GPU",
        "root_cause": "GPU architecture not specified or not supported by this ROCm version",
        "fix_steps": [
            "Check GPU: rocminfo | grep 'Name:'",
            "Set target: export HIP_VISIBLE_DEVICES=0",
            "Compile with arch: hipcc --offload-arch=gfx942 (MI300X) or gfx90a (MI250)",
        ],
        "severity": "critical",
    },
    "rocblas_not_found": {
        "error_pattern": r"cannot find -lrocblas|rocblas\.h.*No such file",
        "root_cause": "rocBLAS library not installed",
        "fix_steps": [
            "Install: sudo apt install rocblas-dev",
            "Link path: export LD_LIBRARY_PATH=/opt/rocm/lib:$LD_LIBRARY_PATH",
        ],
        "severity": "error",
    },
    "miopen_error": {
        "error_pattern": r"miopenStatus.*Error|MIOpen.*failed|miopen.*not found",
        "root_cause": "MIOpen (cuDNN equivalent) configuration issue",
        "fix_steps": [
            "Install: sudo apt install miopen-hip-dev",
            "Set tuning: export MIOPEN_FIND_MODE=3",
            "Clear cache: rm -rf ~/.config/miopen/",
        ],
        "severity": "error",
    },
    "hip_out_of_memory": {
        "error_pattern": r"hipErrorOutOfMemory|HIP out of memory|RuntimeError.*out of memory",
        "root_cause": "GPU memory exhausted — may need different allocation strategy for AMD",
        "fix_steps": [
            "Set: export PYTORCH_HIP_ALLOC_CONF=expandable_segments:True",
            "Reduce batch size or model precision",
            "Monitor: rocm-smi --showmeminfo vram",
        ],
        "severity": "error",
    },
    "warp_size_mismatch": {
        "error_pattern": r"warpSize.*32|lane.*out of range|invalid shuffle",
        "root_cause": "Code assumes NVIDIA warp size (32) but AMD wavefronts are 64-wide",
        "fix_steps": [
            "Replace hardcoded 32 with warpSize or __builtin_amdgcn_wavefrontsize()",
            "Update __shfl_sync masks to cover 64 lanes",
            "Check all bitwise operations on lane masks",
        ],
        "severity": "critical",
    },
    "rccl_timeout": {
        "error_pattern": r"RCCL.*timeout|NCCL.*timeout.*RCCL|collective.*timeout",
        "root_cause": "Multi-GPU communication timeout — RCCL (NCCL equivalent) needs tuning",
        "fix_steps": [
            "Set: export NCCL_SOCKET_IFNAME=eth0",
            "Increase timeout: export RCCL_TIMEOUT=600",
            "Check GPU topology: rocm-smi --showtoponuma",
        ],
        "severity": "error",
    },
}