[hipDNN] Plugin SDK + Device Properties Infrastructure (RFC 0007 - Part 1/3)

projects/hipdnn/backend/src/CMakeLists.txt

@@ -53,8 +53,11 @@ add_library(
     logging/GraphLogger.cpp
     logging/Logging.cpp
     FlatbufferUtilities.cpp
+    heuristics/DeviceProperties.cpp
     plugin/EnginePlugin.cpp
     plugin/EnginePluginResourceManager.cpp
+    plugin/HeuristicPlugin.cpp
+    plugin/HeuristicPluginResourceManager.cpp
     plugin/PluginCore.cpp
     plugin/SharedLibrary.cpp
     utilities/EngineOrdering.cpp

projects/hipdnn/backend/src/handle/Handle.cpp

@@ -8,6 +8,7 @@ using namespace hipdnn_backend::plugin;
 
 hipdnnHandle::hipdnnHandle()
     : _pluginResourceManager(EnginePluginResourceManager::create())
+    , _heuristicPluginResourceManager(HeuristicPluginResourceManager::create())
 {
 }
 
@@ -27,6 +28,12 @@ std::shared_ptr<EnginePluginResourceManager> hipdnnHandle::getPluginResourceMana
     return _pluginResourceManager;
 }
 
+std::shared_ptr<HeuristicPluginResourceManager>
+    hipdnnHandle::getHeuristicPluginResourceManager() const
+{
+    return _heuristicPluginResourceManager;
+}
+
 size_t hipdnnHandle::getEngineCount() const
 {
     return _pluginResourceManager->getEngineCount();

projects/hipdnn/backend/src/handle/Handle.hpp

@@ -4,6 +4,7 @@
 #pragma once
 
 #include "plugin/EnginePluginResourceManager.hpp"
+#include "plugin/HeuristicPluginResourceManager.hpp"
 #include <cstdint>
 #include <hip/hip_runtime.h>
 #include <memory>
@@ -20,13 +21,17 @@ struct hipdnnHandle // NOLINT
     virtual hipStream_t getStream() const;
     virtual std::shared_ptr<hipdnn_backend::plugin::EnginePluginResourceManager>
         getPluginResourceManager() const;
+    virtual std::shared_ptr<hipdnn_backend::plugin::HeuristicPluginResourceManager>
+        getHeuristicPluginResourceManager() const;
     virtual size_t getEngineCount() const;
     virtual std::vector<hipdnn_backend::plugin::EngineInfo> getEngineInfos() const;
     virtual std::string toString() const;
 
 private:
     hipStream_t _stream = nullptr;
     std::shared_ptr<hipdnn_backend::plugin::EnginePluginResourceManager> _pluginResourceManager;
+    std::shared_ptr<hipdnn_backend::plugin::HeuristicPluginResourceManager>
+        _heuristicPluginResourceManager;
 };
 
 template <>

projects/hipdnn/backend/src/heuristics/DeviceProperties.cpp

