|
1 | | -// Copyright (c) Microsoft Corporation. All rights reserved. |
| 1 | +// Copyright (c) Microsoft Corporation. All rights reserved. |
2 | 2 | // Licensed under the MIT License. |
3 | 3 |
|
4 | 4 | // See docs\c_cxx\README.md on generating the Doxygen documentation from this file |
@@ -333,6 +333,7 @@ ORT_RUNTIME_CLASS(ExternalInitializerInfo); |
333 | 333 | ORT_RUNTIME_CLASS(ExternalResourceImporter); // Capability object for external resource import |
334 | 334 | ORT_RUNTIME_CLASS(ExternalMemoryHandle); // EP-imported view of shared external allocation |
335 | 335 | ORT_RUNTIME_CLASS(ExternalSemaphoreHandle); // EP-imported view of shared external semaphore |
| 336 | +ORT_RUNTIME_CLASS(DeviceEpIncompatibilityDetails); |
336 | 337 | ORT_RUNTIME_CLASS(EpAssignedSubgraph); |
337 | 338 | ORT_RUNTIME_CLASS(EpAssignedNode); |
338 | 339 |
|
@@ -512,6 +513,16 @@ typedef enum OrtExecutionProviderDevicePolicy { |
512 | 513 | OrtExecutionProviderDevicePolicy_MIN_OVERALL_POWER, |
513 | 514 | } OrtExecutionProviderDevicePolicy; |
514 | 515 |
|
| 516 | +/** \brief Reasons why an execution provider might not be compatible with a device |
| 517 | + */ |
| 518 | +typedef enum OrtDeviceEpIncompatibilityReason { |
| 519 | + OrtDeviceEpIncompatibility_NONE = 0, |
| 520 | + OrtDeviceEpIncompatibility_DRIVER_INCOMPATIBLE = 1 << 0, |
| 521 | + OrtDeviceEpIncompatibility_DEVICE_INCOMPATIBLE = 1 << 1, |
| 522 | + OrtDeviceEpIncompatibility_MISSING_DEPENDENCY = 1 << 2, |
| 523 | + OrtDeviceEpIncompatibility_UNKNOWN = 1 << 31 |
| 524 | +} OrtDeviceEpIncompatibilityReason; |
| 525 | + |
515 | 526 | /** \brief Delegate to allow providing custom OrtEpDevice selection logic |
516 | 527 | * |
517 | 528 | * This delegate is called by the EP selection code to allow the user to provide custom device selection logic. |
@@ -6786,6 +6797,123 @@ struct OrtApi { |
6786 | 6797 | ORT_API2_STATUS(SessionGetEpDeviceForOutputs, _In_ const OrtSession* session, |
6787 | 6798 | _Out_writes_(num_outputs) const OrtEpDevice** outputs_ep_devices, |
6788 | 6799 | _In_ size_t num_outputs); |
| 6800 | + /** \brief Get the number of available hardware devices. |
| 6801 | + * |
| 6802 | + * Returns the count of hardware devices discovered on the system. |
| 6803 | + * Use this to allocate an array before calling GetHardwareDevices(). |
| 6804 | + * |
| 6805 | + * \param[in] env The OrtEnv instance where device discovery results are stored. |
| 6806 | + * \param[out] num_devices The number of OrtHardwareDevice instances available. |
| 6807 | + * |
| 6808 | + * \snippet{doc} snippets.dox OrtStatus Return Value |
| 6809 | + * |
| 6810 | + * \since Version 1.24. |
| 6811 | + */ |
| 6812 | + ORT_API2_STATUS(GetNumHardwareDevices, _In_ const OrtEnv* env, _Out_ size_t* num_devices); |
| 6813 | + |
| 6814 | + /** \brief Get the list of available hardware devices. |
| 6815 | + * |
| 6816 | + * Enumerates hardware devices available on the system. |
| 6817 | + * Populates a user-provided array with pointers to OrtHardwareDevice instances. The caller is responsible |
| 6818 | + * for allocating the array with sufficient space (use GetNumHardwareDevices() to get the count). |
| 6819 | + * |
| 6820 | + * The returned pointers reference internal ORT data structures that are discovered once at process |
| 6821 | + * startup and remain valid for the lifetime of the OrtEnv. The caller does not need to release these |
| 6822 | + * pointers, but should not use them after calling ReleaseEnv(). |
| 6823 | + * |
| 6824 | + * \param[in] env The OrtEnv instance where device discovery results are stored. |
| 6825 | + * \param[out] devices User-allocated array to receive pointers to OrtHardwareDevice instances. |
| 6826 | + * The array must have space for at least num_devices elements. |
| 6827 | + * \param[in] num_devices The size of the user-allocated devices array. |
| 6828 | + * |
| 6829 | + * \snippet{doc} snippets.dox OrtStatus Return Value |
| 6830 | + * |
| 6831 | + * \since Version 1.24. |
| 6832 | + */ |
| 6833 | + ORT_API2_STATUS(GetHardwareDevices, _In_ const OrtEnv* env, |
| 6834 | + _Out_writes_(num_devices) const OrtHardwareDevice** devices, |
| 6835 | + _In_ size_t num_devices); |
| 6836 | + |
| 6837 | + /** \brief Check for known incompatibility issues between hardware device and a specific execution provider. |
| 6838 | + * |
| 6839 | + * This function checks for known incompatibility issues between the specified hardware device |
| 6840 | + * and a specific execution provider. |
| 6841 | + * If returned incompatibility details have non-zero reasons, it indicates the device is not compatible. |
| 6842 | + * However, if returned detail have reason == 0, it doesn't guarantee 100% compatibility for all models, |
| 6843 | + * as models may have specific requirements. |
| 6844 | + * |
| 6845 | + * Note: This method should only be called when the OrtEnv has been initialized with execution |
| 6846 | + * providers (after RegisterExecutionProviderLibrary is called). |
| 6847 | + * |
| 6848 | + * \param[in] env The OrtEnv instance with registered execution providers. |
| 6849 | + * \param[in] ep_name The name of the execution provider to check. Required and cannot be null or empty. |
| 6850 | + * \param[in] hw The hardware device to check for incompatibility. |
| 6851 | + * \param[out] details Compatibility details including reasons for incompatibility if any. |
| 6852 | + * Must be freed with OrtApi::ReleaseDeviceEpIncompatibilityDetails. |
| 6853 | + * |
| 6854 | + * \snippet{doc} snippets.dox OrtStatus Return Value |
| 6855 | + * |
| 6856 | + * \since Version 1.24. |
| 6857 | + */ |
| 6858 | + ORT_API2_STATUS(GetHardwareDeviceEpIncompatibilityDetails, _In_ const OrtEnv* env, |
| 6859 | + _In_ const char* ep_name, |
| 6860 | + _In_ const OrtHardwareDevice* hw, |
| 6861 | + _Outptr_ OrtDeviceEpIncompatibilityDetails** details); |
| 6862 | + |
| 6863 | + /// \name OrtDeviceEpIncompatibilityDetails |
| 6864 | + /// Accessor functions for device incompatibility details |
| 6865 | + /// @{ |
| 6866 | + |
| 6867 | + /** \brief Get the incompatibility reasons bitmask from OrtDeviceEpIncompatibilityDetails. |
| 6868 | + * |
| 6869 | + * \param[in] details The OrtDeviceEpIncompatibilityDetails instance to query. |
| 6870 | + * \param[out] reasons_bitmask Pointer to store the bitmask of incompatibility reasons. |
| 6871 | + * |
| 6872 | + * \snippet{doc} snippets.dox OrtStatus Return Value |
| 6873 | + * |
| 6874 | + * \since Version 1.24. |
| 6875 | + */ |
| 6876 | + ORT_API2_STATUS(DeviceEpIncompatibilityDetails_GetReasonsBitmask, |
| 6877 | + _In_ const OrtDeviceEpIncompatibilityDetails* details, |
| 6878 | + _Out_ uint32_t* reasons_bitmask); |
| 6879 | + |
| 6880 | + /** \brief Get the notes from OrtDeviceEpIncompatibilityDetails. |
| 6881 | + * |
| 6882 | + * \param[in] details The OrtDeviceEpIncompatibilityDetails instance to query. |
| 6883 | + * \param[out] notes Pointer to the notes string. May be nullptr if no notes are available. |
| 6884 | + * The returned string is owned by the details object and should not be freed. |
| 6885 | + * |
| 6886 | + * \snippet{doc} snippets.dox OrtStatus Return Value |
| 6887 | + * |
| 6888 | + * \since Version 1.24. |
| 6889 | + */ |
| 6890 | + ORT_API2_STATUS(DeviceEpIncompatibilityDetails_GetNotes, |
| 6891 | + _In_ const OrtDeviceEpIncompatibilityDetails* details, |
| 6892 | + _Outptr_result_maybenull_ const char** notes); |
| 6893 | + |
| 6894 | + /** \brief Get the execution provider error code from OrtDeviceEpIncompatibilityDetails. |
| 6895 | + * |
| 6896 | + * This allows Independent Hardware Vendors (IHVs) to define their own error codes |
| 6897 | + * to provide additional details about device incompatibility. |
| 6898 | + * |
| 6899 | + * \param[in] details The OrtDeviceEpIncompatibilityDetails instance to query. |
| 6900 | + * \param[out] error_code Pointer to store the EP-specific error code. A value of 0 indicates no error code was set. |
| 6901 | + * |
| 6902 | + * \snippet{doc} snippets.dox OrtStatus Return Value |
| 6903 | + * |
| 6904 | + * \since Version 1.24. |
| 6905 | + */ |
| 6906 | + ORT_API2_STATUS(DeviceEpIncompatibilityDetails_GetErrorCode, |
| 6907 | + _In_ const OrtDeviceEpIncompatibilityDetails* details, |
| 6908 | + _Out_ int32_t* error_code); |
| 6909 | + |
| 6910 | + /** \brief Release an OrtDeviceEpIncompatibilityDetails instance. |
| 6911 | + * |
| 6912 | + * \since Version 1.24. |
| 6913 | + */ |
| 6914 | + ORT_CLASS_RELEASE(DeviceEpIncompatibilityDetails); |
| 6915 | + |
| 6916 | + /// @} |
6789 | 6917 |
|
6790 | 6918 | /** \brief Get information about the subgraphs assigned to each EP and the nodes within. |
6791 | 6919 | * |
|
0 commit comments