Add EP Device Compatibility APIs (microsoft#26922)

### Description
<!-- Describe your changes. -->
This PR adds new C API for querying hardware device and execution
provider (EP) compatibility/incompatibility reasons. The API allows
applications to determine why a specific EP may not be compatible with a
given hardware device before attempting to use it. The EP implementor
decides how device compatibility is defined for their stack and
communicates this via the possible states in the
OrtDeviceEpIncompatibilityDetails struct.

New API Functions
- GetHardwareDeviceEPIncompatibilityReasons - Query incompatibility
reasons between an EP and a hardware device
- DeviceEpIncompatibilityDetails_GetReasonsBitmask - Get a bitmask of
incompatibility reasons
- DeviceEpIncompatibilityDetails_GetErrorCode - Get an EP-specific error
code
- DeviceEpIncompatibilityDetails_GetNotes - Get optional human-readable
notes about incompatibility
- ReleaseDeviceEpIncompatibilityDetails - Release the details object

New Types
- OrtDeviceEpIncompatibilityDetails - Opaque type holding
incompatibility information
- OrtDeviceEpIncompatibilityReason - Enum defining standard
incompatibility reason flags

Testing
- Added unit tests in hardware_device_compatibility_test.cc for the new
C API functions
- Added plugin EP compatibility tests in test_execution.cc
. Tests verify both compatible (CPU device with CPU-supporting EP) and
incompatible (GPU device with CPU-only EP) scenarios
- Updated example plugin EP to implement the compatibility checking
interface

### Motivation and Context

Applications using ONNX Runtime need a way to understand why an
execution provider cannot run on a particular hardware device. This is
especially important for:

- User feedback - Providing meaningful error messages when hardware is
incompatible
- EP selection - Choosing the best available EP based on compatibility
- Diagnostics - Understanding driver/dependency requirements

Previously, there was no standardized way to query this information. EPs
would simply fail at session creation/model load/inference time without
providing actionable feedback.

Author: xhan65

include/onnxruntime/core/session/environment.h

@@ -146,6 +146,17 @@ class Environment {
     return execution_devices_;
   }
 
+  /// Get hardware device incompatibility details for a specific EP.
+  /// @param ep_name The name of the execution provider to check.
+  /// @param hw The hardware device to check for incompatibility.
+  /// @param details Output: Incompatibility details including reasons for incompatibility if any.
+  /// @returns Status indicating success or failure.
+  Status GetHardwareDeviceEpIncompatibilityDetails(const std::string& ep_name,
+                                                   const OrtHardwareDevice* hw,
+                                                   std::unique_ptr<OrtDeviceEpIncompatibilityDetails>& details) const;
+
+  const std::vector<const OrtHardwareDevice*>& GetSortedOrtHardwareDevices() const;
+
   Status CreateSharedAllocator(const OrtEpDevice& ep_device,
                                OrtDeviceMemoryType mem_type, OrtAllocatorType allocator_type,
                                const OrtKeyValuePairs* allocator_options, OrtAllocator** allocator);

include/onnxruntime/core/session/onnxruntime_c_api.h

@@ -1,4 +1,4 @@
-// Copyright (c) Microsoft Corporation. All rights reserved.
+// Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
 // See docs\c_cxx\README.md on generating the Doxygen documentation from this file
@@ -333,6 +333,7 @@ ORT_RUNTIME_CLASS(ExternalInitializerInfo);
 ORT_RUNTIME_CLASS(ExternalResourceImporter);  // Capability object for external resource import
 ORT_RUNTIME_CLASS(ExternalMemoryHandle);      // EP-imported view of shared external allocation
 ORT_RUNTIME_CLASS(ExternalSemaphoreHandle);   // EP-imported view of shared external semaphore
+ORT_RUNTIME_CLASS(DeviceEpIncompatibilityDetails);
 
 #ifdef _MSC_VER
 typedef _Return_type_success_(return == 0) OrtStatus* OrtStatusPtr;
@@ -510,6 +511,16 @@ typedef enum OrtExecutionProviderDevicePolicy {
   OrtExecutionProviderDevicePolicy_MIN_OVERALL_POWER,
 } OrtExecutionProviderDevicePolicy;
 
+/** \brief Reasons why an execution provider might not be compatible with a device
+ */
+typedef enum OrtDeviceEpIncompatibilityReason {
+  OrtDeviceEpIncompatibility_NONE = 0,
+  OrtDeviceEpIncompatibility_DRIVER_INCOMPATIBLE = 1 << 0,
+  OrtDeviceEpIncompatibility_DEVICE_INCOMPATIBLE = 1 << 1,
+  OrtDeviceEpIncompatibility_MISSING_DEPENDENCY = 1 << 2,
+  OrtDeviceEpIncompatibility_UNKNOWN = 1 << 31
+} OrtDeviceEpIncompatibilityReason;
+
 /** \brief Delegate to allow providing custom OrtEpDevice selection logic
  *
  * This delegate is called by the EP selection code to allow the user to provide custom device selection logic.
@@ -6784,6 +6795,121 @@ struct OrtApi {
   ORT_API2_STATUS(SessionGetEpDeviceForOutputs, _In_ const OrtSession* session,
                   _Out_writes_(num_outputs) const OrtEpDevice** outputs_ep_devices,
                   _In_ size_t num_outputs);
+  /** \brief Get the number of available hardware devices.
+   *
+   * Returns the count of hardware devices discovered on the system.
+   * Use this to allocate an array before calling GetHardwareDevices().
+   *
+   * \param[in] env The OrtEnv instance where device discovery results are stored.
+   * \param[out] num_devices The number of OrtHardwareDevice instances available.
+   *
+   * \snippet{doc} snippets.dox OrtStatus Return Value
+   *
+   * \since Version 1.24.
+   */
+  ORT_API2_STATUS(GetNumHardwareDevices, _In_ const OrtEnv* env, _Out_ size_t* num_devices);
+
+  /** \brief Get the list of available hardware devices.
+   *
+   * Enumerates hardware devices available on the system.
+   * Populates a user-provided array with pointers to OrtHardwareDevice instances. The caller is responsible
+   * for allocating the array with sufficient space (use GetNumHardwareDevices() to get the count).
+   *
+   * The returned pointers reference internal ORT data structures that are discovered once at process
+   * startup and remain valid for the lifetime of the OrtEnv. The caller does not need to release these
+   * pointers, but should not use them after calling ReleaseEnv().
+   *
+   * \param[in] env The OrtEnv instance where device discovery results are stored.
+   * \param[out] devices User-allocated array to receive pointers to OrtHardwareDevice instances.
+   *                     The array must have space for at least num_devices elements.
+   * \param[in] num_devices The size of the user-allocated devices array.
+   *
+   * \snippet{doc} snippets.dox OrtStatus Return Value
+   *
+   * \since Version 1.24.
+   */
+  ORT_API2_STATUS(GetHardwareDevices, _In_ const OrtEnv* env,
+                  _Out_writes_(num_devices) const OrtHardwareDevice** devices,
+                  _In_ size_t num_devices);
+
+  /** \brief Check for known incompatibility issues between hardware device and a specific execution provider.
+   *
+   * This function checks for known incompatibility issues between the specified hardware device
+   * and a specific execution provider.
+   * If returned incompatibility details have non-zero reasons, it indicates the device is not compatible.
+   * However, if returned detail have reason == 0, it doesn't guarantee 100% compatibility for all models,
+   * as models may have specific requirements.
+   *
+   * Note: This method should only be called when the OrtEnv has been initialized with execution
+   * providers (after RegisterExecutionProviderLibrary is called).
+   *
+   * \param[in] env The OrtEnv instance with registered execution providers.
+   * \param[in] ep_name The name of the execution provider to check. Required and cannot be null or empty.
+   * \param[in] hw The hardware device to check for incompatibility.
+   * \param[out] details Compatibility details including reasons for incompatibility if any.
+   *                     Must be freed with OrtApi::ReleaseDeviceEpIncompatibilityDetails.
+   *
+   * \snippet{doc} snippets.dox OrtStatus Return Value
+   *
+   * \since Version 1.24.
+   */
+  ORT_API2_STATUS(GetHardwareDeviceEpIncompatibilityDetails, _In_ const OrtEnv* env,
+                  _In_ const char* ep_name,
+                  _In_ const OrtHardwareDevice* hw,
+                  _Outptr_ OrtDeviceEpIncompatibilityDetails** details);
+
+  /// \name OrtDeviceEpIncompatibilityDetails
+  /// Accessor functions for device incompatibility details
+  /// @{
+
+  /** \brief Get the incompatibility reasons bitmask from OrtDeviceEpIncompatibilityDetails.
+   *
+   * \param[in] details The OrtDeviceEpIncompatibilityDetails instance to query.
+   * \param[out] reasons_bitmask Pointer to store the bitmask of incompatibility reasons.
+   *
+   * \snippet{doc} snippets.dox OrtStatus Return Value
+   *
+   * \since Version 1.24.
+   */
+  ORT_API2_STATUS(DeviceEpIncompatibilityDetails_GetReasonsBitmask,
+                  _In_ const OrtDeviceEpIncompatibilityDetails* details,
+                  _Out_ uint32_t* reasons_bitmask);
+
+  /** \brief Get the notes from OrtDeviceEpIncompatibilityDetails.
+   *
+   * \param[in] details The OrtDeviceEpIncompatibilityDetails instance to query.
+   * \param[out] notes Pointer to the notes string. May be nullptr if no notes are available.
+   *                   The returned string is owned by the details object and should not be freed.
+   *
+   * \snippet{doc} snippets.dox OrtStatus Return Value
+   *
+   * \since Version 1.24.
+   */
+  ORT_API2_STATUS(DeviceEpIncompatibilityDetails_GetNotes,
+                  _In_ const OrtDeviceEpIncompatibilityDetails* details,
+                  _Outptr_result_maybenull_ const char** notes);
+
+  /** \brief Get the execution provider error code from OrtDeviceEpIncompatibilityDetails.
+   *
+   * This allows Independent Hardware Vendors (IHVs) to define their own error codes
+   * to provide additional details about device incompatibility.
+   *
+   * \param[in] details The OrtDeviceEpIncompatibilityDetails instance to query.
+   * \param[out] error_code Pointer to store the EP-specific error code. A value of 0 indicates no error code was set.
+   *
+   * \snippet{doc} snippets.dox OrtStatus Return Value
+   *
+   * \since Version 1.24.
+   */
+  ORT_API2_STATUS(DeviceEpIncompatibilityDetails_GetErrorCode,
+                  _In_ const OrtDeviceEpIncompatibilityDetails* details,
+                  _Out_ int32_t* error_code);
+
+  /** \brief Release an OrtDeviceEpIncompatibilityDetails instance.
+   *
+   * \since Version 1.24.
+   */
+  ORT_CLASS_RELEASE(DeviceEpIncompatibilityDetails);
 
   /// @}
 };

