onnx_runtime_ep_api/
lib.rs

1//! # `onnx-runtime-ep-api`
2//!
3//! The Execution Provider (EP) interface for the ORT 2.0 runtime
4//! (see `docs/ORT2.md` §4). Every backend — CPU, CUDA, MLX, or a legacy ORT
5//! plugin loaded via `dlopen` — implements the same [`ExecutionProvider`]
6//! trait; only the loading mechanism differs.
7//!
8//! This is a **Phase 1 skeleton**: trait and type *signatures* are real and
9//! reference the [`onnx_runtime_ir`] contract, but method bodies live in the
10//! concrete EP crates (e.g. `onnx-runtime-ep-cpu`). Zero-copy tensor views and
11//! the ORT ABI bridge require `unsafe` FFI and are stubbed here.
12//!
13//! ## Modules
14//! * [`provider`] — [`ExecutionProvider`], [`EpConfig`], device buffers/fences.
15//! * [`kernel`] — [`Kernel`] trait, [`KernelMatch`], [`Cost`].
16//! * [`registry`] — [`OpRegistry`], [`OpKey`], [`KernelFactory`], [`EpRegistry`].
17//! * [`epcontext`] — [`EpContext`] runtime form + `source`-keyed [`EpContextRegistry`] (§55).
18//! * [`tensor`] — [`TensorView`] / [`TensorMut`] zero-copy device views.
19//! * [`abi`] — ORT graph ABI bridge for legacy plugin EPs (Phase 2).
20
21pub mod abi;
22pub mod epcontext;
23pub mod kernel;
24pub mod provider;
25pub mod registry;
26pub mod tensor;
27
28pub use epcontext::{build_ep_context_registry, EpContext, EpContextRegistry};
29pub use error::{EpError, Result};
30pub use kernel::{Cost, Kernel, KernelMatch, ViewOutput};
31pub use provider::{
32    DeviceBuffer, EpConfig, EpId, ExecutionProvider, Fence, OptimizerPass, OrtPluginExport,
33};
34pub use registry::{EpRegistry, KernelFactory, OpKey, OpRegistry};
35pub use tensor::{DevicePtr, DevicePtrMut, TensorMut, TensorView};
36
37// Re-export the device vocabulary from the IR so EP authors have one import.
38pub use onnx_runtime_ir::{DeviceId, DeviceType};
39
40mod error {
41    use std::path::PathBuf;
42
43    /// A convenience `Result` alias for EP operations.
44    pub type Result<T> = std::result::Result<T, EpError>;
45
46    /// Errors produced by execution providers and kernels (subset of the
47    /// runtime top-level `Error`, `docs/ORT2.md` §22).
48    #[derive(Debug, thiserror::Error)]
49    pub enum EpError {
50        #[error("no EP supports op {op_type} on any available device")]
51        NoEpForOp { op_type: String },
52
53        #[error("kernel execution failed: {0}")]
54        KernelFailed(String),
55
56        #[error("EP panicked during execution")]
57        EpPanicked,
58
59        #[error("EP plugin load failed: {path}: {reason}")]
60        EpLoadFailed { path: PathBuf, reason: String },
61
62        #[error("device OOM: requested {requested} bytes, available {available}")]
63        OutOfMemory { requested: usize, available: usize },
64
65        #[error("allocation alignment mismatch")]
66        AlignmentError,
67
68        #[error("invalid tensor view: {reason}")]
69        InvalidTensorView { reason: String },
70
71        #[error("EP not initialized")]
72        NotInitialized,
73
74        #[error("no EP is registered for EPContext source key {source_key:?}")]
75        NoEpForContext { source_key: Option<String> },
76
77        #[error("EP {ep} does not support EPContext save/load")]
78        UnsupportedContext { ep: String },
79
80        #[error(
81            "duplicate EPContext source key {source_key:?}: already registered to {existing:?}, \
82             cannot re-register to {new:?}"
83        )]
84        DuplicateContextSource {
85            source_key: String,
86            existing: crate::provider::EpId,
87            new: crate::provider::EpId,
88        },
89
90        #[error(transparent)]
91        Ir(#[from] onnx_runtime_ir::IrError),
92    }
93}
onnx_runtime_ep_api/lib.rs

onnx_runtime_ep_api/
lib.rs
