fix(hipdnn): fail fast on plan-only override execute without override enabled (#8881)

SamuelReeder · web-flow · commit 84dc26ec1b63 · 2026-06-29T23:37:35.000-06:00
## Summary The frontend override `execute()` overload fails fast when override args are supplied to a graph that did not enable override shapes — but only for full graphs. The plan-only [deserialize_compiled_plan](https://github.com/ROCm/rocm-libraries/blob/f1230db5ef05ba6cf6413741a1b58b6a80473a8a/projects/hipdnn/frontend/include/hipdnn_frontend/Graph.hpp#L1571) branch skipped the override-enabled check, so misuse on a plan-only object was only caught later at the backend dispatch guard. This makes the plan-only branch fail fast in the frontend, matching the full-graph branch. Part of the overridable tensor shapes work ([RFC 0008](https://github.com/ROCm/rocm-libraries/blob/develop/projects/hipdnn/docs/rfcs/0008_OverridableTensorShapesDesign.md)). JIRA ID : ALMIOPEN-2244 ## Risk Assessment Medium risk. Adds a read-only backend execution-plan attribute (API addition) and changes the plan-only override-execute path to reject earlier. The new rejection only fires for misuse the backend dispatch guard already rejected authoritatively, so no legitimate path changes: plan-only overrides on an override-enabled plan still execute, and full-graph behavior is unchanged. No serialization format change. Blast radius is ASIC-independent (see below), so passing PR CI is sufficient. ## Testing Summary - Backend unit tests: new attribute round-trips through deserialize → `getAttribute` for both flag states; existing plan-descriptor, serialization, and enum-string suites unaffected. - Frontend GPU integration tests: new plan-only fail-fast regression (rejects with `INVALID_VALUE` and never dispatches to the provider); full override-execute suite for no regressions. - Commit hooks (clang-format, whitespace) on all changed files. ## Testing Checklist - [x] hipDNN backend unit tests - `hipdnn_backend_tests --gtest_filter='TestExecutionPlanDescriptor.*:*SerializationApi*:*BackendEnumStringUtils*:*IsOverrideShapeEnabledExt*'` - ASICs: gfx90a - Status: Passed (74) - [x] hipDNN frontend override integration tests - `hipdnn_public_frontend_tests --gtest_filter='*Override*'` - ASICs: gfx90a - Status: Passed (35) - [x] Commit hooks - `pre-commit run --files <changed>` - Status: Passed - [ ] PR CI - GitHub PR checks - Status: Pending ## Technical Changes - Add read-only `HIPDNN_ATTR_EXECUTION_PLAN_IS_OVERRIDE_SHAPE_ENABLED_EXT` with a `getAttribute` case on `ExecutionPlanDescriptor` (mirrors `ENGINE_GLOBAL_INDEX_EXT`; no serialization change) plus its enum-name mapping. The attribute is required because the override-enabled flag, while already preserved across the plan round-trip in the backend (serialized into the plan flatbuffer, restored on deserialize), was unreachable from the header-only frontend: `getAttribute` did not surface it, `deserialize_compiled_plan` hard-coded it to `false`, and no operation-graph or engine-config descriptor is reconstructed on the plan-only path. The only no-new-attribute alternative — parsing the backend plan flatbuffer in the frontend — would couple the frontend to the backend wire format and version gate. - Recover the flag in `deserialize_compiled_plan` via a new `getExecutionPlanOverrideShapeEnabled` frontend helper instead of forcing `false`. - Reject override args in the plan-only branch of the override `execute()` overload with `INVALID_VALUE`, short-circuiting before any provider dispatch. - Add backend tests for the attribute (both flag states) and enum-name mapping, and a frontend GPU regression test for the plan-only fail-fast.
diff --git a/projects/hipdnn/backend/include/HipdnnBackendAttributeName.h b/projects/hipdnn/backend/include/HipdnnBackendAttributeName.h
@@ -163,6 +163,10 @@ typedef enum
     /** @brief Global index of the engine backing this finalized execution plan (read-only) */
     HIPDNN_ATTR_EXECUTION_PLAN_ENGINE_GLOBAL_INDEX_EXT = 309,
 
+    /** @brief Whether execute-time override shapes are enabled for this plan (bool, read-only,
+     * extension) */
+    HIPDNN_ATTR_EXECUTION_PLAN_IS_OVERRIDE_SHAPE_ENABLED_EXT = 310,
+
     /** @} */
 
     /**
diff --git a/projects/hipdnn/backend/src/BackendEnumStringUtils.hpp b/projects/hipdnn/backend/src/BackendEnumStringUtils.hpp
@@ -322,6 +322,8 @@ inline const char* hipdnnGetAttributeNameString(hipdnnBackendAttributeName_t att
         return "HIPDNN_ATTR_EXECUTION_PLAN_TENSOR_UIDS_EXT";
     case HIPDNN_ATTR_EXECUTION_PLAN_ENGINE_GLOBAL_INDEX_EXT:
         return "HIPDNN_ATTR_EXECUTION_PLAN_ENGINE_GLOBAL_INDEX_EXT";
+    case HIPDNN_ATTR_EXECUTION_PLAN_IS_OVERRIDE_SHAPE_ENABLED_EXT:
+        return "HIPDNN_ATTR_EXECUTION_PLAN_IS_OVERRIDE_SHAPE_ENABLED_EXT";
 
     case HIPDNN_ATTR_INTERMEDIATE_INFO_UNIQUE_ID:
         return "HIPDNN_ATTR_INTERMEDIATE_INFO_UNIQUE_ID";
diff --git a/projects/hipdnn/backend/src/descriptors/ExecutionPlanDescriptor.cpp b/projects/hipdnn/backend/src/descriptors/ExecutionPlanDescriptor.cpp
@@ -119,6 +119,15 @@ void ExecutionPlanDescriptor::getAttribute(hipdnnBackendAttributeName_t attribut
                   arrayOfElements,
                   "ExecutionPlanDescriptor failed to get engine global index");
         break;
+    case HIPDNN_ATTR_EXECUTION_PLAN_IS_OVERRIDE_SHAPE_ENABLED_EXT:
+        getScalar(isOverrideShapeEnabled(),
+                  HIPDNN_TYPE_BOOLEAN,
+                  attributeType,
+                  requestedElementCount,
+                  elementCount,
+                  arrayOfElements,
+                  "ExecutionPlanDescriptor failed to get override shape enabled flag");
+        break;
     case HIPDNN_ATTR_EXECUTION_PLAN_HANDLE:
     case HIPDNN_ATTR_EXECUTION_PLAN_COMPUTED_INTERMEDIATE_UIDS:
     case HIPDNN_ATTR_EXECUTION_PLAN_RUN_ONLY_INTERMEDIATE_UIDS:
diff --git a/projects/hipdnn/backend/tests/TestBackendEnumStringUtils.cpp b/projects/hipdnn/backend/tests/TestBackendEnumStringUtils.cpp
@@ -141,6 +141,11 @@ TEST(TestBackendEnumStringUtils, GetBackendAttributeName)
                  "HIPDNN_ATTR_EXECUTION_PLAN_DEVICEPROP");
     EXPECT_STREQ(hipdnnGetAttributeNameString(HIPDNN_ATTR_EXECUTION_PLAN_TENSOR_UIDS_EXT),
                  "HIPDNN_ATTR_EXECUTION_PLAN_TENSOR_UIDS_EXT");
+    EXPECT_STREQ(hipdnnGetAttributeNameString(HIPDNN_ATTR_EXECUTION_PLAN_ENGINE_GLOBAL_INDEX_EXT),
+                 "HIPDNN_ATTR_EXECUTION_PLAN_ENGINE_GLOBAL_INDEX_EXT");
+    EXPECT_STREQ(
+        hipdnnGetAttributeNameString(HIPDNN_ATTR_EXECUTION_PLAN_IS_OVERRIDE_SHAPE_ENABLED_EXT),
+        "HIPDNN_ATTR_EXECUTION_PLAN_IS_OVERRIDE_SHAPE_ENABLED_EXT");
 
     EXPECT_STREQ(hipdnnGetAttributeNameString(HIPDNN_ATTR_INTERMEDIATE_INFO_UNIQUE_ID),
                  "HIPDNN_ATTR_INTERMEDIATE_INFO_UNIQUE_ID");
diff --git a/projects/hipdnn/backend/tests/descriptors/TestExecutionPlanDescriptor.cpp b/projects/hipdnn/backend/tests/descriptors/TestExecutionPlanDescriptor.cpp
@@ -505,6 +505,54 @@ TEST_F(TestExecutionPlanDescriptor, GetEngineGlobalIndexExtReturnsDeserializedEn
     ASSERT_EQ(engineGlobalIndex, ENGINE_ID);
 }
 
+TEST_F(TestExecutionPlanDescriptor, GetIsOverrideShapeEnabledExtReturnsDeserializedFlagFalse)
+{
+    auto plan = getExecutionPlanDescriptor();
+    auto serializedPlan = makeSerializedPlan(1, 1024, true, true, false, false, false);
+
+    EXPECT_CALL(*_mockEnginePluginResourceManager,
+                createExecutionContextFromSerialized(ENGINE_ID, _))
+        .WillOnce([](int64_t, const hipdnnPluginConstData_t*) { return getExecutionContext(); });
+    EXPECT_CALL(*_mockEnginePluginResourceManager, destroyExecutionContext(_, _));
+
+    ASSERT_NO_THROW(plan->deserializeBackendPlan(
+        _mockEnginePluginResourceManager, serializedPlan.data(), serializedPlan.size()));
+
+    bool isOverrideShapeEnabled = true;
+    int64_t count = 0;
+    ASSERT_NO_THROW(plan->getAttribute(HIPDNN_ATTR_EXECUTION_PLAN_IS_OVERRIDE_SHAPE_ENABLED_EXT,
+                                       HIPDNN_TYPE_BOOLEAN,
+                                       1,
+                                       &count,
+                                       &isOverrideShapeEnabled));
+    ASSERT_EQ(count, 1);
+    ASSERT_FALSE(isOverrideShapeEnabled);
+}
+
+TEST_F(TestExecutionPlanDescriptor, GetIsOverrideShapeEnabledExtReturnsDeserializedFlagTrue)
+{
+    auto plan = getExecutionPlanDescriptor();
+    auto serializedPlan = makeSerializedPlan(1, 1024, true, true, false, false, true);
+
+    EXPECT_CALL(*_mockEnginePluginResourceManager,
+                createExecutionContextFromSerialized(ENGINE_ID, _))
+        .WillOnce([](int64_t, const hipdnnPluginConstData_t*) { return getExecutionContext(); });
+    EXPECT_CALL(*_mockEnginePluginResourceManager, destroyExecutionContext(_, _));
+
+    ASSERT_NO_THROW(plan->deserializeBackendPlan(
+        _mockEnginePluginResourceManager, serializedPlan.data(), serializedPlan.size()));
+
+    bool isOverrideShapeEnabled = false;
+    int64_t count = 0;
+    ASSERT_NO_THROW(plan->getAttribute(HIPDNN_ATTR_EXECUTION_PLAN_IS_OVERRIDE_SHAPE_ENABLED_EXT,
+                                       HIPDNN_TYPE_BOOLEAN,
+                                       1,
+                                       &count,
+                                       &isOverrideShapeEnabled));
+    ASSERT_EQ(count, 1);
+    ASSERT_TRUE(isOverrideShapeEnabled);
+}
+
 TEST_F(TestExecutionPlanDescriptor, SerializeRejectsUnfinalizedPlan)
 {
     auto plan = getExecutionPlanDescriptor();
diff --git a/projects/hipdnn/frontend/include/hipdnn_frontend/Graph.hpp b/projects/hipdnn/frontend/include/hipdnn_frontend/Graph.hpp
@@ -1485,7 +1485,11 @@ class Graph : public INode
                 // A deserialized compiled plan is finalized by construction and can be re-serialized.
                 _executionPlanFinalized = true;
                 // Recover the engine backing the attached plan for the serialize capability gate.
-                _selectedEngineId = detail::getExecutionPlanEngineId(_executionPlanDesc->get());
+                _selectedEngineId = detail::getNullableAttrScalar<int64_t>(
+                    _executionPlanDesc->get(),
+                    HIPDNN_ATTR_EXECUTION_PLAN_ENGINE_GLOBAL_INDEX_EXT,
+                    HIPDNN_TYPE_INT64,
+                    "execution plan engine global index");
             }
             else
             {
@@ -1580,11 +1584,20 @@ class Graph : public INode
         // A deserialized compiled plan is finalized by construction and can be re-serialized.
         _executionPlanFinalized = true;
         // Recover the engine backing the attached plan for the serialize capability gate.
-        _selectedEngineId = detail::getExecutionPlanEngineId(_executionPlanDesc->get());
+        _selectedEngineId = detail::getNullableAttrScalar<int64_t>(
+            _executionPlanDesc->get(),
+            HIPDNN_ATTR_EXECUTION_PLAN_ENGINE_GLOBAL_INDEX_EXT,
+            HIPDNN_TYPE_INT64,
+            "execution plan engine global index");
         _engineConfigDesc.reset();
         resetGraphDesc();
         _sub_nodes.clear();
-        _isOverrideShapeEnabled = false;
+        _isOverrideShapeEnabled = detail::getNullableAttrScalar<bool>(
+                                      _executionPlanDesc->get(),
+                                      HIPDNN_ATTR_EXECUTION_PLAN_IS_OVERRIDE_SHAPE_ENABLED_EXT,
+                                      HIPDNN_TYPE_BOOLEAN,
+                                      "execution plan override shape enabled flag")
+                                      .value_or(false);
 
         return {};
     }
@@ -2024,8 +2037,10 @@ class Graph : public INode
     /**
      * @brief Execute with per-tensor runtime shape/stride overrides.
      *
-     * Graph-backed objects require `set_override_shape_enabled(true)`. Objects
-     * restored from compiled-plan bytes receive structural validation only.
+     * Both graph-backed and plan-only (compiled-plan-deserialized) objects require
+     * the plan to have been built with `set_override_shape_enabled(true)`; otherwise
+     * the call fails fast with `INVALID_VALUE`. Plan-only objects additionally receive
+     * structural validation only (no graph-aware shape checks).
      * Empty override arrays dispatch through the non-override path.
      */
     Error execute(hipdnnHandle_t handle,
@@ -2054,6 +2069,19 @@ class Graph : public INode
         const bool planOnly = _sub_nodes.empty();
         if(planOnly)
         {
+            if(!_isOverrideShapeEnabled)
+            {
+                HIPDNN_FE_LOG_INFO("Override execute called on plan-only graph "
+                                   << graph_attributes.get_name()
+                                   << " deserialized from a plan that was not built with "
+                                      "set_override_shape_enabled(true).");
+                return {ErrorCode::INVALID_VALUE,
+                        "Graph::execute override overload called on a compiled plan that was "
+                        "not built with set_override_shape_enabled(true). The override flag "
+                        "must be set at build time before per-execute overrides are "
+                        "supplied."};
+            }
+
             HIPDNN_CHECK_ERROR(detail::validatePlanOnlyOverrideArguments(
                 overrideUids, overrideShapes, overrideStrides));
         }
diff --git a/projects/hipdnn/frontend/include/hipdnn_frontend/detail/DescriptorUnpackHelpers.hpp b/projects/hipdnn/frontend/include/hipdnn_frontend/detail/DescriptorUnpackHelpers.hpp
@@ -97,24 +97,20 @@ template <typename T>
     return {};
 }
 
-/// Returns the global index of the engine backing a finalized execution-plan
-/// descriptor, or std::nullopt if the backend cannot report it. Lets callers
-/// recover the engine of a plan attached via deserialize so a later
-/// serialize() can re-query that engine's plan-serialization capability.
-[[nodiscard]] inline std::optional<int64_t>
-    getExecutionPlanEngineId(hipdnnBackendDescriptor_t planDesc)
+/// Gets a scalar attribute, returning std::nullopt when the backend cannot
+/// report it instead of surfacing an error.
+template <typename T>
+[[nodiscard]] inline std::optional<T> getNullableAttrScalar(hipdnnBackendDescriptor_t desc,
+                                                            hipdnnBackendAttributeName_t attrName,
+                                                            hipdnnBackendAttributeType_t attrType,
+                                                            const std::string& errorContext)
 {
-    int64_t engineId = 0;
-    if(getDescriptorAttrScalar<int64_t>(planDesc,
-                                        HIPDNN_ATTR_EXECUTION_PLAN_ENGINE_GLOBAL_INDEX_EXT,
-                                        HIPDNN_TYPE_INT64,
-                                        engineId,
-                                        "execution plan engine global index")
-           .is_bad())
+    T value{};
+    if(getDescriptorAttrScalar<T>(desc, attrName, attrType, value, errorContext).is_bad())
     {
         return std::nullopt;
     }
-    return engineId;
+    return value;
 }
 
 /// Gets a string attribute (char array) from a backend descriptor.
diff --git a/projects/hipdnn/frontend/tests/TestGraph.cpp b/projects/hipdnn/frontend/tests/TestGraph.cpp
@@ -636,6 +636,33 @@ TEST_F(TestGraph, DeserializeCompiledPlanClearsFrontendGraphState)
 }
 
 #ifdef HIPDNN_ENABLE_SDPA
