openvino_genai_sys/

lib.rs

//! This crate provides low-level, unsafe, Rust bindings to OpenVINO™ GenAI using its [C API]. If
//! you are looking to use OpenVINO™ GenAI from Rust, you likely should look at the ergonomic, safe
//! bindings in [openvino-genai], which depends on this crate. See the repository [README] for more
//! information, including build instructions.
//!
//! [C API]: https://github.com/openvinotoolkit/openvino.genai
//! [openvino-genai-sys]: https://crates.io/crates/openvino-genai-sys
//! [openvino-genai]: https://crates.io/crates/openvino-genai
//! [README]: https://github.com/intel/openvino-rs/tree/main/crates/openvino-genai-sys
//!
//! An example interaction with raw [openvino-genai-sys]:
//! ```no_run
//! openvino_genai_sys::library::load().expect("to have an OpenVINO GenAI library available");
//! ```

#![allow(non_snake_case, non_camel_case_types, non_upper_case_globals)]
#![allow(unused, dead_code)]
#![deny(clippy::all)]
#![warn(clippy::pedantic)]
#![warn(clippy::cargo)]
#![allow(
    clippy::must_use_candidate,
    clippy::suspicious_doc_comments,
    clippy::wildcard_imports,
    clippy::doc_markdown
)]

mod linking;

mod generated;
pub use generated::*;

// Re-export shared types from openvino-sys so that users of both crates share a single definition.
pub use openvino_sys::ov_status_e;
pub use openvino_sys::ov_tensor_t;

/// Contains extra utilities for finding and loading the OpenVINO GenAI shared libraries.
pub mod library {
    use std::path::PathBuf;

    /// When compiled with the `runtime-linking` feature, load the function definitions from a
    /// shared library; with the `dynamic-linking` feature, this function does nothing since the
    /// library has already been linked.
    ///
    /// # Errors
    ///
    /// When compiled with the `runtime-linking` feature, this may fail if the `openvino-finder`
    /// cannot discover the library on the current system.
    pub fn load() -> Result<(), String> {
        super::generated::load()?;
        init_variadic(find().as_deref())
    }

    /// Load the OpenVINO GenAI shared library from an explicit path.
    ///
    /// This is useful when the library is located in a non-standard directory that cannot be
    /// discovered by the `openvino-finder` search paths or environment variables — for example,
    /// when the path is read from a configuration file.
    ///
    /// The `path` should point to the `openvino_genai_c` shared library file
    /// (e.g., `libopenvino_genai_c.so`).
    ///
    /// # Errors
    ///
    /// May fail if the shared library cannot be opened or is invalid.
    pub fn load_from(path: impl Into<std::path::PathBuf>) -> Result<(), String> {
        let path = path.into();
        super::generated::load_from(path.clone())?;
        init_variadic(Some(&path))
    }

    /// Initialize the variadic pipeline creation functions from the loaded library.
    #[allow(unused_variables)]
    fn init_variadic(path: Option<&std::path::Path>) -> Result<(), String> {
        #[cfg(feature = "runtime-linking")]
        if let Some(path) = path {
            super::runtime_variadic::init_variadic_fns(path)?;
        }
        Ok(())
    }

    /// Return the location of the shared library `openvino-genai-sys` will link to. If compiled
    /// with runtime linking, this will attempt to discover the location of an `openvino_genai_c`
    /// shared library on the system. Otherwise (with dynamic linking or compilation from source),
    /// this relies on a static path discovered at build time.
    ///
    /// Knowing the location of the OpenVINO GenAI libraries can be useful for ensuring the correct
    /// runtime environment is configured.
    pub fn find() -> Option<PathBuf> {
        if cfg!(feature = "runtime-linking") {
            openvino_finder::find("openvino_genai_c", openvino_finder::Linking::Dynamic)
        } else {
            Some(PathBuf::from(env!("OPENVINO_GENAI_LIB_PATH")))
        }
    }
}

// The C API exposes variadic pipeline constructors for device property key-value pairs. We provide
// fixed-signature helpers in both linking modes so higher-level crates can pass a slice of property
// pointers instead of manually expanding a C varargs list.

const MAX_PROPERTIES: usize = 8;

fn pad_props(
    props: &[*const ::std::os::raw::c_char],
) -> [*const ::std::os::raw::c_char; MAX_PROPERTIES * 2] {
    let mut out = [std::ptr::null(); MAX_PROPERTIES * 2];
    let n = props.len().min(MAX_PROPERTIES * 2);
    out[..n].copy_from_slice(&props[..n]);
    out
}

