virtio_accel_coreml/
lib.rs

1//! Core ML host backend for Apple Neural Engine capable Macs.
2//!
3//! The production path accepts device-neutral TOSA 1.0 FlatBuffers, validates and analyzes them
4//! with `virtio-accel-tosa`, and lowers supported static floating-point graphs inside this
5//! host-native crate. Core ML models are configured with `CPUAndNeuralEngine`: supported
6//! operations may execute on the ANE, while Core ML remains free to place unsupported operations
7//! on the CPU. Program buffers are page-aligned allocations wrapped directly by `MLMultiArray`;
8//! output execution is accepted only when Core ML uses the same allocation as its output backing.
9
10#![cfg_attr(not(target_os = "macos"), forbid(unsafe_code))]
11
12mod artifact;
13mod lower;
14
15pub use artifact::{ArtifactBuildError, CoreMlArtifact, FeatureRole};
16pub use lower::{COREML_TOSA_TARGET, LoweringError, supports_tosa_dtype, supports_tosa_operator};
17
18use virtio_accel_core::{ArtifactFormat, TargetIdentity};
19
20/// Provider artifact format for [`CoreMlArtifact`].
21pub const ARTIFACT_FORMAT: ArtifactFormat = match ArtifactFormat::new(0x434d_4c50) {
22    Some(format) => format,
23    None => panic!("Core ML artifact format must be nonzero"),
24};
25
26/// Core ML path-artifact ABI v1 targeting CPU plus Apple Neural Engine execution.
27pub const TARGET_IDENTITY: TargetIdentity = TargetIdentity([
28    0x434f_5245,
29    0x4d4c_0001,
30    0x414e_4503,
31    0x4d41_434f,
32    0x000e_0000,
33    0,
34    0,
35    0,
36    0,
37    0,
38    0,
39    0,
40]);
41
42/// The Core ML runtime does not publish a finite upper bound for model residency.
43///
44/// Requiring the maximal charge makes the provider promise truthful: a process cannot retain
45/// `u64::MAX` bytes for one model. Device integrations must set their aggregate program-residency
46/// policy accordingly when admitting a Core ML program.
47pub const REQUIRED_RESIDENT_BYTES: u64 = u64::MAX;
48
49/// Failure to initialize a Core ML backend instance.
50#[derive(Clone, Copy, Debug, PartialEq, Eq)]
51pub enum InitError {
52    /// The backend is only executable on macOS 14 or newer.
53    UnsupportedPlatform,
54    /// The configured model root is missing, not a directory, or not representable as UTF-8.
55    InvalidModelRoot,
56    /// Core ML does not report an accessible Apple Neural Engine.
57    NeuralEngineUnavailable,
58}
59
60impl std::fmt::Display for InitError {
61    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
62        write!(formatter, "{self:?}")
63    }
64}
65
66impl std::error::Error for InitError {}
67
68#[cfg(target_os = "macos")]
69mod macos;
70#[cfg(target_os = "macos")]
71pub use macos::{
72    CoreMlAccelerator, CoreMlBuffer, CoreMlContext, CoreMlEvent, CoreMlProgram, CoreMlQueue,
73};
74
75/// Non-macOS placeholder that keeps workspace consumers portable.
76#[cfg(not(target_os = "macos"))]
77#[derive(Clone, Copy, Debug, Default)]
78pub struct CoreMlAccelerator;
79
80#[cfg(not(target_os = "macos"))]
81impl CoreMlAccelerator {
82    /// Report that Core ML is unavailable on this target.
83    pub fn new(_model_root: impl AsRef<std::path::Path>) -> Result<Self, InitError> {
84        Err(InitError::UnsupportedPlatform)
85    }
86
87    /// Report that the native TOSA-to-Core ML execution path is unavailable on this target.
88    pub fn new_tosa() -> Result<Self, InitError> {
89        Err(InitError::UnsupportedPlatform)
90    }
91}
virtio_accel_coreml/lib.rs

virtio_accel_coreml/
lib.rs
