ROCm · cderb · May 20, 2026 · Apr 15, 2026 · Apr 15, 2026 · Apr 15, 2026
@@ -101,6 +101,23 @@ set(HIPDNN_RELATIVE_INSTALL_PLUGIN_ENGINE_DIR
     "${HIPDNN_PLUGIN_ROOTDIR}/${HIPDNN_PLUGIN_ENGINE_SUBDIR}"
     CACHE STRING "Relative install directory for official hipDNN engine plugins"
 )
+set(HIPDNN_PLUGIN_HEURISTIC_SUBDIR "hipdnn_plugins/heuristics"
+    CACHE STRING "Subdirectory for official hipDNN heuristic plugins"
+)
+set(HIPDNN_BUILD_PLUGIN_HEURISTIC_DIR
+    "${CMAKE_BINARY_DIR}/${HIPDNN_PLUGIN_ROOTDIR}/${HIPDNN_PLUGIN_HEURISTIC_SUBDIR}"
+    CACHE PATH "Build directory for official hipDNN heuristic plugins"
+)
+set(HIPDNN_FULL_INSTALL_PLUGIN_HEURISTIC_DIR
+    "${HIPDNN_PLUGIN_FULL_ROOTDIR}/${HIPDNN_PLUGIN_HEURISTIC_SUBDIR}"
+    CACHE
+        STRING
+        "Full install directory for official hipDNN heuristic plugins. Uses the CMAKE_INSTALL_PREFIX set at configure time (defaults to /opt/rocm/)."
+)
+set(HIPDNN_RELATIVE_INSTALL_PLUGIN_HEURISTIC_DIR
+    "${HIPDNN_PLUGIN_ROOTDIR}/${HIPDNN_PLUGIN_HEURISTIC_SUBDIR}"
+    CACHE STRING "Relative install directory for official hipDNN heuristic plugins"
+)
 set(HIPDNN_TEST_PLUGIN_DIR "${CMAKE_BINARY_DIR}/${HIPDNN_PLUGIN_ROOTDIR}/test_plugins"
     CACHE INTERNAL "Build directory for test plugins"
 )
@@ -182,6 +199,7 @@ include(cmake/ClangCheck.cmake)
 include(cmake/ClangTidy.cmake)
 include(cmake/Sanitizers.cmake)
 include(cmake/Tests.cmake)
+include(cmake/TestPluginNames.cmake)
 include(cmake/Spdlog.cmake)
 
 # Add global compile options

@@ -85,6 +85,26 @@ typedef enum
     /** @brief Find first mode: stop after finding any applicable engine (bool, extension) */
     HIPDNN_ATTR_ENGINEHEUR_FIND_FIRST_EXT = 105,
 
