# PR #31143 完整报告

- 仓库：`sgl-project/sglang`
- 标题：[AMD] jit_kernel: complete utils.cuh HIP-compat (cudaDevAttr / cudaDeviceGetAttribute)
- 合并时间：2026-07-14 16:06
- 原文链接：http://prhub.com.cn/sgl-project/sglang/pull/31143

---

# PR #31143 分析报告：为 utils.cuh 添加缺失的 HIP 映射

## 执行摘要
本 PR 在 JIT 内核共享头文件 `utils.cuh` 的 HIP 兼容块中添加了三行宏定义，修复了 AMD ROCm 平台上（尤其是 gfx1151 / RDNA3.5 设备）JIT 内核编译失败的问题。变更极小（+3 行），仅在 ROCm 构建下生效，CUDA 构建无变化。该修复是 SGLang 支持消费者 RDNA GPU 能力的一部分。

## 功能与动机
JIT 内核的共享头文件 `jit_kernel/include/sgl_kernel/utils.cuh` 中包含一个 HIP 兼容块，用于将 CUDA 运行时符号映射到 HIP 对应符号（如 `cudaGetErrorString`、`cudaMemcpy*` 等），但 **遗漏了 **`cudaDeviceGetAttribute` 及其相关的 `cudaDevAttrComputeCapabilityMajor/Minor` 枚举。这些符号被 `getSMVersion()` 函数使用，而该函数被许多 JIT 内核调用（例如 KV-cache 内核）。在 ROCm 上，包含 `utils.cuh` 的任何内核都会因此编译失败，报错：`use of undeclared identifier 'cudaDevAttrComputeCapabilityMajor'`。

在 gfx1151（Strix Halo / RDNA3.5）等消费者 RDNA 设备上，这个问题尤为关键，因为 CDNA 路径会跳过这些 JIT 内核，而 RDNA 路径会使用它们。PR 作者在 body 中强调："On ROCm this makes any JIT kernel that includes utils.cuh — e.g. the KV-cache kernel every model compiles — fail to build." 此修复是消费者 RDNA 支持跟踪 issue #30599 的一部分。

## 实现拆解

1. **在 `utils.cuh` 的 HIP 兼容块中添加映射**：在文件 `python/sglang/jit_kernel/include/sgl_kernel/utils.cuh` 的 `#else /* USE_ROCM */` 分支内（该分支仅在定义了 `USE_ROCM` 时编译），在已有的 `#define` 映射列表后添加了三行：
 - `cudaDeviceGetAttribute` → `hipDeviceGetAttribute`
 - `cudaDevAttrComputeCapabilityMajor` → `hipDeviceAttributeComputeCapabilityMajor`
 - `cudaDevAttrComputeCapabilityMinor` → `hipDeviceAttributeComputeCapabilityMinor`
2. **条件编译确保 CUDA 构建无影响**：这些宏定义位于 `#ifndef USE_ROCM` 的 `#else` 块中，因此它们仅对 ROCm 构建生效。对于 CUDA 构建，这些符号由 CUDA 头文件提供，不会引入任何变化。
3. **验证**：作者在 real gfx1151（RDNA3.5）设备上验证了端到端服务，确认 Qwen2.5-7B 和 OLMoE-1B-7B 均能正确运行，无 hipError。无数值、性能或安全影响，因为这只是编译时符号映射。

### `python/sglang/jit_kernel/include/sgl_kernel/utils.cuh`

这是唯一被修改的文件。缺失的 HIP 映射导致 ROCm 上所有包含此文件的 JIT 内核编译失败。添加三个宏定义修复了该问题。

```cuda
// File: python/sglang/jit_kernel/include/sgl_kernel/utils.cuh
// Context: 该文件是 SGLang JIT 内核的共享头文件，包含 CUDA/HIP 兼容宏。
// 以下代码位于 `#ifndef USE_ROCM` 的 `#else` 分支中，仅 ROCm 编译时生效。

// ... 其他 HIP 兼容宏 ...
#define cudaMemcpyAsync hipMemcpyAsync
#define cudaMemcpyHostToDevice hipMemcpyHostToDevice
#define cudaMemcpyDeviceToHost hipMemcpyDeviceToHost

// 新增：映射 cudaDeviceGetAttribute 及 cudaDevAttrComputeCapabilityMajor/Minor
// 这些符号被 `getSMVersion()` 函数用于获取设备计算能力，
// 缺失会导致所有包含 utils.cuh 的 JIT 内核编译失败。
#define cudaDeviceGetAttribute hipDeviceGetAttribute
#define cudaDevAttrComputeCapabilityMajor hipDeviceAttributeComputeCapabilityMajor
#define cudaDevAttrComputeCapabilityMinor hipDeviceAttributeComputeCapabilityMinor

#endif /* USE_ROCM */
// ...

```

## 评论区精华
- 审核人员 `DarkSharpness` 快速批准（LGTM），无额外讨论。
- `gemini-code-assist[bot]` 的自动化审查未提供实质性反馈。
- 无实质性评论交锋，变更简单直接。

## 风险与影响
- **风险**：极低。变更仅涉及三行宏定义，位于 ROCm 专用条件编译块内。CUDA 构建完全不受影响。映射与运行时内核 `runtime.cuh` 中已有的定义一致，且已通过实际硬件验证。
- **影响**：影响范围有限但至关重要——它修复了 AMD RDNA 设备（尤其是 gfx1151）上的 JIT 内核编译失败问题，使得在消费者 AMD GPU 上运行任何模型成为可能。这是 SGLang 支持消费者 RDNA GPU（#30599）这一更大能力的基石。

## 关联脉络
- **PR #31137**：本 PR 的配套，启用 `sgl-kernel` 在 gfx1151 上的构建。两者结合才能实现在 gfx1151 上端到端服务模型。
- **Issue #30599**：消费者 RDNA 支持跟踪 issue，本 PR 是该 issue 中具体问题（JIT 内核编译失败）的修复。
- 与近期历史 PR 的关联：此修复属于持续进行的 AMD 消费者支持工作的一部分。与 #31137、#27873、#28046 等类似，都是在填充 ROCm 平台上的兼容性空白。