gpu-test-framework

GPU Test Framework

A comprehensive, reusable GPU testing framework for Java projects with automatic backend selection, performance benchmarking, and CI/CD compatibility. Built with LWJGL 3.3.6 for multi-platform GPU compute testing.

Features

• Multi-Backend Support: OpenCL, OpenGL Compute, Metal 3 (via bgfx)
• Headless Operation: Runs without display or windowing systems - perfect for CI/CD
• CI/CD Compatible: Automatic mock fallback in CI environments
• Performance Benchmarking: Built-in CPU vs GPU comparison with JMH
• Memory Analysis: Transfer overhead profiling and optimization guidance
• Cross-Validation: Ensure GPU and CPU implementations match
• Platform Detection: Automatic capability discovery across OS and architectures
• GPU Discovery: Automatic device enumeration and selection
• Graceful Degradation: Tests skip gracefully when GPU hardware is unavailable
• Mock Platform Support: Provides mock platforms when real hardware is unavailable

Architecture

Core Classes

• LWJGLHeadlessTest - Abstract base class for all LWJGL headless tests
• OpenCLHeadlessTest - OpenCL-specific base class with initialization and cleanup
• GPUComputeHeadlessTest - GPU compute testing with platform/device discovery
• CICompatibleGPUTest - CI-compatible base class with automatic OpenCL detection
• MockPlatform - Mock platform/device system for CI environments without OpenCL
• PlatformTestSupport - Utilities for platform-conditional test execution

Test Infrastructure

• HeadlessPlatformValidationTest - Platform validation (run this FIRST!)
• BasicGPUComputeTest - Example implementation showing framework usage

Quick Start

1. Run Platform Validation

First, run the platform validation test to ensure your environment is properly configured:

mvn test -Dtest=HeadlessPlatformValidationTest

Expected output on macOS M4:

=== LWJGL Headless Platform Validation ===
Platform: macOS (MACOSX)
Architecture: ARM64 (64-bit: true)
✅ Headless platform validation PASSED - Framework safe to use!

2. Basic Usage

For CI-Compatible Tests (Recommended): Extend CICompatibleGPUTest for automatic CI compatibility:

public class MyGPUTest extends CICompatibleGPUTest {
    
    @Test
    void testMyGPUKernel() {
        var platforms = discoverPlatforms();
        // CICompatibleGPUTest automatically skips when OpenCL unavailable
        
        var platform = platforms.get(0);
        var gpuDevices = discoverDevices(platform.platformId(), CL_DEVICE_TYPE_GPU);
        
        if (MockPlatform.isMockPlatform(platform)) {
            // Skip actual GPU operations with mock platforms
            log.info("Using mock platform - skipping GPU kernel test");
            return;
        }
        
        var device = gpuDevices.get(0);
        testGPUVectorAddition(platform.platformId(), device.deviceId());
    }
}

For Direct GPU Testing: Extend GPUComputeHeadlessTest with manual assumptions:

public class DirectGPUTest extends GPUComputeHeadlessTest {
    
    @Test
    void testMyGPUKernel() {
        var platforms = discoverPlatforms();
        assumeTrue(!platforms.isEmpty(), "No OpenCL platforms available");
        
        var platform = platforms.get(0);
        var gpuDevices = discoverDevices(platform.platformId(), CL_DEVICE_TYPE_GPU);
        assumeTrue(!gpuDevices.isEmpty(), "No GPU devices available");
        
        var device = gpuDevices.get(0);
        testGPUVectorAddition(platform.platformId(), device.deviceId());
    }
}

3. Platform-Specific Testing

Use PlatformTestSupport for conditional execution:

@Test
void testLinuxSpecificFeature() {
    PlatformTestSupport.requirePlatform(Platform.LINUX);
    // Test code here
}

@Test
void testWith64BitArch() {
    PlatformTestSupport.require64Bit();
    // Test code here
}

@Test 
void testSkippingARM() {
    PlatformTestSupport.skipOnARMForStackTests(); // For JVM stack tests
    // Test code here
}