include/onnxruntime/core/session/onnxruntime_ep_c_api.h

@@ -1308,6 +1308,27 @@ struct OrtEpApi {
    */
   ORT_API2_STATUS(KernelInfo_GetEp, _In_ const OrtKernelInfo* info, _Outptr_ const OrtEp** ep);
 
+  /** \brief Set the details of an OrtDeviceEpIncompatibilityDetails instance.
+   *
+   * Used by execution provider factories to set incompatibility details in their
+   * GetHardwareDeviceIncompatibilityDetails implementation. ORT creates and initializes the object
+   * before passing it to the EP, so calling this function is optional. The EP uses this function
+   * to set incompatibility information when the device is not compatible.
+   *
+   * \param[in,out] details The OrtDeviceEpIncompatibilityDetails instance to update.
+   * \param[in] reasons_bitmask Bitmask of OrtDeviceEpIncompatibilityReason values. (0 = no incompatibility).
+   * \param[in] error_code Optional EP-specific error code (0 = no error).
+   * \param[in] notes Optional human-readable notes. Can be null.
+   *
+   * \snippet{doc} snippets.dox OrtStatus Return Value
+   *
+   * \since Version 1.24.
+   */
+  ORT_API2_STATUS(DeviceEpIncompatibilityDetails_SetDetails, _Inout_ OrtDeviceEpIncompatibilityDetails* details,
+                  _In_ uint32_t reasons_bitmask,
+                  _In_ int32_t error_code,
+                  _In_opt_z_ const char* notes);
+
   /** \brief Creates an OrtKernelImpl instance for an If operator.
    *
    * Control flow operators require access to ORT session internals to orchestrate subgraph operations.
@@ -1990,6 +2011,30 @@ struct OrtEpFactory {
    */
   ORT_API2_STATUS(SetEnvironmentOptions, _In_ OrtEpFactory* this_ptr, _In_ const OrtKeyValuePairs* options);
 
+  /** \brief Check for known incompatibility reasons between a hardware device and this execution provider.
+   *
+   * This function allows an execution provider to check if a specific hardware device is compatible
+   * with the execution provider. The EP can set specific incompatibility reasons via the
+   * OrtDeviceEpIncompatibilityDetails parameter using OrtEpApi::DeviceEpIncompatibilityDetails_SetDetails.
+   *
+   * \param[in] this_ptr The OrtEpFactory instance.
+   * \param[in] hw The hardware device to check for incompatibility.
+   * \param[in,out] details Pre-allocated incompatibility details object created and initialized by ORT.
+   *                        The EP can use OrtEpApi::DeviceEpIncompatibilityDetails_SetDetails to set
+   *                        incompatibility information. If the device is compatible, the EP can
+   *                        leave the object unchanged (it defaults to no incompatibility).
+   *
+   * \note Implementation of this function is optional.
+   *       If not implemented, ORT will assume the device is compatible with this EP.
+   *
+   * \snippet{doc} snippets.dox OrtStatus Return Value
+   *
+   * \since Version 1.24.
+   */
+  ORT_API2_STATUS(GetHardwareDeviceIncompatibilityDetails, _In_ OrtEpFactory* this_ptr,
+                  _In_ const OrtHardwareDevice* hw,
+                  _Inout_ OrtDeviceEpIncompatibilityDetails* details);
+
   /** \brief Create an OrtExternalResourceImporterImpl for external resource import.
    *
    * This is used to create an external resource importer that enables zero-copy import of

onnxruntime/core/session/abi_devices.h

@@ -75,3 +75,9 @@ struct OrtEpDevice {
   // get/create methods to be as flexible as possible. this helper converts to a non-const factory instance.
   OrtEpFactory* GetMutableFactory() const { return ep_factory; }
 };
+
+struct OrtDeviceEpIncompatibilityDetails {
+  uint32_t reasons_bitmask{0};  // Bitmask of OrtDeviceEpIncompatibilityReason values
+  int32_t error_code{0};        // EP-specific error code (0 = no error)
+  std::string notes;            // Additional human-readable notes
+};