VulkanDevice.cpp

Go to the documentation of this file.

 
#include "VulkanDevice.h"
#include <algorithm>
#include <cstring>
#include <iostream>
 
// Suppress nullability warnings from VMA header on macOS
#ifdef __clang__
#pragma clang diagnostic push
#pragma clang diagnostic ignored "-Wnullability-completeness"
#endif
#define VMA_IMPLEMENTATION
#include <vk_mem_alloc.h>
#ifdef __clang__
#pragma clang diagnostic pop
#endif
 
namespace helios {
 
    // ========== Debug messenger callback ==========
 
    static VKAPI_ATTR VkBool32 VKAPI_CALL debugCallback(VkDebugUtilsMessageSeverityFlagBitsEXT messageSeverity, VkDebugUtilsMessageTypeFlagsEXT messageType, const VkDebugUtilsMessengerCallbackDataEXT *pCallbackData, void *pUserData) {
        std::string severity_str;
        if (messageSeverity >= VK_DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT) {
            severity_str = "ERROR";
        } else if (messageSeverity >= VK_DEBUG_UTILS_MESSAGE_SEVERITY_WARNING_BIT_EXT) {
            severity_str = "WARNING";
        } else if (messageSeverity >= VK_DEBUG_UTILS_MESSAGE_SEVERITY_INFO_BIT_EXT) {
            severity_str = "INFO";
        } else {
            severity_str = "VERBOSE";
        }
 
        // Use std::cout instead of std::cerr (Helios convention)
        std::cout << "[Vulkan " << severity_str << "] " << pCallbackData->pMessage << std::endl;
 
        return VK_FALSE;
    }
 
    // ========== VulkanDevice implementation ==========
 
    VulkanDevice::VulkanDevice() = default;
 
    VulkanDevice::~VulkanDevice() {
        shutdown();
    }
 
    void VulkanDevice::initialize(bool enable_validation) {
        createInstance(enable_validation);
        selectPhysicalDevice();
        createLogicalDevice();
        createAllocator();
 
        detectMoltenVK();
        detectAtomicFloat();
 
        printDeviceInfo();
 
        // Verify actual GPU execution works (catches MoltenVK on headless CI runners)
        probeComputeCapability();
    }
 
    void VulkanDevice::shutdown() {
        if (allocator != VK_NULL_HANDLE) {
            vmaDestroyAllocator(allocator);
            allocator = VK_NULL_HANDLE;
        }
 
        if (device != VK_NULL_HANDLE) {
            vkDestroyDevice(device, nullptr);
            device = VK_NULL_HANDLE;
        }
 
        if (debug_messenger != VK_NULL_HANDLE) {
            auto func = (PFN_vkDestroyDebugUtilsMessengerEXT) vkGetInstanceProcAddr(instance, "vkDestroyDebugUtilsMessengerEXT");
            if (func != nullptr) {
                func(instance, debug_messenger, nullptr);
            }
            debug_messenger = VK_NULL_HANDLE;
        }
 
        if (instance != VK_NULL_HANDLE) {
            vkDestroyInstance(instance, nullptr);
            instance = VK_NULL_HANDLE;
        }
    }
 