+// Sets the override-shape-enabled attribute query that deserialize_compiled_plan
+// issues on the restored execution plan, letting plan-only tests choose whether the
+// restored plan reports override shapes as enabled. Uses ON_CALL so the sibling
+// engine-id query on the same descriptor stays uninteresting under NiceMock.
+static void setPlanOverrideShapeEnabledQuery(::testing::NiceMock<Mock_hipdnn_backend>& mockBackend,
+                                             hipdnnBackendDescriptor_t executionPlan,
+                                             bool enabled)
+{
+    ON_CALL(mockBackend,
+            backendGetAttribute(executionPlan,
+                                HIPDNN_ATTR_EXECUTION_PLAN_IS_OVERRIDE_SHAPE_ENABLED_EXT,
+                                HIPDNN_TYPE_BOOLEAN,
+                                1,
+                                _,
+                                _))
+        .WillByDefault([enabled](hipdnnBackendDescriptor_t,
+                                 hipdnnBackendAttributeName_t,
+                                 hipdnnBackendAttributeType_t,
+                                 int64_t,
+                                 int64_t* elementCount,
+                                 void* arrayOfElements) {
+            *elementCount = 1;
+            *static_cast<bool*>(arrayOfElements) = enabled;
+            return HIPDNN_STATUS_SUCCESS;
+        });
+}
+
 TEST_F(TestGraph, PlanOnlyOverrideExecuteWritesOverrideVariantPackAttributes)
 {
     Graph graph;
@@ -651,6 +678,7 @@ TEST_F(TestGraph, PlanOnlyOverrideExecuteWritesOverrideVariantPackAttributes)
                 *descriptor = executionPlan;
                 return HIPDNN_STATUS_SUCCESS;
             });