+    /**
+     * @brief Ordered list of heuristic policy IDs for engine selection (array of int64, extension)
+     *
+     * Specifies the policy order for the heuristic outer loop. Each element is an int64_t
+     * policy ID, produced by hashing a policy name (e.g., "SelectionHeuristic::StaticOrdering")
+     * with hipdnn_data_sdk::utilities::policyNameToId.
+     * Hashing is performed by the caller before the C ABI; the backend stores and dispatches
+     * by ID only.
+     *
+     * Resolution priority at finalize time (highest first):
+     *   1. HIPDNN_HEUR_POLICY_ORDER env var (comma-separated tokens; each token is
+     *      either a policy name, which is hashed via policyNameToId, or a raw
+     *      decimal int64 policy ID).
+     *   2. This descriptor attribute, if set.
+     *   3. Built-in default: [SelectionHeuristic::Config, SelectionHeuristic::StaticOrdering].
+     *
+     * Type: HIPDNN_TYPE_INT64
+     */
+    HIPDNN_ATTR_ENGINEHEUR_POLICY_ORDER_EXT = 106,
+
     /** @} */
 
     /**

@@ -502,6 +502,28 @@ HIPDNN_BACKEND_EXPORT void hipdnnLoggingCallback_ext(hipdnnSeverity_t severity,
 HIPDNN_BACKEND_EXPORT hipdnnStatus_t hipdnnSetEnginePluginPaths_ext(
     size_t numPaths, const char* const* pluginPaths, hipdnnPluginLoadingMode_ext_t loadingMode);
 
+/**
+ * @brief Sets the search paths for hipDNN heuristic plugins.
+ *
+ * Mirrors @ref hipdnnSetEnginePluginPaths_ext for the heuristic plugin search domain.
+ * Must be called before creating a hipDNN handle, as heuristic plugins are loaded
+ * during handle creation.
+ *
+ * Paths can be either directories or specific plugin files. Relative paths are resolved
+ * from the location of the libhipdnn_backend.so file.
+ *
+ * @param[in] numPaths       The number of paths in the `pluginPaths` array.
+ * @param[in] pluginPaths    An array of relative or absolute path strings.
+ * @param[in] loadingMode    Specifies whether to add paths to or replace the default search paths.
+ *
+ * @retval HIPDNN_STATUS_SUCCESS                  The operation was successful.
+ * @retval HIPDNN_STATUS_BAD_PARAM_NULL_POINTER   `pluginPaths` is nullptr when `numPaths` is greater than 0.
+ * @retval HIPDNN_STATUS_NOT_SUPPORTED            Called with active handle.
+ * @retval HIPDNN_STATUS_INTERNAL_ERROR           An internal error occurred.
+ */
+HIPDNN_BACKEND_EXPORT hipdnnStatus_t hipdnnSetHeuristicPluginPaths_ext(
+    size_t numPaths, const char* const* pluginPaths, hipdnnPluginLoadingMode_ext_t loadingMode);
+
 /**
  * @brief Sets the plugin unloading mode for hipDNN.
  *
@@ -676,6 +698,72 @@ HIPDNN_BACKEND_EXPORT hipdnnStatus_t hipdnnGetEngineInfo_ext(hipdnnHandle_t hand
                                                              char* type,
                                                              size_t* typeLen);
 
+/**
+ * @brief Gets the count of loaded heuristic policies.
+ *
+ * Returns the number of heuristic policy plugins that have been successfully loaded
+ * and validated by the backend. This count includes all policies available for use
+ * in the outer loop engine selection.
+ *
+ * @param[in]  handle       A valid hipDNN handle.
+ * @param[out] numPolicies  Pointer where the policy count will be stored.
+ *
+ * @retval HIPDNN_STATUS_SUCCESS           Success.
+ * @retval HIPDNN_STATUS_BAD_PARAM         Invalid handle or null pointer.
+ *
+ * @see hipdnnGetHeuristicPolicyInfo_ext for retrieving individual policy metadata
+ */
+HIPDNN_BACKEND_EXPORT hipdnnStatus_t hipdnnGetHeuristicPolicyCount_ext(hipdnnHandle_t handle,
+                                                                       size_t* numPolicies);
+
+/**
+ * @brief Gets information about a loaded heuristic policy by index.
+ *
+ * Retrieves metadata for a heuristic policy plugin, including policy ID, policy
+ * name, plugin name, plugin version, and API version.
+ *
+ * @note The enumeration order is unspecified and may change between calls or
+ * between backend versions. Callers must not assume a stable ordering across
+ * indices; use the returned `policyId` as the identity, not `policyIndex`.
+ *
+ * This function uses a two-call pattern for string fields:
+ * 1. First call: Pass all string buffers as `nullptr` to query required sizes.
+ *    - Sets `policyNameLen`, `pluginNameLen`, `pluginVersionLen`, and `apiVersionLen`
+ *      to the required buffer sizes (including null terminator). Note: if any
+ *      string buffer is null, all sizes are updated.
+ *
+ * 2. Second call: Pass allocated buffers with sizes set from the first call.
+ *
+ * @param[in]     handle            A valid hipDNN handle.
+ * @param[in]     policyIndex       Zero-based index of the policy to query.
+ * @param[out]    policyId          Pointer where the policy ID will be stored, or `nullptr` to skip.
+ * @param[out]    policyName        Buffer for the policy name, or `nullptr` to query size.
+ * @param[in,out] policyNameLen     Pointer to buffer size; updated with required size.
+ * @param[out]    pluginName        Buffer for the plugin name, or `nullptr` to query size.
+ * @param[in,out] pluginNameLen     Pointer to buffer size; updated with required size.
+ * @param[out]    pluginVersion     Buffer for the plugin version, or `nullptr` to query size.
+ * @param[in,out] pluginVersionLen  Pointer to buffer size; updated with required size.
+ * @param[out]    apiVersion        Buffer for the API version, or `nullptr` to query size.
+ * @param[in,out] apiVersionLen     Pointer to buffer size; updated with required size.
+ *
+ * @retval HIPDNN_STATUS_SUCCESS           Success.
+ * @retval HIPDNN_STATUS_BAD_PARAM         Invalid handle, null pointers, or out-of-range index.
+ * @retval HIPDNN_STATUS_INTERNAL_ERROR    Internal error.
+ *
+ * @see hipdnnGetHeuristicPolicyCount_ext for getting the total policy count
+ */
+HIPDNN_BACKEND_EXPORT hipdnnStatus_t hipdnnGetHeuristicPolicyInfo_ext(hipdnnHandle_t handle,
+                                                                      size_t policyIndex,
+                                                                      int64_t* policyId,
+                                                                      char* policyName,
+                                                                      size_t* policyNameLen,
+                                                                      char* pluginName,
+                                                                      size_t* pluginNameLen,
+                                                                      char* pluginVersion,
+                                                                      size_t* pluginVersionLen,
+                                                                      char* apiVersion,
+                                                                      size_t* apiVersionLen);
+
 /**
  * @brief Returns hipdnn backend version string. Returns an error if nullptr is passed
  *

@@ -55,6 +55,10 @@ add_library(
     logging/GraphLogger.cpp
     logging/Logging.cpp
     FlatbufferUtilities.cpp
+    heuristics/BuiltInHeuristics.cpp
+    heuristics/SelectionHeuristic.cpp
+    heuristics/config/ConfigBuiltIn.cpp
+    heuristics/static_ordering/StaticOrderingBuiltIn.cpp
     plugin/EnginePlugin.cpp
     plugin/EnginePluginResourceManager.cpp
     plugin/HeuristicPlugin.cpp

@@ -14,6 +14,7 @@
 #include "hipdnn_backend.h"
 #include "logging/Logging.hpp"
 #include "plugin/EnginePluginResourceManager.hpp"
+#include "plugin/HeuristicPluginResourceManager.hpp"
 
 #include <hipdnn_backend/version.h>
 #include <hipdnn_data_sdk/utilities/StringUtil.hpp>
@@ -480,13 +481,47 @@ HIPDNN_BACKEND_EXPORT hipdnnStatus_t hipdnnSetEnginePluginPaths_ext(
     });
 }
 
+HIPDNN_BACKEND_EXPORT hipdnnStatus_t hipdnnSetHeuristicPluginPaths_ext(
+    size_t numPaths, const char* const* pluginPaths, hipdnnPluginLoadingMode_ext_t loadingMode)
+{
+    LOG_API_ENTRY("numPaths={}, pluginPaths_ptr={:p}, loadingMode={}",
+                  numPaths,
+                  static_cast<const void*>(pluginPaths),
+                  loadingMode);
+
+    return hipdnn_backend::tryCatch([&, apiName = __func__] {
+        if(numPaths > 0)
+        {
+            throwIfNull(pluginPaths);
+        }
+
+        std::vector<std::filesystem::path> pathsVec;
+        pathsVec.reserve(numPaths);
+
+        for(size_t i = 0; i < numPaths; ++i)
+        {
+            throwIfNull(pluginPaths[i]);
+            pathsVec.emplace_back(pluginPaths[i]);
+        }
+
+        hipdnn_backend::plugin::HeuristicPluginResourceManager::setPluginPaths(pathsVec,
+                                                                               loadingMode);
+        LOG_API_SUCCESS(apiName, "set_heuristic_plugin_paths={}", loadingMode);
+        return HIPDNN_STATUS_SUCCESS;
+    });
+}
+
 HIPDNN_BACKEND_EXPORT hipdnnStatus_t
     hipdnnSetPluginUnloadMode_ext(hipdnnPluginUnloadingMode_ext_t unloadingMode)
 {
     LOG_API_ENTRY("unloadingMode={}", unloadingMode);
 
     return hipdnn_backend::tryCatch([&, apiName = __func__] {
+        // Apply to both plugin resource managers so the public ABI behaves
+        // uniformly regardless of plugin kind.
         hipdnn_backend::plugin::EnginePluginResourceManager::setPluginUnloadingMode(unloadingMode);
+        hipdnn_backend::plugin::HeuristicPluginResourceManager::setPluginUnloadingMode(
+            unloadingMode);
         LOG_API_SUCCESS(apiName, "set_plugin_unloading_mode={}", unloadingMode);
         return HIPDNN_STATUS_SUCCESS;
     });
@@ -654,6 +689,116 @@ HIPDNN_BACKEND_EXPORT hipdnnStatus_t hipdnnGetEngineInfo_ext(hipdnnHandle_t hand
     });
 }
 
+HIPDNN_BACKEND_EXPORT hipdnnStatus_t hipdnnGetHeuristicPolicyCount_ext(hipdnnHandle_t handle,
+                                                                       size_t* numPolicies)
+{
+    LOG_API_ENTRY("handle={:p}, numPolicies_ptr={:p}",
+                  static_cast<void*>(handle),
+                  static_cast<void*>(numPolicies));
+
+    return hipdnn_backend::tryCatch([&, apiName = __func__] {
+        throwIfNull(handle);
+        throwIfNull(numPolicies);
+
+        auto policyInfos = handle->getHeuristicPluginResourceManager()->getHeuristicPolicyInfos();
+        *numPolicies = policyInfos.size();
+
+        LOG_API_SUCCESS(apiName, "retrieved_numPolicies={}", *numPolicies);
+    });
+}
+
+HIPDNN_BACKEND_EXPORT hipdnnStatus_t hipdnnGetHeuristicPolicyInfo_ext(hipdnnHandle_t handle,
+                                                                      size_t policyIndex,
+                                                                      int64_t* policyId,
+                                                                      char* policyName,
+                                                                      size_t* policyNameLen,
+                                                                      char* pluginName,
+                                                                      size_t* pluginNameLen,
+                                                                      char* pluginVersion,
+                                                                      size_t* pluginVersionLen,
+                                                                      char* apiVersion,
+                                                                      size_t* apiVersionLen)
+{
+    LOG_API_ENTRY("handle={:p}, policyIndex={}, policyId_ptr={:p}, policyName_ptr={:p}, "
+                  "pluginName_ptr={:p}, pluginVersion_ptr={:p}, apiVersion_ptr={:p}",
+                  static_cast<void*>(handle),
+                  policyIndex,
+                  static_cast<void*>(policyId),
+                  static_cast<void*>(policyName),
+                  static_cast<void*>(pluginName),
+                  static_cast<void*>(pluginVersion),
+                  static_cast<void*>(apiVersion));
+
+    return hipdnn_backend::tryCatch([&, apiName = __func__] {
+        throwIfNull(handle);
+        throwIfNull(policyNameLen);
+        throwIfNull(pluginNameLen);
+        throwIfNull(pluginVersionLen);
+        throwIfNull(apiVersionLen);
+
+        // Built from an unordered_map; ordering is unspecified and may change
+        // between calls. If a stable enumeration is ever required, an explicit
+        // ordering must be applied here rather than relied on from the source map.
+        auto policyInfos = handle->getHeuristicPluginResourceManager()->getHeuristicPolicyInfos();
+        if(policyIndex >= policyInfos.size())
+        {
+            throw HipdnnException(HIPDNN_STATUS_BAD_PARAM,
+                                  "Policy index " + std::to_string(policyIndex) + " out of range ("
+                                      + std::to_string(policyInfos.size()) + " policies loaded).");
+        }
+
+        const auto& info = policyInfos[policyIndex];
+
+        if(policyId != nullptr)
+        {
+            *policyId = info.policyId;
+        }
+
+        const size_t requiredPolicyNameLen = info.policyName.size() + 1;
+        const size_t requiredPluginNameLen = info.pluginName.size() + 1;
+        const size_t requiredPluginVersionLen = info.pluginVersion.size() + 1;
+        const size_t requiredApiVersionLen = info.apiVersion.size() + 1;
+
+        // Query mode: return required sizes
+        if(policyName == nullptr || pluginName == nullptr || pluginVersion == nullptr
+           || apiVersion == nullptr)
+        {
+            *policyNameLen = requiredPolicyNameLen;
+            *pluginNameLen = requiredPluginNameLen;
+            *pluginVersionLen = requiredPluginVersionLen;
+            *apiVersionLen = requiredApiVersionLen;
+            return;
+        }
+
+        // Retrieve mode: check buffer sizes
+        if(*policyNameLen < requiredPolicyNameLen || *pluginNameLen < requiredPluginNameLen
+           || *pluginVersionLen < requiredPluginVersionLen
+           || *apiVersionLen < requiredApiVersionLen)
+        {
+            throw HipdnnException(HIPDNN_STATUS_BAD_PARAM, "Insufficient buffer space provided.");
+        }
+
+        hipdnn_data_sdk::utilities::copyMaxSizeWithNullTerminator(
+            policyName, info.policyName.c_str(), *policyNameLen);
+        hipdnn_data_sdk::utilities::copyMaxSizeWithNullTerminator(
+            pluginName, info.pluginName.c_str(), *pluginNameLen);
+        hipdnn_data_sdk::utilities::copyMaxSizeWithNullTerminator(
+            pluginVersion, info.pluginVersion.c_str(), *pluginVersionLen);
+        hipdnn_data_sdk::utilities::copyMaxSizeWithNullTerminator(
+            apiVersion, info.apiVersion.c_str(), *apiVersionLen);
+
+        LOG_API_SUCCESS(apiName,
+                        "policy[{}]: policyId={}, policyName={}, pluginName={}, "
+                        "pluginVersion={}, apiVersion={}",
+                        policyIndex,
+                        info.policyId,
+                        info.policyName,
+                        info.pluginName,
+                        info.pluginVersion,
+                        info.apiVersion);
+    });
+}
+
 HIPDNN_BACKEND_EXPORT hipdnnStatus_t hipdnnGetVersion_ext(const char** version)
 {
     return hipdnn_backend::tryCatch([&]() {

@@ -32,6 +32,10 @@
 #include "SdpaFwdOperationDescriptor.hpp"
 #include "TensorDescriptor.hpp"
 #include "VariantDescriptor.hpp"
+// Required: EngineHeuristicDescriptor holds std::unique_ptr<SelectionHeuristic>
+// via forward declaration, so the complete type must be visible where
+// make_shared<EngineHeuristicDescriptor>() instantiates the destructor.
+#include "heuristics/SelectionHeuristic.hpp"
 #include "logging/Logging.hpp"
 
 namespace hipdnn_backend