    void VulkanDevice::createInstance(bool enable_validation) {
        VkApplicationInfo app_info{};
        app_info.sType = VK_STRUCTURE_TYPE_APPLICATION_INFO;
        app_info.pApplicationName = "Helios Radiation Plugin";
        app_info.applicationVersion = VK_MAKE_VERSION(1, 3, 0);
        app_info.pEngineName = "Helios";
        app_info.engineVersion = VK_MAKE_VERSION(1, 3, 0);
        app_info.apiVersion = VK_API_VERSION_1_1;
 
        VkInstanceCreateInfo create_info{};
        create_info.sType = VK_STRUCTURE_TYPE_INSTANCE_CREATE_INFO;
        create_info.pApplicationInfo = &app_info;
 
        // Required extensions (none for headless compute)
        std::vector<const char *> extensions;
 
        // MoltenVK requires VK_KHR_portability_enumeration on macOS
#ifdef __APPLE__
        extensions.push_back(VK_KHR_PORTABILITY_ENUMERATION_EXTENSION_NAME);
        extensions.push_back(VK_KHR_GET_PHYSICAL_DEVICE_PROPERTIES_2_EXTENSION_NAME);
        create_info.flags |= VK_INSTANCE_CREATE_ENUMERATE_PORTABILITY_BIT_KHR;
#endif
 
        // Try with validation first if requested
        std::vector<const char *> validation_layers;
        bool validation_enabled = false;
 
        if (enable_validation) {
            validation_layers.push_back("VK_LAYER_KHRONOS_validation");
            extensions.push_back(VK_EXT_DEBUG_UTILS_EXTENSION_NAME);
 
            create_info.enabledExtensionCount = static_cast<uint32_t>(extensions.size());
            create_info.ppEnabledExtensionNames = extensions.data();
            create_info.enabledLayerCount = static_cast<uint32_t>(validation_layers.size());
            create_info.ppEnabledLayerNames = validation_layers.data();
 
            VkResult result = vkCreateInstance(&create_info, nullptr, &instance);
 
            if (result == VK_SUCCESS) {
                validation_enabled = true;
            } else if (result == VK_ERROR_LAYER_NOT_PRESENT || result == VK_ERROR_EXTENSION_NOT_PRESENT) {
                // Validation not available, try without it
                extensions.pop_back(); // Remove debug utils extension
            } else {
                // Other error - fail
                helios_runtime_error("ERROR (VulkanDevice::createInstance): Failed to create Vulkan instance. "
                                     "Make sure Vulkan SDK is installed. VkResult code: " +
                                     std::to_string(result));
            }
        }
 
        // Create instance without validation if not already created
        if (instance == VK_NULL_HANDLE) {
            create_info.enabledExtensionCount = static_cast<uint32_t>(extensions.size());
            create_info.ppEnabledExtensionNames = extensions.data();
            create_info.enabledLayerCount = 0;
            create_info.ppEnabledLayerNames = nullptr;
 
            VkResult result = vkCreateInstance(&create_info, nullptr, &instance);
            if (result != VK_SUCCESS) {
                helios_runtime_error("ERROR (VulkanDevice::createInstance): Failed to create Vulkan instance. "
                                     "Make sure Vulkan SDK is installed. VkResult code: " +
                                     std::to_string(result));
            }
        }
 
        if (validation_enabled) {
            setupDebugMessenger();
        }
    }
 
    void VulkanDevice::setupDebugMessenger() {
        VkDebugUtilsMessengerCreateInfoEXT create_info{};
        create_info.sType = VK_STRUCTURE_TYPE_DEBUG_UTILS_MESSENGER_CREATE_INFO_EXT;
        create_info.messageSeverity = VK_DEBUG_UTILS_MESSAGE_SEVERITY_WARNING_BIT_EXT | VK_DEBUG_UTILS_MESSAGE_SEVERITY_ERROR_BIT_EXT;
        create_info.messageType = VK_DEBUG_UTILS_MESSAGE_TYPE_GENERAL_BIT_EXT | VK_DEBUG_UTILS_MESSAGE_TYPE_VALIDATION_BIT_EXT | VK_DEBUG_UTILS_MESSAGE_TYPE_PERFORMANCE_BIT_EXT;
        create_info.pfnUserCallback = debugCallback;
 
        auto func = (PFN_vkCreateDebugUtilsMessengerEXT) vkGetInstanceProcAddr(instance, "vkCreateDebugUtilsMessengerEXT");
        if (func != nullptr) {
            func(instance, &create_info, nullptr, &debug_messenger);
        }
    }
 
