[Annotations] Address cuda orginal matching (#28623)

This pull request improves the accuracy and safety of device matching
logic for GPU execution providers, especially when using numeric GPU
indices (e.g., `gpu:1`) in layering rules. The changes ensure that
matching by index only occurs when a runtime device ordinal is available
(from `device_memory_info`), preventing accidental matches with hardware
PCI device IDs. The update also enhances logging and expands test
coverage for these scenarios.

**Device matching logic improvements:**

* Added a `has_device_ordinal` flag to `EpDeviceView` and updated
matching logic so that index-based GPU matching only occurs when the
device ordinal is known to be a runtime ordinal (from
`device_memory_info`), not a hardware PCI ID.
[[1]](diffhunk://#diff-a8f614056d63b5b3325eea1d855afc96550c977c16d8fdba641012a79194b7b5R169)
[[2]](diffhunk://#diff-a8f614056d63b5b3325eea1d855afc96550c977c16d8fdba641012a79194b7b5L193-R198)
[[3]](diffhunk://#diff-a8f614056d63b5b3325eea1d855afc96550c977c16d8fdba641012a79194b7b5L288-R299)
[[4]](diffhunk://#diff-a8f614056d63b5b3325eea1d855afc96550c977c16d8fdba641012a79194b7b5R324)
* Updated log messages to provide clearer error information when a
layering rule with a numeric GPU index cannot be mapped, including
guidance for troubleshooting.

**Test improvements:**

* Updated and expanded unit tests to cover correct and incorrect GPU
index matching, including cases where only hardware IDs are present and
should not match, and added a new test for execution providers with
specific GPU ordinals.
[[1]](diffhunk://#diff-37d64a2aa66018cc6a40ca2227432eae6c33dd6c1456d19ef539e869ee9d4f72L364-R366)
[[2]](diffhunk://#diff-37d64a2aa66018cc6a40ca2227432eae6c33dd6c1456d19ef539e869ee9d4f72L375-R387)
[[3]](diffhunk://#diff-37d64a2aa66018cc6a40ca2227432eae6c33dd6c1456d19ef539e869ee9d4f72R566-R584)

Author: yuslepukhin

onnxruntime/core/framework/layering_annotations.cc

@@ -166,6 +166,7 @@ struct EpDeviceView {
   OrtDevice::DeviceType device_type;  // OrtDevice::CPU, GPU, NPU, FPGA, or kDeviceTypeUnknown
   uint32_t vendor_id;
   OrtDevice::DeviceId device_id;
+  bool has_device_ordinal;         // true when device_id is a runtime ordinal (from device_memory_info)
   std::string_view vendor_string;  // from OrtHardwareDevice::vendor (empty if unavailable)
 };
 
@@ -190,7 +191,11 @@ bool MatchEpDevice(const EpDeviceView& ep,
     if (ep.device_type == OrtDevice::GPU) {
       uint32_t index = std::numeric_limits<uint32_t>::max();
       if (TryParseIndex(std::string(target_specifier), index)) {
-        return ep.device_id == static_cast<OrtDevice::DeviceId>(index);
+        // Only match by ordinal index when the device_id is known to be a runtime
+        // ordinal (sourced from device_memory_info). OrtHardwareDevice::device_id is
+        // a PCI hardware-type identifier, not a device instance ordinal.
+        return ep.has_device_ordinal &&
+               ep.device_id == static_cast<OrtDevice::DeviceId>(index);
       }
       // gpu:<vendor>
       if (!ep.vendor_string.empty() && CaseInsensitiveCompare(ep.vendor_string, target_specifier)) {
@@ -285,13 +290,13 @@ std::optional<std::string> EpLayeringMatcher::Match(gsl::span<const OrtEpDevice*
         ep_device.ep_name,
         device_type,
         has_hw ? ep_device.device->vendor_id : 0u,
-        // Prefer the device ordinal from device_memory_info (set by the EP factory to
-        // a runtime device ordinal such as a CUDA ordinal) over the OrtHardwareDevice::device_id
-        // which is a hardware-type identifier and not guaranteed to be a stable runtime ordinal.
+        // Use the device ordinal from device_memory_info (set by the EP factory to
+        // a runtime device ordinal such as a CUDA ordinal). OrtHardwareDevice::device_id
+        // is a PCI hardware-type identifier and must not be used for index-based matching.
         ep_device.device_memory_info
             ? ep_device.device_memory_info->device.Id()
-            : (has_hw ? static_cast<OrtDevice::DeviceId>(ep_device.device->device_id)
-                      : OrtDevice::DeviceId{}),
+            : OrtDevice::DeviceId{},
+        /*has_device_ordinal=*/ep_device.device_memory_info != nullptr,
         has_hw ? std::string_view(ep_device.device->vendor) : std::string_view{}};
 
     if (MatchEpDevice(view, target_type_str, target_specifier, rule.device)) {
@@ -316,7 +321,8 @@ std::optional<std::string> EpLayeringMatcher::Match(const ExecutionProviders& pr
         device.Type(),
         device.Vendor(),
         device.Id(),
-        {}};  // no vendor string available from IExecutionProvider
+        /*has_device_ordinal=*/true,  // IExecutionProvider sets device Id to a runtime ordinal
+        {}};                          // no vendor string available from IExecutionProvider
 
     if (MatchEpDevice(view, target_type_str, target_specifier, rule.device)) {
       return std::string(ep.Type());
@@ -386,8 +392,10 @@ Status LayeringIndex::Create(const Graph& graph,
       LOGS(logger, VERBOSE) << "Layering Rule " << i << " (" << rule.device << " -> " << rule.annotation
                             << ") mapped to EP: " << ep_type;
     } else {
-      LOGS(logger, WARNING) << "Layering Rule " << i << " (" << rule.device << " -> " << rule.annotation
-                            << ") could not be mapped to any available Execution Provider.";
+      LOGS(logger, ERROR) << "Layering rule " << i << " (device='" << rule.device << "', annotation='" << rule.annotation
+                          << "') could not be mapped to any available Execution Provider. "
+                          << "If a numeric gpu index was specified (e.g. gpu:0), ensure an EP with a matching "
+                          << "device ordinal is registered and reports device_memory_info.";
     }
   }
 

onnxruntime/test/framework/layering_annotations_test.cc

@@ -361,9 +361,9 @@ TEST(EpLayeringMatcherTest, MatchSpecificGPU_Heuristic) {
 TEST(EpLayeringMatcherTest, MatchSpecificGPU_Index) {
   LayerAnnotation rule = {"gpu:1", "Anno1", false};
 
-  // Case 1: ID Match
+  // Case 1: ID Match via device_memory_info (runtime ordinal)
   {
-    auto test_ep = CreateHwEp("GPU1", OrtHardwareDeviceType_GPU, 0, 1);
+    auto test_ep = CreateMemEp("GPU1", OrtDevice::GPU, 1);
     OrtEpDevice ep_device = test_ep.Get();
     std::vector<const OrtEpDevice*> devices = {&ep_device};
 
@@ -372,9 +372,19 @@ TEST(EpLayeringMatcherTest, MatchSpecificGPU_Index) {
     EXPECT_EQ(*result, "GPU1");
   }
 
-  // Case 2: ID Mismatch
+  // Case 2: ID Mismatch via device_memory_info
   {
-    auto test_ep = CreateHwEp("GPU0", OrtHardwareDeviceType_GPU, 0, 0);
+    auto test_ep = CreateMemEp("GPU0", OrtDevice::GPU, 0);
+    OrtEpDevice ep_device = test_ep.Get();
+    std::vector<const OrtEpDevice*> devices = {&ep_device};
+    auto result = EpLayeringMatcher::Match(devices, rule);
+    EXPECT_FALSE(result.has_value());
+  }
+
+  // Case 3: HW-only device (no device_memory_info) must NOT match by index.
+  // OrtHardwareDevice::device_id is a PCI hardware-type ID, not an ordinal.
+  {
+    auto test_ep = CreateHwEp("GPU_HW_Only", OrtHardwareDeviceType_GPU, 0, 1);
     OrtEpDevice ep_device = test_ep.Get();
     std::vector<const OrtEpDevice*> devices = {&ep_device};
     auto result = EpLayeringMatcher::Match(devices, rule);
@@ -553,6 +563,25 @@ TEST(EpLayeringMatcherTest, MatchExecutionProviders_GPU_Specific) {
   EXPECT_EQ(*result, kCudaExecutionProvider);
 }
 
+TEST(EpLayeringMatcherTest, MatchExecutionProviders_GPU_Index) {
+  LayerAnnotation rule = {"gpu:1", "Anno1", false};
+  ExecutionProviders providers;
+
+  // Add GPU provider with ordinal 0 (should not match gpu:1)
+  auto gpu0_ep = std::make_shared<MockExecutionProvider>("GPU_EP_0",
+                                                         OrtDevice(OrtDevice::GPU, OrtDevice::MemType::DEFAULT, OrtDevice::VendorIds::NVIDIA, 0));
+  ASSERT_STATUS_OK(providers.Add("GPU_EP_0", gpu0_ep));
+
+  // Add GPU provider with ordinal 1 (should match gpu:1)
+  auto gpu1_ep = std::make_shared<MockExecutionProvider>("GPU_EP_1",
+                                                         OrtDevice(OrtDevice::GPU, OrtDevice::MemType::DEFAULT, OrtDevice::VendorIds::NVIDIA, 1));
+  ASSERT_STATUS_OK(providers.Add("GPU_EP_1", gpu1_ep));
+
+  auto result = EpLayeringMatcher::Match(providers, rule);
+  ASSERT_TRUE(result.has_value());
+  EXPECT_EQ(*result, "GPU_EP_1");
+}
+
 TEST(EpLayeringMatcherTest, MatchExecutionProviders_NoMatch) {
   LayerAnnotation rule = {"GPU", "Anno1", false};
   ExecutionProviders providers;