+    setPlanOverrideShapeEnabledQuery(*_mockBackend, executionPlan, true);
     ASSERT_TRUE(graph.from_compiled_plan_binary(_handle, serializedPlan).is_good());
 
     std::unordered_map<int64_t, void*> variantPack;
@@ -838,6 +866,7 @@ TEST_F(TestGraph, PlanOnlyOverrideExecuteRejectsStructuralValidationBeforeBacken
                 *descriptor = executionPlan;
                 return HIPDNN_STATUS_SUCCESS;
             });
+    setPlanOverrideShapeEnabledQuery(*_mockBackend, executionPlan, true);
     ASSERT_TRUE(graph.from_compiled_plan_binary(_handle, serializedPlan).is_good());
 
     std::unordered_map<int64_t, void*> variantPack;
@@ -870,6 +899,7 @@ TEST_F(TestGraph, PlanOnlyOverrideExecutePropagatesOverrideAttributeFailure)
                 *descriptor = executionPlan;
                 return HIPDNN_STATUS_SUCCESS;
             });
+    setPlanOverrideShapeEnabledQuery(*_mockBackend, executionPlan, true);
     ASSERT_TRUE(graph.from_compiled_plan_binary(_handle, serializedPlan).is_good());
 
     std::unordered_map<int64_t, void*> variantPack;
