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

onnx_runtime_ep_api/
lib.rs