    void VulkanDevice::selectPhysicalDevice() {
        uint32_t device_count = 0;
        VkResult result = vkEnumeratePhysicalDevices(instance, &device_count, nullptr);
 
        // Check for enumeration errors first
        if (result != VK_SUCCESS) {
            std::stringstream error_msg;
            error_msg << "ERROR (VulkanDevice::selectPhysicalDevice): "
                      << "Failed to enumerate physical devices (VkResult: " << result << ")\n"
                      << "This indicates a driver installation or compatibility issue.";
            helios_runtime_error(error_msg.str());
        }
 
        if (device_count == 0) {
            // Provide detailed diagnostic information
            std::stringstream diagnostic;
            diagnostic << "ERROR (VulkanDevice::selectPhysicalDevice): "
                       << "No Vulkan-capable GPU found.\n\n";
 
            // Show environment state
            const char *icd_filenames = std::getenv("VK_ICD_FILENAMES");
            const char *loader_debug = std::getenv("VK_LOADER_DEBUG");
 
            diagnostic << "=== Environment ===\n";
            diagnostic << "VK_ICD_FILENAMES: " << (icd_filenames ? icd_filenames : "(using system default)") << "\n";
            diagnostic << "VK_LOADER_DEBUG: " << (loader_debug ? loader_debug : "(not set)") << "\n\n";
 
            diagnostic << "=== Possible Causes ===\n";
            diagnostic << "1. Vulkan driver library version mismatch (common with mixed compiler environments)\n";
            diagnostic << "2. Incompatible ICD files failing to load (check for GLIBCXX errors)\n";
            diagnostic << "3. GPU does not support Vulkan 1.1 or higher\n";
            diagnostic << "4. Vulkan loader contamination from failed ICD loading attempts\n\n";
 
            diagnostic << "=== Troubleshooting Steps ===\n";
            diagnostic << "1. Check driver loading:\n";
            diagnostic << "   ldd /usr/lib/x86_64-linux-gnu/libvulkan_*.so\n";
            diagnostic << "2. Debug Vulkan loader:\n";
            diagnostic << "   VK_LOADER_DEBUG=all vulkaninfo --summary\n";
            diagnostic << "3. Filter working ICDs:\n";
            diagnostic << "   export VK_ICD_FILENAMES=/path/to/working_icd.json\n";
            diagnostic << "4. Verify GPU Vulkan support:\n";
            diagnostic << "   vulkaninfo | grep 'apiVersion'\n";
 
            helios_runtime_error(diagnostic.str());
        }
 
        std::vector<VkPhysicalDevice> devices(device_count);
        vkEnumeratePhysicalDevices(instance, &device_count, devices.data());
 
        // Score devices and select the best one
        uint32_t best_score = 0;
        VkPhysicalDevice best_device = VK_NULL_HANDLE;
 
        for (const auto &device_candidate: devices) {
            if (!isDeviceSuitable(device_candidate)) {
                continue;
            }
 
            uint32_t score = scorePhysicalDevice(device_candidate);
            if (score > best_score) {
                best_score = score;
                best_device = device_candidate;
            }
        }
 
        if (best_device == VK_NULL_HANDLE) {
            helios_runtime_error("ERROR (VulkanDevice::selectPhysicalDevice): No suitable Vulkan device found. "
                                 "GPU must support compute queues and Vulkan 1.1.");
        }
 
        physical_device = best_device;
        vkGetPhysicalDeviceProperties(physical_device, &device_properties);
    }
 
    bool VulkanDevice::isDeviceSuitable(VkPhysicalDevice device_candidate) const {
        // Must have compute queue
        uint32_t queue_family = findComputeQueueFamily(device_candidate);
        if (queue_family == UINT32_MAX) {
            return false;
        }
 
        // Must support Vulkan 1.1 minimum
        VkPhysicalDeviceProperties props;
        vkGetPhysicalDeviceProperties(device_candidate, &props);
        if (props.apiVersion < VK_API_VERSION_1_1) {
            return false;
        }
 
        return true;
    }
 
    uint32_t VulkanDevice::scorePhysicalDevice(VkPhysicalDevice device_candidate) const {
        VkPhysicalDeviceProperties props;
        vkGetPhysicalDeviceProperties(device_candidate, &props);
 
        uint32_t score = 0;
 
        // Discrete GPUs have a huge performance advantage
        if (props.deviceType == VK_PHYSICAL_DEVICE_TYPE_DISCRETE_GPU) {
            score += 10000;
        } else if (props.deviceType == VK_PHYSICAL_DEVICE_TYPE_INTEGRATED_GPU) {
            score += 1000;
        }
 
        // Prefer newer Vulkan API versions
        score += VK_VERSION_MAJOR(props.apiVersion) * 100 + VK_VERSION_MINOR(props.apiVersion) * 10;
 
        return score;
    }
 
    uint32_t VulkanDevice::findComputeQueueFamily(VkPhysicalDevice device_candidate) const {
        uint32_t queue_family_count = 0;
        vkGetPhysicalDeviceQueueFamilyProperties(device_candidate, &queue_family_count, nullptr);
 
        std::vector<VkQueueFamilyProperties> queue_families(queue_family_count);
        vkGetPhysicalDeviceQueueFamilyProperties(device_candidate, &queue_family_count, queue_families.data());
 
        for (uint32_t i = 0; i < queue_family_count; i++) {
            if (queue_families[i].queueFlags & VK_QUEUE_COMPUTE_BIT) {
                return i;
            }
        }
 
        return UINT32_MAX;
    }
 
