Refactor EPContext data callbacks for EP-owned I/O

Author: Gopalakrishnan Nallasamy

VERSION_NUMBER

@@ -1 +1 @@
-1.27.0
+1.28.0

include/onnxruntime/core/session/onnxruntime_c_api.h

@@ -38,7 +38,7 @@
  *
  * This value is used by some API functions to behave as this version of the header expects.
  */
-#define ORT_API_VERSION 27
+#define ORT_API_VERSION 28
 
 #ifdef __cplusplus
 extern "C" {
@@ -595,9 +595,9 @@ typedef OrtStatus*(ORT_API_CALL* OrtWriteBufferFunc)(_In_ void* state,
 
 /** \brief Function called to write EPContext binary data during compilation.
  *
- * This function is called synchronously by OrtEpApi::WriteEpContextData on the calling thread. ORT does not retain
- * buffer after the callback returns, does not reorder callback invocations, and does not serialize invocations made by
- * different EP instances or EP worker threads.
+ * This function is called synchronously by the execution provider on the calling thread. ORT does not own or retain
+ * buffer after the callback returns. ORT does not serialize invocations made by different EP instances or EP worker
+ * threads.
  *
  * Each callback invocation represents one complete write operation for file_name. The callback signature does not
  * provide an offset, sequence number, or final-chunk marker, so EPs that need chunked streaming must define their own
@@ -627,8 +627,8 @@ typedef OrtStatus*(ORT_API_CALL* OrtWriteEpContextDataFunc)(_In_ void* state,
  *
  * The application reads, processes (e.g., decrypts, decompresses, downloads), and returns the EPContext binary data.
  * ORT provides an allocator so the application can allocate the output buffer directly. The callback is called
- * synchronously by OrtEpApi::ReadEpContextData on the calling thread. ORT does not serialize invocations made by
- * different EP instances or EP worker threads.
+ * synchronously by the execution provider on the calling thread. ORT does not serialize invocations made by different
+ * EP instances or EP worker threads.
  *
  * \param[in] state Opaque pointer holding the user's state. ORT does not own or manage this pointer. The application
  *                  must keep it valid while any session or EP created from the associated OrtSessionOptions may invoke
@@ -7539,8 +7539,8 @@ struct OrtApi {
 
   /** \brief Registers a callback to provide EPContext binary data during session load.
    *
-   * When loading a compiled model with external (non-embedded) EPContext binary data, an execution provider can use
-   * OrtEpApi::ReadEpContextData to call this callback instead of reading the binary data from disk.
+   * When loading a compiled model with external (non-embedded) EPContext binary data, an execution provider can
+   * retrieve this callback from OrtEpContextConfig and call it instead of reading the binary data from disk.
    *
    * The state pointer is stored as-is and is not owned by ORT. It must remain valid while any session or EP created
    * from these options may call the callback. If the same state may be used by multiple EPs or threads, the application
@@ -7552,7 +7552,7 @@ struct OrtApi {
    *
    * \snippet{doc} snippets.dox OrtStatus Return Value
    *
-   * \since Version 1.27.
+   * \since Version 1.28.
    */
   ORT_API2_STATUS(SessionOptions_SetEpContextDataReadFunc, _Inout_ OrtSessionOptions* options,
                   _In_ OrtReadEpContextDataFunc read_func, _In_opt_ void* state);
@@ -8380,8 +8380,8 @@ struct OrtCompileApi {
 
   /** \brief Sets a callback for writing EPContext binary data during compilation.
    *
-   * When EPContext embed mode is disabled, execution providers can use OrtEpApi::WriteEpContextData to call this
-   * callback instead of writing EPContext binary data directly to disk.
+   * When EPContext embed mode is disabled, execution providers can retrieve this callback from OrtEpContextConfig and
+   * call it instead of writing EPContext binary data directly to disk.
    *
    * The state pointer is stored as-is and is not owned by ORT. It must remain valid for the duration of the compile
    * operation that may call the callback. If the same state may be used by multiple EPs or threads, the application is
@@ -8393,7 +8393,7 @@ struct OrtCompileApi {
    *
    * \snippet{doc} snippets.dox OrtStatus Return Value
    *
-   * \since Version 1.27.
+   * \since Version 1.28.
    */
   ORT_API2_STATUS(ModelCompilationOptions_SetEpContextDataWriteFunc,
                   _In_ OrtModelCompilationOptions* model_compile_options,

include/onnxruntime/core/session/onnxruntime_cxx_api.h

@@ -658,6 +658,7 @@ ORT_DEFINE_RELEASE(Value);
 ORT_DEFINE_RELEASE(ValueInfo);
 
 ORT_DEFINE_RELEASE_FROM_API_STRUCT(ModelCompilationOptions, GetCompileApi);
+ORT_DEFINE_RELEASE_FROM_API_STRUCT(EpContextConfig, GetEpApi);
 ORT_DEFINE_RELEASE_FROM_API_STRUCT(EpDevice, GetEpApi);
 ORT_DEFINE_RELEASE_FROM_API_STRUCT(KernelDef, GetEpApi);
 ORT_DEFINE_RELEASE_FROM_API_STRUCT(KernelDefBuilder, GetEpApi);
@@ -786,6 +787,7 @@ struct AllocatedFree {
 
 struct AllocatorWithDefaultOptions;
 struct Env;
+struct EpContextConfig;
 struct EpDevice;
 struct ExternalInitializerInfo;
 struct Graph;
@@ -1185,6 +1187,21 @@ struct EpDevice : detail::EpDeviceImpl<OrtEpDevice> {
            ConstKeyValuePairs ep_metadata = {}, ConstKeyValuePairs ep_options = {});
 };
 
+/** \brief Owning wrapper around ::OrtEpContextConfig. */
+struct EpContextConfig : detail::Base<OrtEpContextConfig> {
+  explicit EpContextConfig(std::nullptr_t) {}                                       ///< No instance is created
+  explicit EpContextConfig(OrtEpContextConfig* p) : Base<OrtEpContextConfig>{p} {}  ///< Take ownership
+
+  /// \brief Wraps OrtEpApi::SessionOptions_GetEpContextConfig
+  explicit EpContextConfig(const OrtSessionOptions* session_options);
+
+  /// \brief Wraps OrtEpApi::EpContextConfig_GetEpContextDataReadFunc
+  std::pair<OrtReadEpContextDataFunc, void*> GetEpContextDataReadFunc() const;
+
+  /// \brief Wraps OrtEpApi::EpContextConfig_GetEpContextDataWriteFunc
+  std::pair<OrtWriteEpContextDataFunc, void*> GetEpContextDataWriteFunc() const;
+};
+
 /** \brief Validate a compiled model's compatibility for one or more EP devices.
  *
  * Throws on error. Returns the resulting compatibility status.

include/onnxruntime/core/session/onnxruntime_cxx_inline.h

@@ -769,6 +769,24 @@ inline EpDevice::EpDevice(OrtEpFactory& ep_factory, ConstHardwareDevice& hardwar
   ThrowOnError(GetEpApi().CreateEpDevice(&ep_factory, hardware_device, ep_metadata, ep_options, &p_));
 }
 
+inline EpContextConfig::EpContextConfig(const OrtSessionOptions* session_options) {
+  ThrowOnError(GetEpApi().SessionOptions_GetEpContextConfig(session_options, &p_));
+}
+
+inline std::pair<OrtReadEpContextDataFunc, void*> EpContextConfig::GetEpContextDataReadFunc() const {
+  OrtReadEpContextDataFunc read_func = nullptr;
+  void* state = nullptr;
+  ThrowOnError(GetEpApi().EpContextConfig_GetEpContextDataReadFunc(this->p_, &read_func, &state));
+  return {read_func, state};
+}
+
+inline std::pair<OrtWriteEpContextDataFunc, void*> EpContextConfig::GetEpContextDataWriteFunc() const {
+  OrtWriteEpContextDataFunc write_func = nullptr;
+  void* state = nullptr;
+  ThrowOnError(GetEpApi().EpContextConfig_GetEpContextDataWriteFunc(this->p_, &write_func, &state));
+  return {write_func, state};
+}
+
 namespace detail {
 template <typename T>
 inline std::string EpAssignedSubgraphImpl<T>::GetEpName() const {

include/onnxruntime/core/session/onnxruntime_ep_c_api.h

@@ -2087,14 +2087,14 @@ struct OrtEpApi {
    *
    * The returned handle owns only ORT's copy of callback function pointers and opaque state pointer values. It does not
    * own the application-provided state. The application is responsible for keeping callback state valid and
-   * synchronized while an EP may call ReadEpContextData or WriteEpContextData with this config.
+   * synchronized while an EP may call callbacks retrieved from this config.
    *
    * \param[in] session_options The OrtSessionOptions instance.
    * \param[out] config The extracted OrtEpContextConfig.
    *
    * \snippet{doc} snippets.dox OrtStatus Return Value
    *
-   * \since Version 1.27.
+   * \since Version 1.28.
    */
   ORT_API2_STATUS(SessionOptions_GetEpContextConfig,
                   _In_ const OrtSessionOptions* session_options,
@@ -2104,66 +2104,49 @@ struct OrtEpApi {
    *
    * \param[in] input The OrtEpContextConfig instance to release. May be NULL.
    *
-   * \since Version 1.27.
+   * \since Version 1.28.
    */
   ORT_CLASS_RELEASE(EpContextConfig);
 
-  /** \brief Read EPContext binary data, using an application read callback or falling back to disk.
+  /** \brief Get the application-provided EPContext data read callback.
    *
-   * If config contains a read callback, the callback is invoked with the provided allocator. Otherwise, ORT reads the
-   * file from disk. The disk fallback derives the base directory from the graph's model path.
+   * Returns the OrtReadEpContextDataFunc and opaque state pointer registered via
+   * OrtApi::SessionOptions_SetEpContextDataReadFunc. If no callback was registered, *read_func and *state are set to
+   * NULL. The EP is responsible for calling the callback when present and for using its own normal read path when no
+   * callback is present.
    *
-   * This function is synchronous. If a callback is present, it is invoked on the calling thread and its OrtStatus is
-   * returned to the caller. ORT does not serialize concurrent calls across EP instances or EP worker threads.
-   *
-   * \param[in] config The OrtEpContextConfig from SessionOptions_GetEpContextConfig. May be NULL for disk fallback.
-   * \param[in] file_name EPContext file name as a null-terminated UTF-8 string.
-   * \param[in] graph The OrtGraph from which ORT derives the model path for disk fallback. May be NULL.
-   * \param[in] allocator Allocator for the output buffer.
-   * \param[out] buffer Output buffer containing the EPContext binary data.
-   * \param[out] buffer_size Size of the output buffer in bytes.
+   * \param[in] config The OrtEpContextConfig from SessionOptions_GetEpContextConfig.
+   * \param[out] read_func The registered read callback, or NULL if none was registered.
+   * \param[out] state Opaque state pointer passed to read_func, or NULL if none was registered.
    *
    * \snippet{doc} snippets.dox OrtStatus Return Value
    *
-   * \since Version 1.27.
+   * \since Version 1.28.
    */
-  ORT_API2_STATUS(ReadEpContextData,
-                  _In_opt_ const OrtEpContextConfig* config,
-                  _In_ const char* file_name,
-                  _In_opt_ const OrtGraph* graph,
-                  _Inout_ OrtAllocator* allocator,
-                  _Outptr_ void** buffer,
-                  _Out_ size_t* buffer_size);
+  ORT_API2_STATUS(EpContextConfig_GetEpContextDataReadFunc,
+                  _In_ const OrtEpContextConfig* config,
+                  _Out_ OrtReadEpContextDataFunc* read_func,
+                  _Out_ void** state);
 
-  /** \brief Write EPContext binary data, using an application write callback or falling back to disk.
+  /** \brief Get the application-provided EPContext data write callback.
    *
-   * If config contains a write callback, the data is forwarded to the application's callback. Otherwise, ORT writes the
-   * data to disk. The disk fallback derives the base directory from the graph's model path.
+   * Returns the OrtWriteEpContextDataFunc and opaque state pointer registered via
+   * OrtCompileApi::ModelCompilationOptions_SetEpContextDataWriteFunc. If no callback was registered, *write_func and
+   * *state are set to NULL. The EP is responsible for calling the callback when present and for using its own normal
+   * write path when no callback is present.
    *
-   * This function is synchronous. If a callback is present, it is invoked on the calling thread and its OrtStatus is
-   * returned to the caller. ORT does not retain buffer after the callback returns, reorder callback invocations, or
-   * serialize concurrent calls across EP instances or EP worker threads.
-   *
-   * Each call is one complete write operation for file_name. The API does not provide an offset, sequence number, or
-   * final-chunk marker. EPs should prefer one call per EPContext binary, or document EP-specific chunk ordering and
-   * completion semantics if multiple calls are made for the same file_name.
-   *
-   * \param[in] config The OrtEpContextConfig from SessionOptions_GetEpContextConfig. May be NULL for disk fallback.
-   * \param[in] file_name EPContext file name as a null-terminated UTF-8 string.
-   * \param[in] graph The OrtGraph from which ORT derives the model path for disk fallback. May be NULL.
-   * \param[in] buffer The buffer containing EPContext binary data to write.
-   * \param[in] buffer_size Size of the buffer in bytes.
+   * \param[in] config The OrtEpContextConfig from SessionOptions_GetEpContextConfig.
+   * \param[out] write_func The registered write callback, or NULL if none was registered.
+   * \param[out] state Opaque state pointer passed to write_func, or NULL if none was registered.
    *
    * \snippet{doc} snippets.dox OrtStatus Return Value
    *
-   * \since Version 1.27.
+   * \since Version 1.28.
    */
-  ORT_API2_STATUS(WriteEpContextData,
-                  _In_opt_ const OrtEpContextConfig* config,
-                  _In_ const char* file_name,
-                  _In_opt_ const OrtGraph* graph,
-                  _In_ const void* buffer,
-                  _In_ size_t buffer_size);
+  ORT_API2_STATUS(EpContextConfig_GetEpContextDataWriteFunc,
+                  _In_ const OrtEpContextConfig* config,
+                  _Out_ OrtWriteEpContextDataFunc* write_func,
+                  _Out_ void** state);
 };
 
 /**

onnxruntime/core/session/compile_api.cc

@@ -393,6 +393,9 @@ static constexpr OrtCompileApi ort_compile_api = {
 
     &OrtCompileAPI::ModelCompilationOptions_SetInputModel,
     // End of Version 24 - DO NOT MODIFY ABOVE
+    // End of Version 25 - DO NOT MODIFY ABOVE
+    // End of Version 26 - DO NOT MODIFY ABOVE
+    // End of Version 27 - DO NOT MODIFY ABOVE
 
     &OrtCompileAPI::ModelCompilationOptions_SetEpContextDataWriteFunc,
 };
@@ -404,6 +407,8 @@ static_assert(offsetof(OrtCompileApi, ModelCompilationOptions_SetOutputModelGetI
               "Size of version 23 of Api cannot change");
 static_assert(offsetof(OrtCompileApi, ModelCompilationOptions_SetInputModel) / sizeof(void*) == 14,
               "Size of version 24 of Api cannot change");
+static_assert(offsetof(OrtCompileApi, ModelCompilationOptions_SetInputModel) / sizeof(void*) == 14,
+              "Size of version 27 of Api cannot change");
 
 ORT_API(const OrtCompileApi*, OrtCompileAPI::GetCompileApi) {
   return &ort_compile_api;

onnxruntime/core/session/onnxruntime_c_api.cc

@@ -4415,7 +4415,7 @@ Second example, if we wanted to add and remove some members, we'd do this:
     In GetApi we now make it return ort_api_3 for version 3.
 */
 
-static constexpr OrtApi ort_api_1_to_27 = {
+static constexpr OrtApi ort_api_1_to_28 = {
     // NOTE: The ordering of these fields MUST not change after that version has shipped since existing binaries depend on this ordering.
 
     // Shipped as version 1 - DO NOT MODIFY (see above text for more information)
@@ -4926,6 +4926,8 @@ static constexpr OrtApi ort_api_1_to_27 = {
     &OrtApis::GetMemPatternEnabled,
     &OrtApis::GetSessionExecutionMode,
     &OrtApis::SessionReleaseCapturedGraph,
+    // End of Version 27 - DO NOT MODIFY ABOVE (see above text for more information)
+
     &OrtApis::SessionOptions_SetEpContextDataReadFunc,
 };
 
@@ -4966,9 +4968,10 @@ static_assert(offsetof(OrtApi, CreateExternalInitializerInfo) / sizeof(void*) ==
 static_assert(offsetof(OrtApi, GetTensorElementTypeAndShapeDataReference) / sizeof(void*) == 414, "Size of version 24 API cannot change");
 static_assert(offsetof(OrtApi, SetPerSessionThreadPoolCallbacks) / sizeof(void*) == 418, "Size of version 25 API cannot change");
 // no additions in version 26
+static_assert(offsetof(OrtApi, GetSessionExecutionMode) / sizeof(void*) == 420, "Size of version 27 API cannot change");
 
 // So that nobody forgets to finish an API version, this check will serve as a reminder:
-static_assert(std::string_view(ORT_VERSION) == "1.27.0",
+static_assert(std::string_view(ORT_VERSION) == "1.28.0",
               "ORT_Version change detected, please follow below steps to ensure OrtApi is updated properly");
 // 1. Update the hardcoded version string in above static_assert to silence it
 //
@@ -4984,7 +4987,7 @@ static_assert(std::string_view(ORT_VERSION) == "1.27.0",
 
 ORT_API(const OrtApi*, OrtApis::GetApi, uint32_t version) {
   if (version >= 1 && version <= ORT_API_VERSION)
-    return &ort_api_1_to_27;
+    return &ort_api_1_to_28;
 
   fprintf(stderr,
           "The requested API version [%u] is not available, only API versions [1, %u] are supported in this build."