feat: Add device capability seam for testable GPU queries

LessUp · Copilot · LessUp · commit 7a3f25ab38f7 · 2026-05-28T05:35:12.000+08:00
Extract GPU capability queries from singleton pattern to allow tests
to inject fake device info without requiring specific GPU hardware.

Design:
- DeviceInfoProvider: lightweight struct-based interface
- ProductionDeviceInfoProvider: adapter backed by DeviceInfoCache
- Overloaded API: no-arg versions use production adapter by default
- Tests can supply custom providers for capability scenarios

Changes:
- src/utils/device_info_provider.cuh: new seam interface
- src/utils/cuda_utils.cuh: add production adapter implementation
- src/kernels/tensor_core_sgemm.cuh: use seam for capability queries
- src/utils/benchmark_metrics.cuh: use seam for peak calculations
- tests/test_device_info_seam.cu: comprehensive test coverage
- docs/device_capability_seam.md: design documentation

The fallback policy was already well-structured with the template-based
launch_tensor_core_sgemm_with_fallback interface and BankConflictFreeFallback
concrete policy. No changes needed there.

All existing production code continues to work unchanged, calling no-arg
versions of functions that now delegate to the production adapter.

Co-authored-by: Copilot &lt;223556219+Copilot@users.noreply.github.com&gt;
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -121,10 +121,23 @@ if(BUILD_TESTS)
         $<$<COMPILE_LANGUAGE:CUDA>:--expt-relaxed-constexpr>
     )
 
+    # Device info seam test
+    add_executable(test_device_info_seam tests/test_device_info_seam.cu)
+    target_include_directories(test_device_info_seam PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/src)
+    target_link_libraries(test_device_info_seam PRIVATE
+        GTest::gtest_main
+        CUDA::cudart
+        CUDA::cublas
+    )
+    target_compile_options(test_device_info_seam PRIVATE
+        $<$<COMPILE_LANGUAGE:CUDA>:--expt-relaxed-constexpr>
+    )
+
     include(GoogleTest)
     gtest_discover_tests(test_sgemm)
     gtest_discover_tests(test_utils)
     gtest_discover_tests(test_performance)
     gtest_discover_tests(test_benchmark_settings)
     gtest_discover_tests(test_kernel_catalog)
+    gtest_discover_tests(test_device_info_seam)
 endif()
diff --git a/docs/device_capability_seam.md b/docs/device_capability_seam.md
@@ -0,0 +1,124 @@
+# Device Capability Seam
+
+## Overview
+
+The device capability seam extracts GPU capability queries from the singleton pattern (`DeviceInfoCache::instance()`), allowing tests to inject fake device info without requiring specific GPU hardware.
+
+## Design
+
+### Core Interface
+
+`DeviceInfoProvider` (in `src/utils/device_info_provider.cuh`):
+- Lightweight struct-based interface (no virtual dispatch overhead)
+- Provides minimal surface for querying GPU capabilities
+- Methods: `hasTensorCores()`, `computeMajor()`, `computeMinor()`, `smCount()`, etc.
+
+### Production Adapter
+
+`ProductionDeviceInfoProvider`:
+- Backed by `DeviceInfoCache` singleton
+- Used by default in all production code paths
+- Zero runtime overhead compared to direct singleton access
+
+### API Pattern
+
+All capability-dependent functions provide two overloads:
+
+```cpp
+// With explicit provider (for tests)
+bool tensorCoresAvailable(const DeviceInfoProvider &provider);
+float getTheoreticalPeakGflops(const DeviceInfoProvider &provider);
+
+// Default (uses production provider)
+bool tensorCoresAvailable();
+float getTheoreticalPeakGflops();
+```
+
+## Usage
+
+### Production Code
+
+Production code continues to use no-argument versions:
+
+```cpp
+if (tensorCoresAvailable()) {
+    // Use Tensor Cores
+}
+float peak = getTheoreticalPeakGflops();
+```
+
+### Test Code
+
+Tests can inject fake device info:
+
+```cpp
+cudaDeviceProp fake_prop{};
+fake_prop.major = 7;  // Volta
+fake_prop.minor = 0;
+fake_prop.multiProcessorCount = 80;
+
+DeviceInfoProvider fake_provider{&fake_prop, 64, 1.53f};
+
+EXPECT_TRUE(tensorCoresAvailable(fake_provider));
+EXPECT_NEAR(getTheoreticalPeakGflops(fake_provider), 15667.2f, 0.1f);
+```
+
+## Affected Modules
+
+### `src/utils/cuda_utils.cuh`
+- Added production adapter implementation
+- `DeviceInfoCache` remains unchanged (still singleton)
+- Only the production adapter calls the singleton
+
+### `src/kernels/tensor_core_sgemm.cuh`
+- `tensorCoresAvailable()` - overloaded
+- `getTensorCoreArchName()` - overloaded
+- No longer calls `DeviceInfoCache::instance()` directly
+
+### `src/utils/benchmark_metrics.cuh`
+- `getTheoreticalPeakGflops()` - overloaded
+- `getTheoreticalPeakBandwidth()` - overloaded
+- No longer calls `DeviceInfoCache::instance()` directly
+
+## Testing
+
+See `tests/test_device_info_seam.cu` for comprehensive examples:
+
+- Fake device provider creation
+- Tensor Core capability testing without real hardware
+- Peak GFLOPS/bandwidth calculations with fake devices
+- Architectural classification (Volta, Ampere, Hopper, etc.)
+- Production adapter integration tests
+
+## Design Rationale
+
+### Why struct-based instead of virtual interfaces?
+
+- Zero runtime overhead (no vtable lookups)
+- Header-only implementation remains simple
+- Sufficient for the single use case (production vs test)
+
+### Why preserve the singleton?
+
+- Minimal code changes to existing production paths
+- The singleton itself isn't problematic; the hard dependency was
+- Production adapter provides the indirection we need
+
+### Why overloads instead of default parameters?
+
+- Clearer call sites in tests
+- No ambiguity about which version is being called
+- Easier to grep for test-specific vs production usage
+
+## Limitations
+
+- Tests still require a CUDA-capable GPU to run (for initialization)
+- Only capability queries are abstracted, not actual kernel execution
+- The seam is focused on decision logic, not full GPU emulation
+
+## Future Extensions
+
+If needed, this seam could be extended to support:
+- Mock kernel execution for unit tests
+- Multiple device scenarios in a single test
+- Device capability fuzzing for edge case discovery
diff --git a/src/kernels/tensor_core_sgemm.cuh b/src/kernels/tensor_core_sgemm.cuh
@@ -46,8 +46,19 @@ using tensor_core::WMMA_N;
 
 /**
  * 检查当前设备是否支持 Tensor Core (sm_70+)
+ *
+ * 提供重载版本以支持可注入的 device info provider。
  */