@@ -0,0 +1,106 @@
+// Copyright © Advanced Micro Devices, Inc., or its affiliates.
+// SPDX-License-Identifier:  MIT
+
+#include "DeviceProperties.hpp"
+
+#include <hip/hip_runtime.h>
+
+#include <flatbuffers/flatbuffers.h>
+#include <flatbuffers/verifier.h>
+
+#include "HipdnnException.hpp"
+#include "logging/Logging.hpp"
+
+// Include generated FlatBuffer header
+#include <hipdnn_data_sdk/data_objects/device_properties_generated.h>
+
+namespace hipdnn_backend::heuristics
+{
+
+DeviceProperties queryDeviceProperties()
+{
+    DeviceProperties out{};
+
+    // Get current device
+    int device = 0;
+    hipError_t err = hipGetDevice(&device);
+    if(err != hipSuccess)
+    {
+        HIPDNN_BACKEND_LOG_WARN("hipGetDevice failed: {}. Using default device properties.",
+                                hipGetErrorString(err));
+        return out;
+    }
+    out.deviceId = device;
+
+    // Get device properties
+    hipDeviceProp_t hipProps{};
+    err = hipGetDeviceProperties(&hipProps, device);
+    if(err != hipSuccess)
+    {
+        HIPDNN_BACKEND_LOG_WARN(
+            "hipGetDeviceProperties failed: {}. Using partial device properties.",
+            hipGetErrorString(err));
+        return out;
+    }
+
+    out.multiProcessorCount = hipProps.multiProcessorCount;
+    out.totalGlobalMem = hipProps.totalGlobalMem;
+
+    HIPDNN_BACKEND_LOG_DEBUG(
+        "Queried device properties: deviceId={}, multiProcessorCount={}, totalGlobalMem={} bytes",
+        out.deviceId,
+        out.multiProcessorCount,
+        out.totalGlobalMem);
+
+    return out;
+}
+
+std::vector<uint8_t> serializeDeviceProperties(const DeviceProperties& props)
+{
+    flatbuffers::FlatBufferBuilder builder(256);
+
+    // Build the DeviceProperties table
+    auto devicePropsOffset = hipdnn_data_sdk::data_objects::CreateDeviceProperties(
+        builder, props.deviceId, props.multiProcessorCount, props.totalGlobalMem);
+
+    builder.Finish(devicePropsOffset, "HDDP"); // File identifier for versioning
+
+    // Copy to vector
+    uint8_t* buf = builder.GetBufferPointer();
+    const size_t size = builder.GetSize();
+    return {buf, buf + size};
+}
+
+DeviceProperties deserializeDeviceProperties(const uint8_t* buffer, size_t size)
+{
+    THROW_IF_FALSE(buffer != nullptr,
+                   HIPDNN_STATUS_BAD_PARAM_NULL_POINTER,
+                   "Device properties buffer cannot be null");
+    THROW_IF_FALSE(size > 0, HIPDNN_STATUS_BAD_PARAM, "Device properties buffer size must be > 0");
+
+    // Verify the buffer
+    flatbuffers::Verifier verifier(buffer, size);
+    if(!verifier.VerifyBuffer<hipdnn_data_sdk::data_objects::DeviceProperties>("HDDP"))
+    {
+        throw HipdnnException(HIPDNN_STATUS_BAD_PARAM,
+                              "Invalid device properties buffer: failed FlatBuffer verification");
+    }
+
+    // Get the root table
+    auto devicePropsFB = hipdnn_data_sdk::data_objects::GetDeviceProperties(buffer);
+    if(devicePropsFB == nullptr)
+    {
+        throw HipdnnException(HIPDNN_STATUS_INTERNAL_ERROR,
+                              "Failed to get DeviceProperties root table");
+    }
+
+    // Extract fields
+    DeviceProperties props;
+    props.deviceId = devicePropsFB->device_id();
+    props.multiProcessorCount = devicePropsFB->multi_processor_count();
+    props.totalGlobalMem = devicePropsFB->total_global_mem();
+
+    return props;
+}
+
+} // namespace hipdnn_backend::heuristics

projects/hipdnn/backend/src/heuristics/DeviceProperties.hpp

