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//! * [`weight`] — capability-negotiated lazy [`WeightHandle`] delivery.
20//! * [`abi`] — ORT graph ABI bridge for legacy plugin EPs (Phase 2).
21
22pub mod abi;
23pub mod epcontext;
24pub mod kernel;
25pub mod provider;
26pub mod registry;
27pub mod tensor;
28pub mod weight;
29
30pub use epcontext::{EpContext, EpContextRegistry, build_ep_context_registry};
31pub use error::{EpError, Result};
32pub use kernel::{
33    ARG_KERNEL_VARIANT, ARG_KERNEL_VARIANT_REASON, CaptureSupport, Cost, Kernel, KernelInput,
34    KernelMatch, KernelVariantSelection, ViewOutput, kernel_variant_tracing_enabled,
35    record_kernel_variant_selection, record_kernel_variant_stage_selection,
36};
37pub use onnx_runtime_optimizer::OptimizationPass as OptimizerPass;
38pub use provider::{DeviceBuffer, EpConfig, EpId, ExecutionProvider, Fence, OrtPluginExport};
39pub use registry::{EpRegistry, KernelFactory, OpKey, OpRegistry};
40pub use tensor::{
41    DevicePtr, DevicePtrMut, ExternalMmapRegion, TensorBacking, TensorMut, TensorView,
42};
43pub use weight::{
44    ExecutionProviderCapabilities, LazyDeviceWeightBinder, LazyWeight, LazyWeightBoundary,
45    NXRT_WEIGHT_PAGING_CAPABILITY, NegotiatedWeight, Phase3aHostOnlyBinder, ResidentWeight,
46    ResidentWeightMaterializer, WeightHandle, WeightHandleError,
47};
48
49// Re-export the device vocabulary from the IR so EP authors have one import.
50pub use onnx_runtime_ir::{DeviceId, DeviceType};
51
52mod error {
53    use std::path::PathBuf;
54
55    /// A convenience `Result` alias for EP operations.
56    pub type Result<T> = std::result::Result<T, EpError>;
57
58    /// Errors produced by execution providers and kernels (subset of the
59    /// runtime top-level `Error`, `docs/ORT2.md` §22).
60    #[derive(Debug, thiserror::Error)]
61    pub enum EpError {
62        #[error("no EP handler for {domain}::{op_type} at opset {opset} on any available device")]
63        NoEpForOp {
64            domain: String,
65            op_type: String,
66            opset: u64,
67        },
68
69        #[error("kernel execution failed: {0}")]
70        KernelFailed(String),
71
72        #[error("EP panicked during execution")]
73        EpPanicked,
74
75        #[error("EP plugin load failed: {path}: {reason}")]
76        EpLoadFailed { path: PathBuf, reason: String },
77
78        #[error("device OOM: requested {requested} bytes, available {available}")]
79        OutOfMemory { requested: usize, available: usize },
80
81        #[error("allocation alignment mismatch")]
82        AlignmentError,
83
84        #[error("invalid tensor view: {reason}")]
85        InvalidTensorView { reason: String },
86
87        #[error("EP not initialized")]
88        NotInitialized,
89
90        #[error("no EP is registered for EPContext source key {source_key:?}")]
91        NoEpForContext { source_key: Option<String> },
92
93        #[error("EP {ep} does not support EPContext save/load")]
94        UnsupportedContext { ep: String },
95
96        #[error(
97            "duplicate EPContext source key {source_key:?}: already registered to {existing:?}, \
98             cannot re-register to {new:?}"
99        )]
100        DuplicateContextSource {
101            source_key: String,
102            existing: crate::provider::EpId,
103            new: crate::provider::EpId,
104        },
105
106        #[error(transparent)]
107        Ir(#[from] onnx_runtime_ir::IrError),
108
109        #[error(transparent)]
110        WeightHandle(#[from] crate::weight::WeightHandleError),
111    }
112}
onnx_runtime_ep_api/lib.rs

onnx_runtime_ep_api/
lib.rs