    void VulkanDevice::createLogicalDevice() {
        compute_queue_family = findComputeQueueFamily(physical_device);
 
        VkDeviceQueueCreateInfo queue_create_info{};
        queue_create_info.sType = VK_STRUCTURE_TYPE_DEVICE_QUEUE_CREATE_INFO;
        queue_create_info.queueFamilyIndex = compute_queue_family;
        queue_create_info.queueCount = 1;
        float queue_priority = 1.0f;
        queue_create_info.pQueuePriorities = &queue_priority;
 
        VkPhysicalDeviceFeatures device_features{};
        // No special features required for baseline compute
 
        // Check and enable atomic float if available (needed for atomicAdd in shaders)
        VkPhysicalDeviceShaderAtomicFloatFeaturesEXT atomic_float_features{};
        atomic_float_features.sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_ATOMIC_FLOAT_FEATURES_EXT;
        atomic_float_features.pNext = nullptr;
 
        VkPhysicalDeviceFeatures2 features2{};
        features2.sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FEATURES_2;
        features2.pNext = &atomic_float_features;
        features2.features = device_features;
 
        // Query if atomic float is supported
        vkGetPhysicalDeviceFeatures2(physical_device, &features2);
 
        bool enable_atomic_float = atomic_float_features.shaderBufferFloat32AtomicAdd;
 
        VkDeviceCreateInfo create_info{};
        create_info.sType = VK_STRUCTURE_TYPE_DEVICE_CREATE_INFO;
        create_info.pQueueCreateInfos = &queue_create_info;
        create_info.queueCreateInfoCount = 1;
 
        // Required device extensions
        std::vector<const char *> device_extensions;
 
#ifdef __APPLE__
        // MoltenVK requires portability subset extension
        device_extensions.push_back("VK_KHR_portability_subset");
#endif
 
        // Enable atomic float extension if supported
        if (enable_atomic_float) {
            device_extensions.push_back(VK_EXT_SHADER_ATOMIC_FLOAT_EXTENSION_NAME);
            // Enable the feature via pNext chain
            atomic_float_features.shaderBufferFloat32AtomicAdd = VK_TRUE;
            create_info.pNext = &features2;
            create_info.pEnabledFeatures = nullptr; // Use features2 instead
        } else {
            create_info.pEnabledFeatures = &device_features;
        }
 
        create_info.enabledExtensionCount = static_cast<uint32_t>(device_extensions.size());
        create_info.ppEnabledExtensionNames = device_extensions.data();
 
        VkResult result = vkCreateDevice(physical_device, &create_info, nullptr, &device);
        if (result != VK_SUCCESS) {
            helios_runtime_error("ERROR (VulkanDevice::createLogicalDevice): Failed to create logical device. "
                                 "VkResult code: " +
                                 std::to_string(result));
        }
 
        vkGetDeviceQueue(device, compute_queue_family, 0, &compute_queue);
    }
 
    void VulkanDevice::createAllocator() {
        VmaAllocatorCreateInfo allocator_info{};
        allocator_info.vulkanApiVersion = VK_API_VERSION_1_1;
        allocator_info.physicalDevice = physical_device;
        allocator_info.device = device;
        allocator_info.instance = instance;
 
        VkResult result = vmaCreateAllocator(&allocator_info, &allocator);
        if (result != VK_SUCCESS) {
            helios_runtime_error("ERROR (VulkanDevice::createAllocator): Failed to create VMA allocator. "
                                 "VkResult code: " +
                                 std::to_string(result));
        }
    }
 
    void VulkanDevice::detectMoltenVK() {
        // Method 1: Check for Apple vendor ID (0x106B)
        if (device_properties.vendorID == 0x106B) {
            is_moltenvk = true;
            return;
        }
 
        // Method 2: Check for MoltenVK-specific extension
        uint32_t ext_count;
        vkEnumerateDeviceExtensionProperties(physical_device, nullptr, &ext_count, nullptr);
        std::vector<VkExtensionProperties> exts(ext_count);
        vkEnumerateDeviceExtensionProperties(physical_device, nullptr, &ext_count, exts.data());
 
        for (const auto &ext: exts) {
            if (std::strcmp(ext.extensionName, "VK_MVK_moltenvk") == 0) {
                is_moltenvk = true;
                return;
            }
        }
 
        // Method 3: Fallback to device name check
        const char *device_name = device_properties.deviceName;
        is_moltenvk = (std::strstr(device_name, "MoltenVK") != nullptr);
    }
 
    void VulkanDevice::detectAtomicFloat() {
        // First check if VK_EXT_shader_atomic_float extension is available
        uint32_t ext_count;
        vkEnumerateDeviceExtensionProperties(physical_device, nullptr, &ext_count, nullptr);
        std::vector<VkExtensionProperties> exts(ext_count);
        vkEnumerateDeviceExtensionProperties(physical_device, nullptr, &ext_count, exts.data());
 
        bool has_extension = false;
        for (const auto &ext: exts) {
            if (std::strcmp(ext.extensionName, VK_EXT_SHADER_ATOMIC_FLOAT_EXTENSION_NAME) == 0) {
                has_extension = true;
                break;
            }
        }
 
        if (!has_extension) {
            has_atomic_float = false;
            return; // Extension not available, use atomicCompSwap fallback
        }
 
        // Extension present, query features
        VkPhysicalDeviceShaderAtomicFloatFeaturesEXT atomic_float_features{};
        atomic_float_features.sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_SHADER_ATOMIC_FLOAT_FEATURES_EXT;
 
        VkPhysicalDeviceFeatures2 features2{};
        features2.sType = VK_STRUCTURE_TYPE_PHYSICAL_DEVICE_FEATURES_2;
        features2.pNext = &atomic_float_features;
 
        vkGetPhysicalDeviceFeatures2(physical_device, &features2);
 
        has_atomic_float = atomic_float_features.shaderBufferFloat32AtomicAdd;
    }
 