@@ -901,6 +931,74 @@ TEST_F(TestGraph, PlanOnlyOverrideExecutePropagatesOverrideAttributeFailure)
 
     EXPECT_EQ(result.code, ErrorCode::HIPDNN_BACKEND_ERROR);
 }
+
+TEST_F(TestGraph, DeserializeCompiledPlanRecoversOverrideShapeEnabledFlag)
+{
+    const std::vector<uint8_t> serializedPlan{1, 2, 3};
+
+    auto enabledPlan = reinterpret_cast<hipdnnBackendDescriptor_t>(0x4567);
+    EXPECT_CALL(*_mockBackend, backendCreateAndDeserializeExecutionPlanExt(_handle, _, _, _))
+        .WillOnce(
+            [enabledPlan](
+                hipdnnHandle_t, hipdnnBackendDescriptor_t* descriptor, const uint8_t*, size_t) {
+                *descriptor = enabledPlan;
+                return HIPDNN_STATUS_SUCCESS;
+            });
+    setPlanOverrideShapeEnabledQuery(*_mockBackend, enabledPlan, true);
+
+    Graph enabledGraph;
+    ASSERT_TRUE(enabledGraph.from_compiled_plan_binary(_handle, serializedPlan).is_good());
+    EXPECT_TRUE(enabledGraph.is_override_shape_enabled());
+
+    auto disabledPlan = reinterpret_cast<hipdnnBackendDescriptor_t>(0x89ab);
+    EXPECT_CALL(*_mockBackend, backendCreateAndDeserializeExecutionPlanExt(_handle, _, _, _))
+        .WillOnce(
+            [disabledPlan](
+                hipdnnHandle_t, hipdnnBackendDescriptor_t* descriptor, const uint8_t*, size_t) {
+                *descriptor = disabledPlan;
+                return HIPDNN_STATUS_SUCCESS;
+            });
+    setPlanOverrideShapeEnabledQuery(*_mockBackend, disabledPlan, false);
+
+    Graph disabledGraph;
+    ASSERT_TRUE(disabledGraph.from_compiled_plan_binary(_handle, serializedPlan).is_good());
+    EXPECT_FALSE(disabledGraph.is_override_shape_enabled());
+}
+
+TEST_F(TestGraph, PlanOnlyOverrideExecuteRejectedWhenOverrideShapeDisabled)
+{
+    Graph graph;
+    const std::vector<uint8_t> serializedPlan{1, 2, 3};
+    auto executionPlan = reinterpret_cast<hipdnnBackendDescriptor_t>(0x4567);
+
+    EXPECT_CALL(*_mockBackend,
+                backendCreateAndDeserializeExecutionPlanExt(
+                    _handle, _, serializedPlan.data(), serializedPlan.size()))
+        .WillOnce(
+            [executionPlan](
+                hipdnnHandle_t, hipdnnBackendDescriptor_t* descriptor, const uint8_t*, size_t) {
+                *descriptor = executionPlan;
+                return HIPDNN_STATUS_SUCCESS;
+            });
+    setPlanOverrideShapeEnabledQuery(*_mockBackend, executionPlan, false);
+    ASSERT_TRUE(graph.from_compiled_plan_binary(_handle, serializedPlan).is_good());
+
+    std::unordered_map<int64_t, void*> variantPack;
+    variantPack[1] = reinterpret_cast<void*>(0x1000);
+    const std::vector<int64_t> overrideUids{1};
+    const std::vector<std::vector<int64_t>> overrideShapes{{2, 3}};
+    const std::vector<std::vector<int64_t>> overrideStrides{{3, 1}};
+
+    // Fail-fast must reject before constructing a variant pack or dispatching.
+    EXPECT_CALL(*_mockBackend, backendCreateDescriptor(HIPDNN_BACKEND_VARIANT_PACK_DESCRIPTOR, _))
+        .Times(0);
+    EXPECT_CALL(*_mockBackend, backendExecute(_, _, _)).Times(0);
+
+    auto result = graph.execute(
+        _handle, variantPack, nullptr, overrideUids, overrideShapes, overrideStrides);
+
+    EXPECT_EQ(result.code, ErrorCode::INVALID_VALUE) << result.get_message();
+}
 #endif
 
 TEST_F(TestGraph, ValidateUnsetNodeComputeTypeSetGraphComputeType)
diff --git a/projects/hipdnn/tests/frontend/IntegrationOverrideExecute.cpp b/projects/hipdnn/tests/frontend/IntegrationOverrideExecute.cpp
