Add EP Device Compatibility APIs by xhan65 · Pull Request #26922 · microsoft/onnxruntime

adrianlizarraga

adrianlizarraga

adrianlizarraga

edgchen1

github-advanced-security[bot]

@xhan65 xhan65 marked this pull request as ready for review

January 12, 2026 04:26

javier-intel

edgchen1

github-advanced-security[bot]

adrianlizarraga

javier-intel

@xhan65

adrianlizarraga

alex-spacemit pushed a commit to spacemit-com/onnxruntime that referenced this pull request

Jan 20, 2026
### 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.

alex-spacemit pushed a commit to spacemit-com/onnxruntime that referenced this pull request

Jan 27, 2026
<!-- 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

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.

This was referenced

Feb 9, 2026

This was referenced

Feb 23, 2026