Maven Integration

The framework automatically handles platform-specific native libraries:

<dependency>
    <groupId>com.hellblazer.luciferase</groupId>
    <artifactId>gpu-test-framework</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <scope>test</scope>
</dependency>

Supported Platforms

• macOS: ARM64 (Apple Silicon), x86_64 (Intel)
• Linux: AMD64, ARM64
• Windows: AMD64

Native libraries are automatically selected based on your platform.

Configuration

Maven Test Configuration

Tests run with headless configuration by default:

<systemPropertyVariables>
    <java.awt.headless>true</java.awt.headless>
    <lwjgl.opencl.explicitInit>true</lwjgl.opencl.explicitInit>
</systemPropertyVariables>

JVM Arguments

The framework sets these JVM arguments automatically:

• -Djava.awt.headless=true - Headless operation
• --add-modules jdk.incubator.vector - Vector API support
• LWJGL debug settings for memory tracking

Testing Strategy

Test Categories

1. Platform Validation - Verify LWJGL and OpenCL work on current platform
2. Device Discovery - Enumerate available compute devices
3. Compute Testing - Run actual GPU kernels with verification
4. Memory Testing - Validate memory allocation patterns

Conditional Execution

Tests use JUnit 5's @EnabledIf and Assumptions for graceful handling:

@Test
@EnabledIf("hasGPUDevice")  // Only run if GPU available
void testGPUKernel() { ... }

@Test 
void testWithGracefulFallback() {
    var devices = discoverDevices(platformId, CL_DEVICE_TYPE_GPU);
    assumeTrue(!devices.isEmpty(), "No GPU - skipping test");
    // Test code here
}

CI/CD Integration

GitHub Actions Example

- name: Run GPU Tests
  run: mvn test -Dtest="*GPUTest" 
  env:
    JAVA_TOOL_OPTIONS: -Djava.awt.headless=true

Expected Behavior

• With GPU: All tests run and validate GPU compute functionality
• Without GPU: Tests skip gracefully with informative messages
• CI Systems: Framework detects headless environment and adapts accordingly

Troubleshooting

Common Issues

1. "No OpenCL platforms found" - Normal on systems without OpenCL drivers
2. ARM64 JVM stack tests fail - Expected limitation, library functions work fine
3. macOS windowing errors - Use headless tests, or add -XstartOnFirstThread for windowing

Debug Logging

Enable debug logging for detailed GPU discovery information:

<systemPropertyVariables>
    <org.lwjgl.util.Debug>true</org.lwjgl.util.Debug>
    <org.lwjgl.util.DebugAllocator>true</org.lwjgl.util.DebugAllocator>
</systemPropertyVariables>

Platform Validation

If tests fail, first run the platform validation:

mvn test -Dtest=HeadlessPlatformValidationTest

This will provide detailed information about what's working and what isn't.

Example Output

Successful GPU discovery and testing:

[INFO] Found 1 OpenCL platform(s):
[INFO]   Apple - Apple (OpenCL 1.2 (Aug 25 2024 22:07:56))
[INFO] Found 1 device(s) on platform Apple:
[INFO]   Apple M4 [GPU] - 10 CUs, 21474.8 MB mem
[INFO] Testing GPU vector addition on: Apple M4 [GPU] - 10 CUs, 21474.8 MB mem
[INFO] ✅ GPU vector addition test PASSED - 1024 elements processed

Documentation

GPU Testing Guides

• GPU Implementation Details - Technical implementation reference for GPU testing patterns
• GPU Acceleration Guide - Setup and usage guide

Integration with Luciferase

This framework is designed for testing GPU acceleration in the Luciferase project:

• ESVO ray traversal - Efficient sparse voxel octree GPU kernels
• Spatial index operations - Parallel tree traversal and queries
• Collision detection - GPU-accelerated broad and narrow phase
• Rendering pipeline - Compute shaders for voxel rendering
• Memory bandwidth testing - Profiling large octree structures

The framework provides the foundation for testing GPU-accelerated spatial algorithms in a headless CI/CD environment.