    void VulkanDevice::probeComputeCapability() {
        // Dispatch a compute shader that writes to a storage buffer, then read it back.
        // This verifies the device can actually execute GPU compute work with memory access.
        //
        // A no-op shader (void main(){}) is NOT sufficient: MoltenVK on macOS CI runners
        // (Apple Silicon VMs via Virtualization.framework) can dispatch trivial shaders
        // that touch no memory, but fail with VK_ERROR_DEVICE_LOST when a shader reads
        // or writes storage buffers — which is what the real radiation shaders do.
        //
        // This probe exercises the same code path: descriptor set + storage buffer + write.
 
        // Embedded SPIR-V for:
        //   #version 450
        //   layout(local_size_x = 1) in;
        //   layout(set = 0, binding = 0) buffer ProbeBuffer { uint data[]; } buf;
        //   void main() { buf.data[0] = 42u; }
        // Compiled with glslangValidator -V. 568 bytes, 142 words.
        static const uint32_t probe_spirv[] = {
            0x07230203, 0x00010000, 0x0008000b, 0x00000013,
            0x00000000, 0x00020011, 0x00000001, 0x0006000b,
            0x00000001, 0x4c534c47, 0x6474732e, 0x3035342e,
            0x00000000, 0x0003000e, 0x00000000, 0x00000001,
            0x0005000f, 0x00000005, 0x00000004, 0x6e69616d,
            0x00000000, 0x00060010, 0x00000004, 0x00000011,
            0x00000001, 0x00000001, 0x00000001, 0x00030003,
            0x00000002, 0x000001c2, 0x00040005, 0x00000004,
            0x6e69616d, 0x00000000, 0x00050005, 0x00000008,
            0x626f7250, 0x66754265, 0x00726566, 0x00050006,
            0x00000008, 0x00000000, 0x61746164, 0x00000000,
            0x00030005, 0x0000000a, 0x00667562, 0x00040047,
            0x00000007, 0x00000006, 0x00000004, 0x00030047,
            0x00000008, 0x00000003, 0x00050048, 0x00000008,
            0x00000000, 0x00000023, 0x00000000, 0x00040047,
            0x0000000a, 0x00000021, 0x00000000, 0x00040047,
            0x0000000a, 0x00000022, 0x00000000, 0x00040047,
            0x00000012, 0x0000000b, 0x00000019, 0x00020013,
            0x00000002, 0x00030021, 0x00000003, 0x00000002,
            0x00040015, 0x00000006, 0x00000020, 0x00000000,
            0x0003001d, 0x00000007, 0x00000006, 0x0003001e,
            0x00000008, 0x00000007, 0x00040020, 0x00000009,
            0x00000002, 0x00000008, 0x0004003b, 0x00000009,
            0x0000000a, 0x00000002, 0x00040015, 0x0000000b,
            0x00000020, 0x00000001, 0x0004002b, 0x0000000b,
            0x0000000c, 0x00000000, 0x0004002b, 0x00000006,
            0x0000000d, 0x0000002a, 0x00040020, 0x0000000e,
            0x00000002, 0x00000006, 0x00040017, 0x00000010,
            0x00000006, 0x00000003, 0x0004002b, 0x00000006,
            0x00000011, 0x00000001, 0x0006002c, 0x00000010,
            0x00000012, 0x00000011, 0x00000011, 0x00000011,
            0x00050036, 0x00000002, 0x00000004, 0x00000000,
            0x00000003, 0x000200f8, 0x00000005, 0x00060041,
            0x0000000e, 0x0000000f, 0x0000000a, 0x0000000c,
            0x0000000c, 0x0003003e, 0x0000000f, 0x0000000d,
            0x000100fd, 0x00010038,
        };
        static const size_t probe_spirv_size = sizeof(probe_spirv);
 
        // Vulkan handles for cleanup
        VkCommandPool probe_pool = VK_NULL_HANDLE;
        VkCommandBuffer probe_cmd = VK_NULL_HANDLE;
        VkFence probe_fence = VK_NULL_HANDLE;
        VkShaderModule probe_shader = VK_NULL_HANDLE;
        VkPipelineLayout probe_layout = VK_NULL_HANDLE;
        VkPipeline probe_pipeline = VK_NULL_HANDLE;
        VkDescriptorSetLayout probe_set_layout = VK_NULL_HANDLE;
        VkDescriptorPool probe_desc_pool = VK_NULL_HANDLE;
        VkDescriptorSet probe_desc_set = VK_NULL_HANDLE;
        VkBuffer probe_buffer = VK_NULL_HANDLE;
        VmaAllocation probe_alloc = VK_NULL_HANDLE;
 
        auto cleanup = [&]() {
            if (probe_pipeline != VK_NULL_HANDLE) vkDestroyPipeline(device, probe_pipeline, nullptr);
            if (probe_layout != VK_NULL_HANDLE) vkDestroyPipelineLayout(device, probe_layout, nullptr);
            if (probe_shader != VK_NULL_HANDLE) vkDestroyShaderModule(device, probe_shader, nullptr);
            if (probe_desc_pool != VK_NULL_HANDLE) vkDestroyDescriptorPool(device, probe_desc_pool, nullptr);
            if (probe_set_layout != VK_NULL_HANDLE) vkDestroyDescriptorSetLayout(device, probe_set_layout, nullptr);
            if (probe_buffer != VK_NULL_HANDLE) vmaDestroyBuffer(allocator, probe_buffer, probe_alloc);
            if (probe_fence != VK_NULL_HANDLE) vkDestroyFence(device, probe_fence, nullptr);
            if (probe_pool != VK_NULL_HANDLE) vkDestroyCommandPool(device, probe_pool, nullptr);
        };
 
        // 1. Create storage buffer (4 bytes, host-visible for readback)
        VkBufferCreateInfo buf_info{};
        buf_info.sType = VK_STRUCTURE_TYPE_BUFFER_CREATE_INFO;
        buf_info.size = sizeof(uint32_t);
        buf_info.usage = VK_BUFFER_USAGE_STORAGE_BUFFER_BIT;
        buf_info.sharingMode = VK_SHARING_MODE_EXCLUSIVE;
 
        VmaAllocationCreateInfo vma_info{};
        vma_info.usage = VMA_MEMORY_USAGE_AUTO;
        vma_info.flags = VMA_ALLOCATION_CREATE_HOST_ACCESS_RANDOM_BIT | VMA_ALLOCATION_CREATE_MAPPED_BIT;
 
        VmaAllocationInfo alloc_result{};
        VkResult result = vmaCreateBuffer(allocator, &buf_info, &vma_info, &probe_buffer, &probe_alloc, &alloc_result);
        if (result != VK_SUCCESS) {
            cleanup();
            helios_runtime_error("ERROR (VulkanDevice::probeComputeCapability): Failed to create probe buffer. "
                                 "VkResult code: " + std::to_string(result));
        }
 
        // Zero the buffer so we can verify the shader wrote to it
        *static_cast<uint32_t *>(alloc_result.pMappedData) = 0;
 
        // 2. Create descriptor set layout (one storage buffer at binding 0)
        VkDescriptorSetLayoutBinding binding{};
        binding.binding = 0;
        binding.descriptorType = VK_DESCRIPTOR_TYPE_STORAGE_BUFFER;
        binding.descriptorCount = 1;
        binding.stageFlags = VK_SHADER_STAGE_COMPUTE_BIT;
 
        VkDescriptorSetLayoutCreateInfo set_layout_info{};
        set_layout_info.sType = VK_STRUCTURE_TYPE_DESCRIPTOR_SET_LAYOUT_CREATE_INFO;
        set_layout_info.bindingCount = 1;
        set_layout_info.pBindings = &binding;
 
        result = vkCreateDescriptorSetLayout(device, &set_layout_info, nullptr, &probe_set_layout);
        if (result != VK_SUCCESS) {
            cleanup();
            helios_runtime_error("ERROR (VulkanDevice::probeComputeCapability): Failed to create descriptor set layout. "
                                 "VkResult code: " + std::to_string(result));
        }
 
        // 3. Create descriptor pool and allocate set
        VkDescriptorPoolSize pool_size{};
        pool_size.type = VK_DESCRIPTOR_TYPE_STORAGE_BUFFER;
        pool_size.descriptorCount = 1;
 
        VkDescriptorPoolCreateInfo desc_pool_info{};
        desc_pool_info.sType = VK_STRUCTURE_TYPE_DESCRIPTOR_POOL_CREATE_INFO;
        desc_pool_info.maxSets = 1;
        desc_pool_info.poolSizeCount = 1;
        desc_pool_info.pPoolSizes = &pool_size;
 
        result = vkCreateDescriptorPool(device, &desc_pool_info, nullptr, &probe_desc_pool);
        if (result != VK_SUCCESS) {
            cleanup();
            helios_runtime_error("ERROR (VulkanDevice::probeComputeCapability): Failed to create descriptor pool. "
                                 "VkResult code: " + std::to_string(result));
        }
 
        VkDescriptorSetAllocateInfo desc_alloc_info{};
        desc_alloc_info.sType = VK_STRUCTURE_TYPE_DESCRIPTOR_SET_ALLOCATE_INFO;
        desc_alloc_info.descriptorPool = probe_desc_pool;
        desc_alloc_info.descriptorSetCount = 1;
        desc_alloc_info.pSetLayouts = &probe_set_layout;
 
        result = vkAllocateDescriptorSets(device, &desc_alloc_info, &probe_desc_set);
        if (result != VK_SUCCESS) {
            cleanup();
            helios_runtime_error("ERROR (VulkanDevice::probeComputeCapability): Failed to allocate descriptor set. "
                                 "VkResult code: " + std::to_string(result));
        }
 
        // 4. Update descriptor set to point to the buffer
        VkDescriptorBufferInfo desc_buf_info{};
        desc_buf_info.buffer = probe_buffer;
        desc_buf_info.offset = 0;
        desc_buf_info.range = VK_WHOLE_SIZE;
 
        VkWriteDescriptorSet write{};
        write.sType = VK_STRUCTURE_TYPE_WRITE_DESCRIPTOR_SET;
        write.dstSet = probe_desc_set;
        write.dstBinding = 0;
        write.descriptorCount = 1;
        write.descriptorType = VK_DESCRIPTOR_TYPE_STORAGE_BUFFER;
        write.pBufferInfo = &desc_buf_info;
 
        vkUpdateDescriptorSets(device, 1, &write, 0, nullptr);
 
        // 5. Create shader module from embedded SPIR-V
        VkShaderModuleCreateInfo shader_info{};
        shader_info.sType = VK_STRUCTURE_TYPE_SHADER_MODULE_CREATE_INFO;
        shader_info.codeSize = probe_spirv_size;
        shader_info.pCode = probe_spirv;
 
        result = vkCreateShaderModule(device, &shader_info, nullptr, &probe_shader);
        if (result != VK_SUCCESS) {
            cleanup();
            helios_runtime_error("ERROR (VulkanDevice::probeComputeCapability): Failed to create probe shader module. "
                                 "VkResult code: " + std::to_string(result));
        }
 
        // 6. Create pipeline layout with descriptor set layout, and compute pipeline
        VkPipelineLayoutCreateInfo layout_create_info{};
        layout_create_info.sType = VK_STRUCTURE_TYPE_PIPELINE_LAYOUT_CREATE_INFO;
        layout_create_info.setLayoutCount = 1;
        layout_create_info.pSetLayouts = &probe_set_layout;
 
        result = vkCreatePipelineLayout(device, &layout_create_info, nullptr, &probe_layout);
        if (result != VK_SUCCESS) {
            cleanup();
            helios_runtime_error("ERROR (VulkanDevice::probeComputeCapability): Failed to create probe pipeline layout. "
                                 "VkResult code: " + std::to_string(result));
        }
 
        VkComputePipelineCreateInfo pipeline_info{};
        pipeline_info.sType = VK_STRUCTURE_TYPE_COMPUTE_PIPELINE_CREATE_INFO;
        pipeline_info.stage.sType = VK_STRUCTURE_TYPE_PIPELINE_SHADER_STAGE_CREATE_INFO;
        pipeline_info.stage.stage = VK_SHADER_STAGE_COMPUTE_BIT;
        pipeline_info.stage.module = probe_shader;
        pipeline_info.stage.pName = "main";
        pipeline_info.layout = probe_layout;
 
        result = vkCreateComputePipelines(device, VK_NULL_HANDLE, 1, &pipeline_info, nullptr, &probe_pipeline);
        if (result != VK_SUCCESS) {
            cleanup();
            helios_runtime_error("ERROR (VulkanDevice::probeComputeCapability): Failed to create probe compute pipeline. "
                                 "VkResult code: " + std::to_string(result));
        }
 
        // 7. Create command pool and record dispatch with bound descriptor set
        VkCommandPoolCreateInfo pool_create_info{};
        pool_create_info.sType = VK_STRUCTURE_TYPE_COMMAND_POOL_CREATE_INFO;
        pool_create_info.queueFamilyIndex = compute_queue_family;
        pool_create_info.flags = VK_COMMAND_POOL_CREATE_TRANSIENT_BIT;
 
        result = vkCreateCommandPool(device, &pool_create_info, nullptr, &probe_pool);
        if (result != VK_SUCCESS) {
            cleanup();
            helios_runtime_error("ERROR (VulkanDevice::probeComputeCapability): Failed to create command pool. "
                                 "VkResult code: " + std::to_string(result));
        }
 
        VkCommandBufferAllocateInfo cmd_alloc_info{};
        cmd_alloc_info.sType = VK_STRUCTURE_TYPE_COMMAND_BUFFER_ALLOCATE_INFO;
        cmd_alloc_info.commandPool = probe_pool;
        cmd_alloc_info.level = VK_COMMAND_BUFFER_LEVEL_PRIMARY;
        cmd_alloc_info.commandBufferCount = 1;
 
        result = vkAllocateCommandBuffers(device, &cmd_alloc_info, &probe_cmd);
        if (result != VK_SUCCESS) {
            cleanup();
            helios_runtime_error("ERROR (VulkanDevice::probeComputeCapability): Failed to allocate command buffer. "
                                 "VkResult code: " + std::to_string(result));
        }
 
        VkCommandBufferBeginInfo begin_info{};
        begin_info.sType = VK_STRUCTURE_TYPE_COMMAND_BUFFER_BEGIN_INFO;
        begin_info.flags = VK_COMMAND_BUFFER_USAGE_ONE_TIME_SUBMIT_BIT;
 
        vkBeginCommandBuffer(probe_cmd, &begin_info);
        vkCmdBindPipeline(probe_cmd, VK_PIPELINE_BIND_POINT_COMPUTE, probe_pipeline);
        vkCmdBindDescriptorSets(probe_cmd, VK_PIPELINE_BIND_POINT_COMPUTE, probe_layout, 0, 1, &probe_desc_set, 0, nullptr);
        vkCmdDispatch(probe_cmd, 1, 1, 1); // Single workgroup, writes buf.data[0] = 42
        vkEndCommandBuffer(probe_cmd);
 
        // 8. Create fence, submit, and wait
        VkFenceCreateInfo fence_info{};
        fence_info.sType = VK_STRUCTURE_TYPE_FENCE_CREATE_INFO;
 
        result = vkCreateFence(device, &fence_info, nullptr, &probe_fence);
        if (result != VK_SUCCESS) {
            cleanup();
            helios_runtime_error("ERROR (VulkanDevice::probeComputeCapability): Failed to create fence. "
                                 "VkResult code: " + std::to_string(result));
        }
 
        VkSubmitInfo submit_info{};
        submit_info.sType = VK_STRUCTURE_TYPE_SUBMIT_INFO;
        submit_info.commandBufferCount = 1;
        submit_info.pCommandBuffers = &probe_cmd;
 
        result = vkQueueSubmit(compute_queue, 1, &submit_info, probe_fence);
        if (result != VK_SUCCESS) {
            cleanup();
            helios_runtime_error("ERROR (VulkanDevice::probeComputeCapability): Compute dispatch submission failed. "
                                 "VkResult code: " + std::to_string(result));
        }
 
        // Poll with timeout (MoltenVK doesn't always respect the timeout parameter)
        bool completed = false;
        for (int attempt = 0; attempt < 50; ++attempt) {
            result = vkWaitForFences(device, 1, &probe_fence, VK_TRUE, 100000000ULL); // 100ms per poll
            if (result == VK_SUCCESS) {
                completed = true;
                break;
            } else if (result != VK_TIMEOUT) {
                cleanup();
                helios_runtime_error("ERROR (VulkanDevice::probeComputeCapability): GPU compute probe failed. "
                                     "The Vulkan device was created but cannot execute compute shaders "
                                     "(common on CI runners or systems without full GPU compute support). "
                                     "VkResult code: " + std::to_string(result));
            }
        }
 
        if (!completed) {
            cleanup();
            helios_runtime_error("ERROR (VulkanDevice::probeComputeCapability): GPU compute probe timed out after 5 seconds.");
        }
 
        // 9. Verify the shader actually wrote to the buffer
        uint32_t readback = *static_cast<uint32_t *>(alloc_result.pMappedData);
        cleanup();
 
        if (readback != 42) {
            helios_runtime_error("ERROR (VulkanDevice::probeComputeCapability): GPU compute probe produced wrong result "
                                 "(expected 42, got " + std::to_string(readback) + "). "
                                 "The GPU may not support compute shader storage buffer writes.");
        }
    }
 
    void VulkanDevice::printDeviceInfo() const {
        // Device info is not printed during normal operation
    }
 
} // namespace helios