@@ -0,0 +1,101 @@
+// Copyright © Advanced Micro Devices, Inc., or its affiliates.
+// SPDX-License-Identifier:  MIT
+
+#pragma once
+
+#include <cstddef>
+#include <cstdint>
+#include <vector>
+
+#include <hipdnn_plugin_sdk/PluginApiDataTypes.h>
+
+namespace hipdnn_backend::heuristics
+{
+
+/**
+ * @brief Device properties for heuristic plugin selection.
+ *
+ * This structure carries device facts needed for engine selection heuristics.
+ * It is filled by the backend (via queryDeviceProperties() or descriptor override)
+ * and serialized to FlatBuffer format before being passed to heuristic plugins.
+ *
+ * RFC 0007 Reference: Section 6.1
+ */
+struct DeviceProperties
+{
+    int deviceId = -1; ///< Device ID from hipGetDevice
+    int multiProcessorCount = 0; ///< Number of multiprocessors (compute units)
+    size_t totalGlobalMem = 0; ///< Total global memory in bytes
+
+    // Future optional fields can be added here and to the FlatBuffer schema
+    // Example: std::string architectureName;
+    // Example: int wavefrontSize = 0;
+};
+
+/**
+ * @brief Query device properties from HIP.
+ *
+ * Calls hipGetDevice() and hipGetDeviceProperties() to obtain current
+ * device information. This is the default acquisition method when no
+ * descriptor override is provided.
+ *
+ * Plugins must NOT call this function. They receive serialized device
+ * properties via hipdnnHeuristicHandleSetDeviceProperties.
+ *
+ * RFC 0007 Reference: Section 6.2
+ *
+ * @return DeviceProperties populated from HIP, or default values on error.
+ */
+DeviceProperties queryDeviceProperties();
+
+/**
+ * @brief Serialize DeviceProperties to FlatBuffer format.
+ *
+ * Builds a FlatBuffer-serialized representation of the device properties
+ * using the schema from data_sdk/schemas/device_properties.fbs.
+ *
+ * The returned buffer is owned by the caller and must remain valid while
+ * any hipdnnPluginConstData_t wrappers pointing to it are in use.
+ *
+ * RFC 0007 Reference: Section 13.2
+ *
+ * @param props Device properties to serialize.
+ * @return Vector containing the serialized FlatBuffer bytes.
+ */
+std::vector<uint8_t> serializeDeviceProperties(const DeviceProperties& props);
+
+/**
+ * @brief Deserialize DeviceProperties from FlatBuffer format.
+ *
+ * Verifies and parses a FlatBuffer-serialized device properties buffer.
+ * Throws HipdnnException if the buffer is malformed or incompatible.
+ *
+ * This is primarily for testing and backend internal use. Plugins should
+ * use the generated FlatBuffer accessors directly.
+ *
+ * @param buffer Pointer to serialized FlatBuffer bytes.
+ * @param size Size of the buffer in bytes.
+ * @return DeviceProperties deserialized from the buffer.
+ * @throws HipdnnException if buffer is invalid.
+ */
+DeviceProperties deserializeDeviceProperties(const uint8_t* buffer, size_t size);
+
+/**
+ * @brief Wrap serialized device properties in hipdnnPluginConstData_t.
+ *
+ * Creates a hipdnnPluginConstData_t wrapper pointing to the serialized buffer.
+ * The buffer must remain valid while the wrapper is in use.
+ *
+ * @param serializedBuffer Reference to the serialized buffer (must outlive the wrapper).
+ * @return hipdnnPluginConstData_t wrapper pointing to the buffer.
+ */
+inline hipdnnPluginConstData_t
+    wrapSerializedDeviceProperties(const std::vector<uint8_t>& serializedBuffer)
+{
+    hipdnnPluginConstData_t wrapper;
+    wrapper.ptr = serializedBuffer.data();
+    wrapper.size = serializedBuffer.size();
+    return wrapper;
+}
+
+} // namespace hipdnn_backend::heuristics

projects/hipdnn/backend/src/logging/Logging.cpp

@@ -607,5 +607,22 @@ hipdnnStatus_t getGlobalLogLevel(hipdnnSeverity_t& level)
     return HIPDNN_STATUS_SUCCESS;
 }
 
+void heuristicLoggingCallback(hipdnnSeverity_t severity,
+                              const char* componentPrefix,
+                              const char* msg)
+{
+    // RFC 0007 Section 12: Heuristic plugin logging callback
+    // Combines component prefix and message, then forwards to backend logging
+    if(componentPrefix != nullptr && msg != nullptr)
+    {
+        const std::string combined = std::string(componentPrefix) + msg;
+        backendLoggingCallback(severity, combined.c_str());
+    }
+    else if(msg != nullptr)
+    {
+        backendLoggingCallback(severity, msg);
+    }
+}
+
 } // namespace logging
 } // namespace hipdnn_backend

projects/hipdnn/backend/src/logging/Logging.hpp

@@ -49,6 +49,16 @@
             hipdnn_backend::logging::detail::K_BACKEND_LOGGER_COMPONENT_NAME,    \
             hipdnn_backend::logging::detail::formatBackendMessage(__VA_ARGS__)); \
     } while(0)
+
+// DEBUG logging - use INFO level since DEBUG doesn't exist in SDK
+#define HIPDNN_BACKEND_LOG_DEBUG(...)                                            \
+    do                                                                           \
+    {                                                                            \
+        hipdnn_backend::logging::initialize();                                   \
+        HIPDNN_SDK_LOG_INFO_WITH_COMPONENT(                                      \
+            hipdnn_backend::logging::detail::K_BACKEND_LOGGER_COMPONENT_NAME,    \
+            hipdnn_backend::logging::detail::formatBackendMessage(__VA_ARGS__)); \
+    } while(0)
 #endif // HIPDNN_BACKEND_COMPILATION
 
 namespace hipdnn_backend::logging
@@ -60,6 +70,11 @@ void loggerShutdown();
 
 void backendLoggingCallback(hipdnnSeverity_t severity, const char* msg);
 
+// Heuristic plugin logging callback (3-parameter version with component prefix)
+void heuristicLoggingCallback(hipdnnSeverity_t severity,
+                              const char* componentPrefix,
+                              const char* msg);
+
 void logHipDeviceInfo(hipStream_t stream);
 
 hipdnnStatus_t setUserLogCallback(hipdnnUserLogCallback_t callback,