#[cfg(feature = "dynamic-linking")]
mod dynamic_variadic {
    use super::*;

    unsafe extern "C" {
        #[link_name = "ov_genai_llm_pipeline_create"]
        fn ov_genai_llm_pipeline_create_raw(
            models_path: *const ::std::os::raw::c_char,
            device: *const ::std::os::raw::c_char,
            property_args_size: usize,
            pipe: *mut *mut ov_genai_llm_pipeline,
            ...
        ) -> ov_status_e;

        #[link_name = "ov_genai_vlm_pipeline_create"]
        fn ov_genai_vlm_pipeline_create_raw(
            models_path: *const ::std::os::raw::c_char,
            device: *const ::std::os::raw::c_char,
            property_args_size: usize,
            pipe: *mut *mut ov_genai_vlm_pipeline,
            ...
        ) -> ov_status_e;

        #[link_name = "ov_genai_whisper_pipeline_create"]
        fn ov_genai_whisper_pipeline_create_raw(
            models_path: *const ::std::os::raw::c_char,
            device: *const ::std::os::raw::c_char,
            property_args_size: usize,
            pipeline: *mut *mut ov_genai_whisper_pipeline,
            ...
        ) -> ov_status_e;
    }

    /// Create an LLM pipeline (dynamic-linking variant).
    ///
    /// `props` contains flattened key-value pairs as C string pointers: `[k1, v1, k2, v2, ...]`.
    /// Pass an empty slice for no properties. Up to `MAX_PROPERTIES` pairs (16 pointers).
    ///
    /// # Safety
    ///
    /// The caller must ensure that `models_path`, `device`, and all pointers in `props` are
    /// valid C strings, and `pipe` is a valid pointer to receive the created pipeline.
    ///
    /// # Panics
    ///
    /// Panics if `props` contains more than `MAX_PROPERTIES * 2` entries.
    pub unsafe fn ov_genai_llm_pipeline_create(
        models_path: *const ::std::os::raw::c_char,
        device: *const ::std::os::raw::c_char,
        property_args_size: usize,
        pipe: *mut *mut ov_genai_llm_pipeline,
        props: &[*const ::std::os::raw::c_char],
    ) -> ov_status_e {
        assert!(
            props.len() <= MAX_PROPERTIES * 2,
            "too many properties (max {})",
            MAX_PROPERTIES
        );
        let p = pad_props(props);
        ov_genai_llm_pipeline_create_raw(
            models_path,
            device,
            property_args_size,
            pipe,
            p[0],
            p[1],
            p[2],
            p[3],
            p[4],
            p[5],
            p[6],
            p[7],
            p[8],
            p[9],
            p[10],
            p[11],
            p[12],
            p[13],
            p[14],
            p[15],
        )
    }

    /// Create a VLM pipeline (dynamic-linking variant).
    ///
    /// See [`ov_genai_llm_pipeline_create`] for details on the `props` parameter.
    ///
    /// # Safety
    ///
    /// Same safety requirements as [`ov_genai_llm_pipeline_create`].
    ///
    /// # Panics
    ///
    /// Panics if `props` contains more than `MAX_PROPERTIES * 2` entries.
    pub unsafe fn ov_genai_vlm_pipeline_create(
        models_path: *const ::std::os::raw::c_char,
        device: *const ::std::os::raw::c_char,
        property_args_size: usize,
        pipe: *mut *mut ov_genai_vlm_pipeline,
        props: &[*const ::std::os::raw::c_char],
    ) -> ov_status_e {
        assert!(
            props.len() <= MAX_PROPERTIES * 2,
            "too many properties (max {})",
            MAX_PROPERTIES
        );
        let p = pad_props(props);
        ov_genai_vlm_pipeline_create_raw(
            models_path,
            device,
            property_args_size,
            pipe,
            p[0],
            p[1],
            p[2],
            p[3],
            p[4],
            p[5],
            p[6],
            p[7],
            p[8],
            p[9],
            p[10],
            p[11],
            p[12],
            p[13],
            p[14],
            p[15],
        )
    }