-inline bool tensorCoresAvailable() { return DeviceInfoCache::instance().hasTensorCores(); }
+inline bool tensorCoresAvailable(const DeviceInfoProvider &provider) {
+    return provider.hasTensorCores();
+}
+
+/**
+ * 检查当前设备是否支持 Tensor Core (默认使用生产环境设备)
+ */
+inline bool tensorCoresAvailable() {
+    return tensorCoresAvailable(getProductionDeviceInfo());
+}
 
 /**
  * 检查给定维度是否适合 Tensor Core 加速
@@ -59,20 +70,30 @@ inline bool tensorCoreDimensionsSupported(int M, int K, int N) {
 
 /**
  * 获取当前设备的 Tensor Core 信息字符串
+ *
+ * 提供重载版本以支持可注入的 device info provider。
  */
-inline const char *getTensorCoreArchName() {
-    const cudaDeviceProp &prop = DeviceInfoCache::instance().prop();
-
-    if (prop.major == 7) {
-        return (prop.minor == 0) ? "Volta" : (prop.minor == 5) ? "Turing" : "Unknown sm_7x";
-    } else if (prop.major == 8) {
-        return (prop.minor == 0 || prop.minor == 6) ? "Ampere" : "Ampere/Ada";
-    } else if (prop.major == 9) {
+inline const char *getTensorCoreArchName(const DeviceInfoProvider &provider) {
+    int major = provider.computeMajor();
+    int minor = provider.computeMinor();
+
+    if (major == 7) {
+        return (minor == 0) ? "Volta" : (minor == 5) ? "Turing" : "Unknown sm_7x";
+    } else if (major == 8) {
+        return (minor == 0 || minor == 6) ? "Ampere" : "Ampere/Ada";
+    } else if (major == 9) {
         return "Hopper";
     }
     return "Unknown";
 }
 
+/**
+ * 获取当前设备的 Tensor Core 信息字符串（默认使用生产环境设备）
+ */
+inline const char *getTensorCoreArchName() {
+    return getTensorCoreArchName(getProductionDeviceInfo());
+}
+
 // ============================================================================
 // Fallback 策略接口
 // ============================================================================
diff --git a/src/utils/benchmark_metrics.cuh b/src/utils/benchmark_metrics.cuh
@@ -55,39 +55,46 @@ inline PerformanceMetrics calculateSgemmMetrics(int M, int K, int N, float time_
  * - SM 数量
  * - 每 SM 的 CUDA 核心数
  * - 时钟频率
+ *
+ * 提供重载版本以支持可注入的 device info provider。
  */
-inline float getTheoreticalPeakGflops() {
-    DeviceInfoCache &cache = DeviceInfoCache::instance();
-    const cudaDeviceProp &prop = cache.prop();
-
+inline float getTheoreticalPeakGflops(const DeviceInfoProvider &provider) {
     // 峰值 GFLOPS = SMs * cores/SM * 2 (FMA) * clock (GHz) * 1000 (MHz factor)
-    float peakGflops = prop.multiProcessorCount * cache.coresPerSM() * 2 * cache.clockGHz() * 1000;
-
+    float peakGflops = provider.smCount() * provider.cores_per_sm * 2 * provider.clock_ghz * 1000;
     return peakGflops;
 }
 
+/**
+ * 获取 GPU 理论峰值 GFLOPS（默认使用生产环境设备）
+ */
+inline float getTheoreticalPeakGflops() {
+    return getTheoreticalPeakGflops(getProductionDeviceInfo());
+}
+
 /**
  * 获取 GPU 理论峰值带宽 (GB/s)
  *
  * 基于内存时钟频率和总线宽度计算：
  * - DDR 倍率 (2x)
  * - 内存时钟频率
  * - 内存总线宽度
+ *
+ * 提供重载版本以支持可注入的 device info provider。
  */
-inline float getTheoreticalPeakBandwidth() {
-    const cudaDeviceProp &prop = DeviceInfoCache::instance().prop();
-
+inline float getTheoreticalPeakBandwidth(const DeviceInfoProvider &provider) {
     // 内存时钟频率 (Hz -> MHz)
-    float memoryClockMHz = static_cast<float>(prop.memoryClockRate) / 1000.0f;
+    float memoryClockMHz = static_cast<float>(provider.memoryClockRate()) / 1000.0f;
 
     // 如果 memoryClockRate 不可用，使用架构默认值
     if (memoryClockMHz <= 0) {
-        switch (prop.major) {
+        int major = provider.computeMajor();
+        int minor = provider.computeMinor();
+        switch (major) {
         case 7:
-            memoryClockMHz = (prop.minor == 5) ? 1750.0f : 877.0f; // Turing vs Volta
+            memoryClockMHz = (minor == 5) ? 1750.0f : 877.0f; // Turing vs Volta
             break;
         case 8:
-            memoryClockMHz = (prop.minor == 6) ? 1215.0f : 1593.0f; // A100 vs RTX 30
+            memoryClockMHz = (minor == 6) ? 1215.0f : 1593.0f; // A100 vs RTX 30
             break;
         case 9:
             memoryClockMHz = 2619.0f; // H100 HBM3
@@ -98,11 +105,18 @@ inline float getTheoreticalPeakBandwidth() {
     }
 
     // 峰值带宽 = 2 (DDR) * clock (MHz) * bus width (bits) / 8 (bytes)
-    float peakBandwidth = 2 * memoryClockMHz * (prop.memoryBusWidth / 8) / 1000.0f;
+    float peakBandwidth = 2 * memoryClockMHz * (provider.memoryBusWidth() / 8) / 1000.0f;
 
     return peakBandwidth; // GB/s
 }
 
+/**
+ * 获取 GPU 理论峰值带宽（默认使用生产环境设备）
+ */
+inline float getTheoreticalPeakBandwidth() {
+    return getTheoreticalPeakBandwidth(getProductionDeviceInfo());
+}
+
 /**
  * 计算效率（相对于理论峰值的百分比）
  */
diff --git a/src/utils/cuda_utils.cuh b/src/utils/cuda_utils.cuh
@@ -7,6 +7,8 @@
 #include <curand.h>
 #include <random>
 
+#include "device_info_provider.cuh"
+
 // ============================================================================
 // 命名常量
 // ============================================================================
@@ -247,3 +249,26 @@ class DeviceInfoCache {
     int coresPerSM_;
     float clockGHz_;
 };
+
+// ============================================================================
+// Device Info Provider Implementation
+// ============================================================================
+
+/**
+ * Production adapter implementation: queries from DeviceInfoCache
+ */
+inline DeviceInfoProvider ProductionDeviceInfoProvider::get() const {
+    DeviceInfoCache &cache = DeviceInfoCache::instance();
+    return DeviceInfoProvider{
+        &cache.prop(),
+        cache.coresPerSM(),
+        cache.clockGHz(),
+    };
+}
+
+/**
+ * Convenience function: get production device info
+ */
+inline DeviceInfoProvider getProductionDeviceInfo() {
+    return ProductionDeviceInfoProvider{}.get();
+}
diff --git a/src/utils/device_info_provider.cuh b/src/utils/device_info_provider.cuh
diff --git a/tests/test_device_info_seam.cu b/tests/test_device_info_seam.cu