    /// Create a Whisper pipeline (dynamic-linking variant).
    ///
    /// See [`ov_genai_llm_pipeline_create`] for details on the `props` parameter.
    ///
    /// # Safety
    ///
    /// Same safety requirements as [`ov_genai_llm_pipeline_create`].
    ///
    /// # Panics
    ///
    /// Panics if `props` contains more than `MAX_PROPERTIES * 2` entries.
    pub unsafe fn ov_genai_whisper_pipeline_create(
        models_path: *const ::std::os::raw::c_char,
        device: *const ::std::os::raw::c_char,
        property_args_size: usize,
        pipeline: *mut *mut ov_genai_whisper_pipeline,
        props: &[*const ::std::os::raw::c_char],
    ) -> ov_status_e {
        assert!(
            props.len() <= MAX_PROPERTIES * 2,
            "too many properties (max {})",
            MAX_PROPERTIES
        );
        let p = pad_props(props);
        ov_genai_whisper_pipeline_create_raw(
            models_path,
            device,
            property_args_size,
            pipeline,
            p[0],
            p[1],
            p[2],
            p[3],
            p[4],
            p[5],
            p[6],
            p[7],
            p[8],
            p[9],
            p[10],
            p[11],
            p[12],
            p[13],
            p[14],
            p[15],
        )
    }
}

#[cfg(feature = "dynamic-linking")]
pub use dynamic_variadic::{
    ov_genai_llm_pipeline_create, ov_genai_vlm_pipeline_create, ov_genai_whisper_pipeline_create,
};

// For runtime linking, we load these functions manually and expose the same fixed-signature
// helpers as the dynamic-linking path. These use OnceLock so they can be initialized either lazily
// (from `find()`) or explicitly (from `load_from`). The `library::load()` and
// `library::load_from()` functions call `init_variadic_fns` to populate them.
#[cfg(feature = "runtime-linking")]
mod runtime_variadic {
    use super::*;
    use std::path::Path;
    use std::sync::OnceLock;

    // The C API uses variadic args for property key-value pairs. We define the
    // function pointer with 16 extra `*const c_char` slots (enough for 8 properties).
    // The C function only reads `property_args_size * 2` args from the va_list,
    // so trailing NULLs are harmless.
    type CreateFn = unsafe extern "C" fn(
        *const ::std::os::raw::c_char,    // models_path
        *const ::std::os::raw::c_char,    // device
        usize,                            // property_args_size (number of key-value pairs)
        *mut *mut ::std::os::raw::c_void, // pipe
        // Up to 8 property key-value pairs (16 args):
        *const ::std::os::raw::c_char,
        *const ::std::os::raw::c_char,
        *const ::std::os::raw::c_char,
        *const ::std::os::raw::c_char,
        *const ::std::os::raw::c_char,
        *const ::std::os::raw::c_char,
        *const ::std::os::raw::c_char,
        *const ::std::os::raw::c_char,
        *const ::std::os::raw::c_char,
        *const ::std::os::raw::c_char,
        *const ::std::os::raw::c_char,
        *const ::std::os::raw::c_char,
        *const ::std::os::raw::c_char,
        *const ::std::os::raw::c_char,
        *const ::std::os::raw::c_char,
        *const ::std::os::raw::c_char,
    ) -> ov_status_e;

    static LLM_CREATE: OnceLock<CreateFn> = OnceLock::new();
    static VLM_CREATE: OnceLock<CreateFn> = OnceLock::new();
    static WHISPER_CREATE: OnceLock<CreateFn> = OnceLock::new();

    /// Initialize the variadic pipeline creation functions from the library at `path`.
    ///
    /// Called internally by `library::load()` and `library::load_from()`.
    pub(crate) fn init_variadic_fns(path: &Path) -> Result<(), String> {
        unsafe {
            let lib = libloading::Library::new(path).map_err(|e| {
                format!(
                    "failed to open shared library for variadic fns at {}: {}",
                    path.display(),
                    e,
                )
            })?;

            if let Ok(sym) = lib.get::<CreateFn>(b"ov_genai_llm_pipeline_create") {
                let _ = LLM_CREATE.set(*sym);
            }
            if let Ok(sym) = lib.get::<CreateFn>(b"ov_genai_vlm_pipeline_create") {
                let _ = VLM_CREATE.set(*sym);
            }
            if let Ok(sym) = lib.get::<CreateFn>(b"ov_genai_whisper_pipeline_create") {
                let _ = WHISPER_CREATE.set(*sym);
            }

            // Leak the library to keep function pointers valid.
            std::mem::forget(lib);
        }
        Ok(())
    }

    /// Create an LLM pipeline (runtime-linking variant).
    ///
    /// `props` contains flattened key-value pairs as C string pointers: `[k1, v1, k2, v2, ...]`.
    /// Pass an empty slice for no properties. Up to `MAX_PROPERTIES` pairs (16 pointers).
    ///
    /// # Safety
    ///
    /// The caller must ensure that `models_path`, `device`, and all pointers in `props` are
    /// valid C strings, and `pipe` is a valid pointer to receive the created pipeline.
    ///
    /// # Panics
    ///
    /// Panics if `library::load()` or `library::load_from()` has not been called first,
    /// or if `props` contains more than `MAX_PROPERTIES * 2` entries.
    pub unsafe fn ov_genai_llm_pipeline_create(
        models_path: *const ::std::os::raw::c_char,
        device: *const ::std::os::raw::c_char,
        property_args_size: usize,
        pipe: *mut *mut ov_genai_llm_pipeline,
        props: &[*const ::std::os::raw::c_char],
    ) -> ov_status_e {
        assert!(
            props.len() <= MAX_PROPERTIES * 2,
            "too many properties (max {MAX_PROPERTIES})"
        );
        let p = pad_props(props);
        let f = LLM_CREATE
            .get()
            .expect("`openvino_genai_c` function not loaded: `ov_genai_llm_pipeline_create`; call library::load() or library::load_from() first");
        f(
            models_path,
            device,
            property_args_size,
            pipe.cast(),
            p[0],
            p[1],
            p[2],
            p[3],
            p[4],
            p[5],
            p[6],
            p[7],
            p[8],
            p[9],
            p[10],
            p[11],
            p[12],
            p[13],
            p[14],
            p[15],
        )
    }

    /// Create a VLM pipeline (runtime-linking variant).
    ///
    /// See [`ov_genai_llm_pipeline_create`] for details on the `props` parameter.
    ///
    /// # Safety
    ///
    /// Same safety requirements as [`ov_genai_llm_pipeline_create`].
    ///
    /// # Panics
    ///
    /// Panics if `library::load()` or `library::load_from()` has not been called first,
    /// or if `props` contains more than `MAX_PROPERTIES * 2` entries.
    pub unsafe fn ov_genai_vlm_pipeline_create(
        models_path: *const ::std::os::raw::c_char,
        device: *const ::std::os::raw::c_char,
        property_args_size: usize,
        pipe: *mut *mut ov_genai_vlm_pipeline,
        props: &[*const ::std::os::raw::c_char],
    ) -> ov_status_e {
        assert!(
            props.len() <= MAX_PROPERTIES * 2,
            "too many properties (max {MAX_PROPERTIES})"
        );
        let p = pad_props(props);
        let f = VLM_CREATE
            .get()
            .expect("`openvino_genai_c` function not loaded: `ov_genai_vlm_pipeline_create`; call library::load() or library::load_from() first");
        f(
            models_path,
            device,
            property_args_size,
            pipe.cast(),
            p[0],
            p[1],
            p[2],
            p[3],
            p[4],
            p[5],
            p[6],
            p[7],
            p[8],
            p[9],
            p[10],
            p[11],
            p[12],
            p[13],
            p[14],
            p[15],
        )
    }

    /// Create a Whisper pipeline (runtime-linking variant).
    ///
    /// See [`ov_genai_llm_pipeline_create`] for details on the `props` parameter.
    ///
    /// # Safety
    ///
    /// Same safety requirements as [`ov_genai_llm_pipeline_create`].
    ///
    /// # Panics
    ///
    /// Panics if `library::load()` or `library::load_from()` has not been called first,
    /// or if `props` contains more than `MAX_PROPERTIES * 2` entries.
    pub unsafe fn ov_genai_whisper_pipeline_create(
        models_path: *const ::std::os::raw::c_char,
        device: *const ::std::os::raw::c_char,
        property_args_size: usize,
        pipeline: *mut *mut ov_genai_whisper_pipeline,
        props: &[*const ::std::os::raw::c_char],
    ) -> ov_status_e {
        assert!(
            props.len() <= MAX_PROPERTIES * 2,
            "too many properties (max {MAX_PROPERTIES})"
        );
        let p = pad_props(props);
        let f = WHISPER_CREATE
            .get()
            .expect("`openvino_genai_c` function not loaded: `ov_genai_whisper_pipeline_create`; call library::load() or library::load_from() first");
        f(
            models_path,
            device,
            property_args_size,
            pipeline.cast(),
            p[0],
            p[1],
            p[2],
            p[3],
            p[4],
            p[5],
            p[6],
            p[7],
            p[8],
            p[9],
            p[10],
            p[11],
            p[12],
            p[13],
            p[14],
            p[15],
        )
    }
}

#[cfg(feature = "runtime-linking")]
pub use runtime_variadic::{
    ov_genai_llm_pipeline_create, ov_genai_vlm_pipeline_create, ov_genai_whisper_pipeline_create,
};