virglrenderer 0.1.4

// Copyright 2024 Red Hat Inc
// Copyright 2019 The ChromiumOS Authors
// Copyright The virglrenderer-rs Contributors.
//
// SPDX-License-Identifier: MIT

//! # Rust bindings for virglrenderer
//!
//! `virglrenderer` is a crate that provides safe Rust bindings for `libvirglrenderer`,
//! a library for hardware-accelerated 3D graphics rendering in virtualized environments.
//! It enables a host-side application to act as a graphics server, processing commands
//! from a guest virtual machine.
//!
//! Programs that interact with virglrenderer usually react to events from the guest by
//! processing command streams and signaling the completion of operations with fences.
//!
//! ## Getting started
//!
//! Most programs that interact with virglrenderer will need a few basic objects:
//! - A **`VirglRenderer`** that manages the global state of the rendering process.
//!   This object is responsible for initialization, cleanup, and handling global events.
//! - A **`VirglResource`** that represents a graphics resource, such as a texture or buffer,
//!   which can be created and managed by the renderer.
//!
//! This is how they can be created:
//!
//! ```no_run
//! use virglrenderer::{VirglRenderer, VirglError, FenceHandler, VirglRendererFlags};
//! use std::os::fd::OwnedFd;
//!
//! // A simple fence handler that prints the fence ID.
//! struct MyFenceHandler;
//!
//! impl FenceHandler for MyFenceHandler {
//!     fn call(&self, fence_id: u64, ctx_id: u32, _ring_idx: u8) {
//!         println!("Fence complete: {} on context {}", fence_id, ctx_id);
//!     }
//! }
//!
//! fn main() -> Result<(), VirglError> {
//!     let flags = VirglRendererFlags::new()
//!         .use_egl(true)
//!         .use_glx(true)
//!         .use_virgl(true)
//!         .use_venus(true)
//!         .use_surfaceless(true)
//!         .use_external_blob(true)
//!         .use_async_fence_cb(true)
//!         .use_thread_sync(true);
//!
//!     // Initialize the renderer with a fence handler.
//!     let renderer = VirglRenderer::init(
//!         flags, // Flags
//!         Box::new(MyFenceHandler),
//!         None, // Optional render server file descriptor
//!         None, // Optional DRM device file descriptor
//!     )?;
//!
//!     // Create a rendering context.
//!     renderer.create_context(
//!         1, // Unique context ID
//!         0, // Context initialization flags
//!         Some("my-app-context") // Optional context name
//!     )?;
//!
//!     Ok(())
//! }
//! ```
//!
//!  ## Common Operations
//!
//! Now you can start creating resources, attaching them to the context, and processing command streams.
//! - **Creating Resources**: Use [`VirglRenderer::create_3d`] or [`VirglRenderer::create_blob`].
//! - **Attaching Backing Memory**: Map guest memory to virgl resources.
//! - **Submitting Commands**: Send rendering commands.
//!
//! ```no_run
//! use virglrenderer::{VirglRenderer, VirglError, ResourceCreate3D, VirglRendererFlags};
//! use std::os::fd::OwnedFd;
//!
//! // A simple fence handler (same as above).
//! # struct MyFenceHandler;
//! # impl virglrenderer::FenceHandler for MyFenceHandler {
//! #   fn call(&self, fence_id: u64, ctx_id: u32, _ring_idx: u8) {
//! #     println!("Fence complete: {} on context {}", fence_id, ctx_id);
//! #   }
//! # }
//!
//! fn main() -> Result<(), VirglError> {
//!     let flags = VirglRendererFlags::new()
//!         .use_egl(true)
//!         .use_glx(true)
//!         .use_virgl(true)
//!         .use_venus(true)
//!         .use_surfaceless(true)
//!         .use_external_blob(true)
//!         .use_async_fence_cb(true)
//!         .use_thread_sync(true);
//!
//!     // Initialize the renderer with a fence handler.
//!     let renderer = VirglRenderer::init(
//!         flags, // Flags
//!         Box::new(MyFenceHandler),
//!         None, // Optional render server file descriptor
//!         None, // Optional DRM device file descriptor
//!     )?;
//!
//!     let ctx_id = 1;
//!     renderer.create_context(ctx_id, 0, Some("my-app-context"))?;
//!
//!     // Create a 3D resource, like a texture.
//!     let resource_create_3d = ResourceCreate3D {
//!         target: 0x0C,   // Example: GL_TEXTURE_2D
//!         format: 0x8058, // Example: GL_RGBA8
//!         bind: 0x01,     // Example: GL_TEXTURE_BINDING
//!         width: 256,
//!         height: 256,
//!         depth: 1,
//!         array_size: 1,
//!         last_level: 0,
//!         nr_samples: 0,
//!         flags: 0,
//!     };
//!
//!     // Create the resource with a unique ID and attach it to the context.
//!     let mut resource = renderer.create_3d(100, resource_create_3d)?;
//!
//!     renderer.ctx_attach_resource(ctx_id, resource.resource_id);
//!
//!     // Here, you would process incoming commands and submit them to the context
//!     // using `renderer.submit_cmd(ctx_id, ...)` and transfer data using `renderer.transfer_write(...)`.
//!
//!     // Detach the resource when you are done with it.
//!     renderer.ctx_detach_resource(ctx_id, resource.resource_id);
//!
//!     Ok(())
//! }
//! ```
//!
//! Note that resource IDs and context IDs are globally unique and are used to refer to objects in
//! commands from the guest.
//!
//! ---
//!
//! ## Event Handling and Integration
//!
//! The `virglrenderer` library requires periodic event processing to handle incoming
//! commands and dispatch fence callbacks.
//!
//! You can integrate `virglrenderer` into your application's event loop using one of two methods:
//! - **Direct Polling:** Call `event_poll()` periodically in a loop.
//! - **File Descriptor Integration (recommended):** Use `poll_descriptor()` to obtain
//!   a pollable fd, then register it with your application’s event loop
//!   (e.g. `epoll`, `mio`, or `tokio::AsyncFd`).
//!
//! Here's an example using the `event_poll()` method:
//!
//! ```no_run
//! use virglrenderer::{VirglRenderer, VirglRendererFlags, FenceHandler, VirglError};
//!
//! # struct MyFenceHandler;
//! # impl virglrenderer::FenceHandler for MyFenceHandler {
//! #   fn call(&self, fence_id: u64, ctx_id: u32, _ring_idx: u8) {
//! #     println!("Fence complete: {} on context {}", fence_id, ctx_id);
//! #   }
//! # }
//! fn main() -> Result<(), VirglError> {
//!     let flags = VirglRendererFlags::new()
//!         .use_egl(true)
//!         .use_glx(true)
//!         .use_virgl(true)
//!         .use_venus(true)
//!         .use_surfaceless(true)
//!         .use_external_blob(true)
//!         .use_async_fence_cb(true)
//!         .use_thread_sync(true);
//!
//!     // Initialize the renderer with a fence handler.
//!     let renderer = VirglRenderer::init(
//!         flags, // Flags
//!         Box::new(MyFenceHandler),
//!         None, // Optional render server file descriptor
//!         None, // Optional DRM device file descriptor
//!     )?;
//!     loop {
//!         renderer.event_poll();
//!         std::thread::sleep(std::time::Duration::from_millis(10));
//!     }
//! }
//! ```
//!
//! This will continuously process events from the renderer, ensuring commands and fence callbacks
//! are handled correctly.
//! ## Safety Notes
//!
//! - virglrenderer is a C library: these bindings wrap unsafe FFI calls in safe Rust APIs.
//! - Resource IDs and Context IDs must be unique and guest-driven.
//! - Fence callbacks run asynchronously and should avoid blocking.
//!
//! ---
//! For more details, see the [virglrenderer project](https://gitlab.freedesktop.org/virgl/virglrenderer).

#[derive(Debug, thiserror::Error)]
pub enum VirglError {
    #[error("initialization failed")]
    InitializationFailed,
    #[error("resource creation failed")]
    ResourceCreationError,
    #[error("context creation failed")]
    ContextCreationError,
    #[error("I/O error: {0}")]
    IoError(#[from] std::io::Error),
    #[error("transfer failed")]
    TransferError,
    #[error("resource info query failed")]
    ResourceInfoError,
    #[error("mapping failed")]
    MappingFailed,
    #[error("unsupported")]
    Unsupported,
    #[error("invalid command size: {0}")]
    InvalidCommandSize(usize),
    #[error("failed to create fence")]
    FenceError,
}

pub mod flags;
// Re-export the raw bindings.
pub use flags::VirglRendererFlags;
use libc::dup;
use log::{log, Level};
use std::ffi::CStr;
use std::io::{IoSlice, IoSliceMut};
use std::mem::size_of;
use std::mem::ManuallyDrop;
use std::os::fd::{IntoRawFd, RawFd};
use std::os::raw::{c_char, c_int, c_void};
use std::os::unix::io::{FromRawFd, OwnedFd};
use std::panic::catch_unwind;
use std::process::abort;
use std::ptr::null_mut;
use std::sync::{Arc, Once};
use virglrenderer_sys as ffi;

// --- Constants to mirror Mesa handle types ---
pub const VIRGL_HANDLE_TYPE_MEM_OPAQUE_FD: u32 = 0x0001;
pub const VIRGL_HANDLE_TYPE_MEM_DMABUF: u32 = 0x0002;
pub const VIRGL_HANDLE_TYPE_MEM_SHM: u32 = 0x0004;

/// Mask used to obtain cache behavior flags from VirglResource::map_info
pub use ffi::VIRGL_RENDERER_MAP_CACHE_MASK as VIRGL_MAP_CACHE_MASK;

pub trait FenceHandler {
    fn call(&self, fence_id: u64, ctx_id: u32, ring_idx: u8);
}

pub struct VirglHandle {
    pub os_handle: OwnedFd,
    pub handle_type: u32,
}

#[repr(C)]
#[derive(Debug, Copy, Clone)]
pub struct VirglBox {
    pub x: u32,
    pub y: u32,
    pub z: u32,
    pub w: u32,
    pub h: u32,
    pub d: u32,
}

#[repr(C)]
#[derive(Copy, Clone)]
pub struct Iovec {
    pub base: *mut c_void,
    pub len: usize,
}

// Safe because we only pass the pointer to virgl on its own thread,
// and we never mutate the Vec after attaching.
unsafe impl Send for Iovec {}

#[repr(C)]
#[derive(Clone)]
pub struct Resource3DInfo {
    pub width: u32,
    pub height: u32,
    pub drm_fourcc: u32,
    pub strides: [u32; 4],
    pub offsets: [u32; 4],
    pub modifier: u64,
    pub guest_cpu_mappable: bool,
}

pub struct ResourceCreate3D {
    pub target: u32,
    pub format: u32,
    pub bind: u32,
    pub width: u32,
    pub height: u32,
    pub depth: u32,
    pub array_size: u32,
    pub last_level: u32,
    pub nr_samples: u32,
    pub flags: u32,
}

pub struct ResourceCreateBlob {
    pub blob_mem: u32,
    pub blob_flags: u32,
    pub blob_id: u64,
    pub size: u64,
}

#[repr(C)]
#[derive(Clone)]
pub struct VirglResource {
    pub resource_id: u32,
    pub width: u32,
    pub height: u32,
    pub handle: Option<Arc<VirglHandle>>,
    pub info_3d: Option<Resource3DInfo>,
    pub map_info: Option<u32>,
}

pub struct VirglRenderer {
    _private: (),
}

#[repr(C)]
#[derive(Copy, Clone, Debug)]
pub struct Transfer3D {
    pub x: u32,
    pub y: u32,
    pub z: u32,
    pub w: u32,
    pub h: u32,
    pub d: u32,
    pub level: u32,
    pub stride: u32,
    pub layer_stride: u32,
    pub offset: u64,
}

impl Transfer3D {
    /// Constructs a 2 dimensional XY box in 3 dimensional space with unit depth and zero
    /// displacement on the Z axis.
    pub fn new_2d(x: u32, y: u32, w: u32, h: u32, offset: u64) -> Transfer3D {
        Transfer3D {
            x,
            y,
            z: 0,
            w,
            h,
            d: 1,
            level: 0,
            stride: 0,
            layer_stride: 0,
            offset,
        }
    }

    /// Returns true if this box represents a volume of zero.
    pub fn is_empty(&self) -> bool {
        self.w == 0 || self.h == 0 || self.d == 0
    }
}

// --- FFI Callbacks and Statics ---
struct VirglCookie {
    render_server_fd: Option<OwnedFd>,
    drm_fd: Option<OwnedFd>,
    fence_handler: Option<Box<dyn FenceHandler + Send + Sync>>,
}

static INIT_ONCE: Once = Once::new();
static mut VIRGL_COOKIE: ManuallyDrop<VirglCookie> = ManuallyDrop::new(VirglCookie {
    render_server_fd: None,
    drm_fd: None,
    fence_handler: None,
});

extern "C" fn log_callback(
    log_level: ffi::virgl_log_level_flags,
    message: *const ::std::os::raw::c_char,
    _user_data: *mut ::std::os::raw::c_void,
) {
    let level = match log_level {
        ffi::virgl_log_level_flags_VIRGL_LOG_LEVEL_DEBUG => Level::Debug,
        ffi::virgl_log_level_flags_VIRGL_LOG_LEVEL_INFO => Level::Info,
        ffi::virgl_log_level_flags_VIRGL_LOG_LEVEL_WARNING => Level::Warn,
        ffi::virgl_log_level_flags_VIRGL_LOG_LEVEL_ERROR => Level::Error,
        ffi::virgl_log_level_flags_VIRGL_LOG_LEVEL_SILENT => Level::Error, // Or another appropriate level
        _ => Level::Trace,
    };
    let message_str = unsafe { CStr::from_ptr(message) };
    log!(level, "{}", message_str.to_string_lossy());
}

extern "C" fn write_context_fence(cookie: *mut c_void, ctx_id: u32, ring_idx: u32, fence_id: u64) {
    catch_unwind(|| {
        assert!(!cookie.is_null());
        let cookie = unsafe { &*(cookie as *const VirglCookie) };
        if let Some(handler) = &cookie.fence_handler {
            handler.call(fence_id, ctx_id, ring_idx as u8);
        }
    })
    .unwrap_or_else(|_| abort())
}

unsafe extern "C" fn write_fence(cookie: *mut c_void, fence: u32) {
    catch_unwind(|| {
        assert!(!cookie.is_null());
        let cookie = &*(cookie as *const VirglCookie);
        if let Some(handler) = &cookie.fence_handler {
            handler.call(fence as u64, 0, 0);
        }
    })
    .unwrap_or_else(|_| abort())
}

unsafe extern "C" fn get_server_fd(cookie: *mut c_void, version: u32) -> c_int {
    catch_unwind(|| {
        assert!(!cookie.is_null());
        let cookie = &mut *(cookie as *mut VirglCookie);
        if version != 0 {
            return -1;
        }
        cookie
            .render_server_fd
            .take()
            .map(|o| o.into_raw_fd())
            .unwrap_or(-1)
    })
    .unwrap_or_else(|_| abort())
}

unsafe extern "C" fn get_drm_fd(cookie: *mut c_void) -> c_int {
    catch_unwind(|| {
        assert!(!cookie.is_null());
        let cookie = &*(cookie as *const VirglCookie);
        cookie
            .drm_fd
            .as_ref()
            .and_then(|fd| fd.try_clone().ok())
            .map(|o| o.into_raw_fd())
            .unwrap_or(-1)
    })
    .unwrap_or_else(|_| abort())
}

const VIRGL_RENDERER_CALLBACKS: &ffi::virgl_renderer_callbacks = &ffi::virgl_renderer_callbacks {
    version: 3,
    write_fence: Some(write_fence),
    create_gl_context: None,
    destroy_gl_context: None,
    make_current: None,
    get_drm_fd: Some(get_drm_fd),
    write_context_fence: Some(write_context_fence),
    get_server_fd: Some(get_server_fd),
    get_egl_display: None,
};

// --- `VirglRenderer` Implementation ---
impl VirglRenderer {
    pub fn init(
        flags: VirglRendererFlags,
        fence_handler: Box<dyn FenceHandler + Send + Sync>,
        render_server_fd: Option<OwnedFd>,
        drm_fd: Option<OwnedFd>,
    ) -> Result<Self, VirglError> {
        // Validate that at least one OpenGL backend is enabled.
        // Without EGL or GLX, virglrenderer will try to use the GL context callbacks
        // (create_gl_context, destroy_gl_context, make_current), but those are not
        // currently supported in this binding (they're set to None), causing a segfault.
        // Note: SURFACELESS is a modifier flag, not a backend that creates GL contexts.
        let has_gl_backend = (flags.bits() & flags::VIRGL_RENDERER_USE_EGL) != 0
            || (flags.bits() & flags::VIRGL_RENDERER_USE_GLX) != 0;

        if !has_gl_backend {
            return Err(VirglError::InitializationFailed);
        }

        let mut result = Err(VirglError::InitializationFailed);
        INIT_ONCE.call_once(|| {
            unsafe {
                // SAFETY: We are inside `call_once`, ensuring this code runs only once.
                // This makes the access to the `VIRGL_COOKIE` static safe, as no other
                // thread can be modifying it. The `ManuallyDrop` prevents a double-free
                // on program exit. The `transmute` is safe because `VIRGL_RENDERER_CALLBACKS`
                // is a static `&'static` reference and the C API expects a pointer to a
                // statically allocated struct. The `ffi::virgl_renderer_init` is called
                // once, and the return value is checked.
                VIRGL_COOKIE = ManuallyDrop::new(VirglCookie {
                    render_server_fd,
                    drm_fd,
                    fence_handler: Some(fence_handler),
                });
                ffi::virgl_set_log_callback(Some(log_callback), null_mut(), None);

                let ret = ffi::virgl_renderer_init(
                    &mut *VIRGL_COOKIE as *mut _ as *mut c_void,
                    flags.into(),
                    VIRGL_RENDERER_CALLBACKS as *const _ as *mut _,
                );
                if ret == 0 {
                    result = Ok(VirglRenderer { _private: () });
                }
            }
        });
        result
    }

    pub fn unref_resource(&self, resource_id: u32) {
        unsafe {
            // SAFETY: `virgl_renderer_resource_unref` takes a resource handle.
            // The safety of this call relies on the provided `resource_id` being valid,
            // which is a precondition of our public API contract.
            ffi::virgl_renderer_resource_unref(resource_id)
        };
    }

    pub fn create_3d(
        &self,
        resource_id: u32,
        resource_create_3d: ResourceCreate3D,
    ) -> Result<VirglResource, VirglError> {
        let mut args = ffi::virgl_renderer_resource_create_args {
            handle: resource_id,
            target: resource_create_3d.target,
            format: resource_create_3d.format,
            bind: resource_create_3d.bind,
            width: resource_create_3d.width,
            height: resource_create_3d.height,
            depth: resource_create_3d.depth,
            array_size: resource_create_3d.array_size,
            last_level: resource_create_3d.last_level,
            nr_samples: resource_create_3d.nr_samples,
            flags: resource_create_3d.flags,
        };

        let ret = unsafe {
            // SAFETY: `virgl_renderer_resource_create` takes a mutable pointer to the `args` struct
            // and a pointer to an iovec array. The `args` struct is a valid stack variable.
            // We pass a null pointer for the iovec array, which is a valid state.
            // The return value is checked for success.
            ffi::virgl_renderer_resource_create(&mut args, null_mut(), 0)
        };
        if ret != 0 {
            return Err(VirglError::ResourceCreationError);
        }

        let mut resource_handle = self.export_blob(resource_id).ok();
        let mut resource_info_3d = self.query(resource_id).ok();

        if resource_handle.is_none() && resource_info_3d.is_none() {
            if let Ok(info_ext) = self.get_resource_info_ext(resource_id) {
                if let Ok(fd) = self.get_fd_for_texture(info_ext.base.tex_id) {
                    let fourcc: u32 = info_ext.base.drm_fourcc as u32;

                    let owned_fd = unsafe { OwnedFd::from_raw_fd(fd) };
                    resource_handle = Some(Arc::new(VirglHandle {
                        os_handle: owned_fd,
                        handle_type: VIRGL_HANDLE_TYPE_MEM_DMABUF,
                    }));
                    resource_info_3d = Some(Resource3DInfo {
                        width: info_ext.base.width,
                        height: info_ext.base.height,
                        drm_fourcc: fourcc,
                        strides: [info_ext.base.stride, 0, 0, 0],
                        offsets: [0, 0, 0, 0],
                        modifier: info_ext.modifiers,
                        guest_cpu_mappable: false,
                    });
                }
            }
        }
        Ok(VirglResource {
            resource_id,
            width: resource_create_3d.width,
            height: resource_create_3d.height,
            handle: resource_handle,
            info_3d: resource_info_3d,
            map_info: None,
        })
    }

    pub fn create_blob(
        &self,
        ctx_id: u32,
        width: u32,
        height: u32,
        resource_id: u32,
        resource_create_blob: ResourceCreateBlob,
        iovecs: Option<&[Iovec]>,
    ) -> Result<VirglResource, VirglError> {
        let (iovec_ptr, num_iovecs) = match iovecs {
            Some(iovs) => (iovs.as_ptr() as *const ffi::iovec, iovs.len()),
            None => (null_mut() as *const ffi::iovec, 0),
        };

        let resource_create_args = ffi::virgl_renderer_resource_create_blob_args {
            res_handle: resource_id,
            ctx_id,
            blob_mem: resource_create_blob.blob_mem,
            blob_flags: resource_create_blob.blob_flags,
            blob_id: resource_create_blob.blob_id,
            size: resource_create_blob.size,
            iovecs: iovec_ptr,
            num_iovs: num_iovecs as u32,
        };

        let ret = unsafe {
            // SAFETY: The `resource_create_args` is a valid stack variable.
            // The `iovec_ptr` is either a valid pointer derived from a Rust slice or
            // `null_mut`, both of which are valid for the C function. The `num_iovs`
            // is correct for the `iovec_ptr`. The return value is checked.
            ffi::virgl_renderer_resource_create_blob(&resource_create_args)
        };
        if ret != 0 {
            return Err(VirglError::ResourceCreationError);
        }

        Ok(VirglResource {
            resource_id,
            width,
            height,
            handle: self.export_blob(resource_id).ok(),
            info_3d: self.query(resource_id).ok(),
            map_info: self.map_info(resource_id).ok(),
        })
    }

    /// Attaches a backing memory buffer (represented by iovecs) to a resource.
    pub fn attach_backing(
        &self,
        resource_id: u32,
        iovecs: &mut Vec<Iovec>,
    ) -> Result<(), VirglError> {
        let ret = unsafe {
            // SAFETY: `virgl_renderer_resource_attach_iov` takes a resource handle, a pointer
            // to an iovec array, and the number of iovecs. The `iovecs.as_ptr()` is a valid,
            // non-null pointer to a slice of iovecs, and `iovecs.len()` is the correct length.
            // We check the return value for success.
            ffi::virgl_renderer_resource_attach_iov(
                resource_id as i32,
                iovecs.as_mut_ptr() as *mut ffi::iovec,
                iovecs.len() as i32,
            )
        };
        if ret == 0 {
            Ok(())
        } else {
            Err(VirglError::IoError(std::io::Error::last_os_error()))
        }
    }

    /// Detaches backing I/O vectors from a resource.
    pub fn detach_backing(&self, resource_id: u32) {
        unsafe {
            // SAFETY: `virgl_renderer_resource_detach_iov` takes a resource handle.
            // The `null_mut()` arguments are valid for a detach operation where the old iovecs
            // are not needed. The safety relies on the provided `resource_id` being valid.
            ffi::virgl_renderer_resource_detach_iov(resource_id as i32, null_mut(), null_mut());
        }
    }

    /// Polls for pending virglrenderer events.
    pub fn event_poll(&self) {
        unsafe {
            // SAFETY: `virgl_renderer_poll` takes no arguments and is designed to be called
            // safely to process pending events.
            ffi::virgl_renderer_poll()
        };
    }

    /// Returns an owned file descriptor that can be used for polling.
    pub fn poll_descriptor(&self) -> Option<OwnedFd> {
        let fd = unsafe {
            // SAFETY: `virgl_renderer_get_poll_fd` takes no arguments and returns a raw file descriptor.
            // We check the return value for an error state.
            ffi::virgl_renderer_get_poll_fd()
        };
        if fd >= 0 {
            let dup_fd = unsafe {
                // SAFETY: `dup` is a C library function. It is safe to call with a valid file descriptor.
                // We check the return value to ensure the operation was successful.
                dup(fd)
            };
            if dup_fd >= 0 {
                // SAFETY: `dup` returns a new, valid file descriptor that we now own.
                // `from_raw_fd` correctly wraps this into a safe `OwnedFd` type.
                return Some(unsafe { OwnedFd::from_raw_fd(dup_fd) });
            }
        }
        None
    }

    /// Returns the maximum version and size of a given capset ID.
    pub fn get_capset_info(&self, capset_id: u32) -> (u32, u32) {
        let mut version = 0;
        let mut size = 0;
        unsafe {
            // SAFETY: `virgl_renderer_get_cap_set` takes a capset ID and mutable pointers
            // to stack variables. The function writes to these pointers, and we read the
            // results. This is safe as the pointers are valid and the types match.
            ffi::virgl_renderer_get_cap_set(capset_id, &mut version, &mut size);
        }
        (version, size)
    }

    /// Returns the capabilities of a given capset and version.
    pub fn get_capset(&self, capset_id: u32, version: u32) -> Vec<u8> {
        let (_, max_size) = self.get_capset_info(capset_id);
        let mut buf = vec![0u8; max_size as usize];
        unsafe {
            // SAFETY: `virgl_renderer_fill_caps` takes a capset ID, version, and a mutable
            // pointer to a buffer. We ensure the buffer pointer is valid and non-null,
            // and the buffer is appropriately sized for the operation.
            ffi::virgl_renderer_fill_caps(capset_id, version, buf.as_mut_ptr() as *mut c_void);
        }
        buf
    }

    /// Forces the use of context 0.
    pub fn force_ctx_0(&self) {
        unsafe {
            // SAFETY: `virgl_renderer_force_ctx_0` takes no arguments and is a safe global
            // function call to change the current context.
            ffi::virgl_renderer_force_ctx_0();
        }
    }

    /// Create a fence not tied to a specific context.
    pub fn create_fence(&self, fence_id: u32, ctx_id: u32) -> Result<(), VirglError> {
        let ret = unsafe {
            //SAFETY: This function calls into the C virglrenderer API (`virgl_renderer_create_fence`).
            // The caller must ensure the renderer has been properly initialized,
            // and the fence/context IDs are valid according to the virgl protocol.
            ffi::virgl_renderer_create_fence(fence_id as i32, ctx_id)
        };
        if ret != 0 {
            Err(VirglError::FenceError)
        } else {
            Ok(())
        }
    }

    /// Export an existing fence to a file descriptor.
    pub fn export_fence(&self, fence_id: u64) -> Result<RawFd, VirglError> {
        #[cfg(feature = "virgl_renderer_unstable")]
        {
            let mut fd: i32 = 0;
            let ret = unsafe {
                // SAFETY: Calls into the C virglrenderer API (`virgl_renderer_export_fence`).
                // The returned file descriptor is owned by the caller and must be closed
                // when no longer needed to avoid resource leaks.
                ffi::virgl_renderer_export_fence(fence_id, &mut fd)
            };
            if ret != 0 {
                Err(VirglError::FenceError)
            } else {
                Ok(fd)
            }
        }
        #[cfg(not(feature = "virgl_renderer_unstable"))]
        Err(VirglError::Unsupported)
    }

    /// Maps a resource into memory, returning a raw pointer and size.
    pub fn map(&self, resource_id: u32) -> Result<(*mut c_void, u64), VirglError> {
        let mut map: *mut c_void = null_mut();
        let mut size: u64 = 0;
        unsafe {
            // SAFETY: `virgl_renderer_resource_map` takes a resource handle and mutable
            // pointers to stack variables. The function writes to these pointers, and we
            // check the return value. This is safe as long as the resource handle is valid.
            let ret = ffi::virgl_renderer_resource_map(resource_id, &mut map, &mut size);
            if ret != 0 {
                return Err(VirglError::MappingFailed);
            }
        }

        if map.is_null() {
            return Err(VirglError::MappingFailed);
        }

        Ok((map, size))
    }

    /// Unmaps a previously mapped resource.
    pub fn unmap(&self, resource_id: u32) -> Result<(), VirglError> {
        unsafe {
            // SAFETY: `virgl_renderer_resource_unmap` takes a resource handle.
            // This is safe to call as long as the resource handle is valid and the
            // resource was previously mapped. We check the return value.
            let ret = ffi::virgl_renderer_resource_unmap(resource_id);
            if ret != 0 {
                return Err(VirglError::MappingFailed);
            }
        }
        Ok(())
    }

    /// Reads data from a resource into a series of I/O vectors.
    pub fn transfer_read(
        &self,
        resource_id: u32,
        ctx_id: u32,
        transfer: Transfer3D,
        buf: Option<IoSliceMut>,
    ) -> Result<(), VirglError> {
        if transfer.is_empty() {
            return Ok(());
        }

        let mut transfer_box = VirglBox {
            x: transfer.x,
            y: transfer.y,
            z: transfer.z,
            w: transfer.w,
            h: transfer.h,
            d: transfer.d,
        };

        let mut iov = Iovec {
            base: null_mut(),
            len: 0,
        };
        let (iovecs, num_iovecs) = match buf {
            Some(mut buf) => {
                iov.base = buf.as_mut_ptr() as *mut c_void;
                iov.len = buf.len();
                (&mut iov as *mut Iovec as *mut ffi::iovec, 1)
            }
            None => (null_mut(), 0),
        };

        let ret = unsafe {
            // SAFETY: `virgl_renderer_transfer_read_iov` takes a valid `transfer_box` struct,
            // and `iovecs` and `num_iovecs` are constructed from a valid Rust slice, or are null
            // as is safe. The resource and context IDs are assumed to be valid from the public
            // API contract. The return value is checked.
            ffi::virgl_renderer_transfer_read_iov(
                resource_id,
                ctx_id,
                transfer.level,
                transfer.stride,
                transfer.layer_stride,
                &mut transfer_box as *mut VirglBox as *mut ffi::virgl_box,
                transfer.offset,
                iovecs,
                num_iovecs,
            )
        };
        if ret == 0 {
            Ok(())
        } else {
            Err(VirglError::TransferError)
        }
    }

    /// Writes data to a resource from a series of I/O vectors.
    pub fn transfer_write(
        &self,
        resource_id: u32,
        ctx_id: u32,
        transfer: Transfer3D,
        buf: Option<&IoSlice>,
    ) -> Result<(), VirglError> {
        if transfer.is_empty() {
            return Ok(());
        }

        if buf.is_some() {
            return Err(VirglError::Unsupported);
        }

        let mut transfer_box = VirglBox {
            x: transfer.x,
            y: transfer.y,
            z: transfer.z,
            w: transfer.w,
            h: transfer.h,
            d: transfer.d,
        };

        let ret = unsafe {
            // SAFETY: `virgl_renderer_transfer_write_iov` takes a valid `transfer_box` struct.
            // The `iovecs` pointer is cast from a valid Rust stack variable, and the length
            // is correct. The resource and context IDs are assumed to be valid. The return value is checked.
            ffi::virgl_renderer_transfer_write_iov(
                resource_id,
                ctx_id,
                transfer.level as i32,
                transfer.stride,
                transfer.layer_stride,
                &mut transfer_box as *mut VirglBox as *mut ffi::virgl_box,
                transfer.offset,
                null_mut(),
                0,
            )
        };
        if ret == 0 {
            Ok(())
        } else {
            Err(VirglError::TransferError)
        }
    }

    // --- Private Helper Functions ---
    fn export_blob(&self, resource_id: u32) -> Result<Arc<VirglHandle>, VirglError> {
        let mut fd_type = 0;
        let mut fd = 0;
        let ret = unsafe {
            // SAFETY: `virgl_renderer_resource_export_blob` takes a resource ID and mutable pointers
            // to stack variables. We check the return value and the validity of the returned FD.
            ffi::virgl_renderer_resource_export_blob(resource_id, &mut fd_type, &mut fd)
        };
        if ret != 0 || fd < 0 {
            return Err(VirglError::IoError(std::io::Error::last_os_error()));
        }
        let handle_type = match fd_type {
            ffi::VIRGL_RENDERER_BLOB_FD_TYPE_DMABUF => VIRGL_HANDLE_TYPE_MEM_DMABUF,
            ffi::VIRGL_RENDERER_BLOB_FD_TYPE_SHM => VIRGL_HANDLE_TYPE_MEM_SHM,
            ffi::VIRGL_RENDERER_BLOB_FD_TYPE_OPAQUE => VIRGL_HANDLE_TYPE_MEM_OPAQUE_FD,
            _ => return Err(VirglError::Unsupported),
        };
        let owned_fd = unsafe { OwnedFd::from_raw_fd(fd) };
        Ok(Arc::new(VirglHandle {
            os_handle: owned_fd,
            handle_type,
        }))
    }

    fn query(&self, resource_id: u32) -> Result<Resource3DInfo, VirglError> {
        let mut query: ffi::virgl_renderer_export_query = unsafe {
            // SAFETY: `std::mem::zeroed` is used to create a zeroed struct, which is safe
            // as long as the struct does not have invalid bit patterns for its types,
            // which is the case for this FFI struct.
            std::mem::zeroed()
        };
        query.hdr.stype =
            ffi::virgl_renderer_structure_type_v0_VIRGL_RENDERER_STRUCTURE_TYPE_EXPORT_QUERY;
        query.hdr.stype_version = 0;
        query.hdr.size = size_of::<ffi::virgl_renderer_export_query>() as u32;
        query.in_resource_id = resource_id;
        query.in_export_fds = 0;

        let ret = unsafe {
            // SAFETY: `virgl_renderer_execute` takes a mutable pointer and a size.
            // We provide a valid pointer to our stack variable and the correct size.
            // The function will write to this memory, and we check the return value.
            ffi::virgl_renderer_execute(&mut query as *mut _ as *mut c_void, query.hdr.size)
        };

        if ret != 0 {
            return Err(VirglError::ResourceInfoError);
        }

        if query.out_num_fds == 0 {
            return Err(VirglError::Unsupported);
        }

        Ok(Resource3DInfo {
            width: 0,  // Not returned by this query
            height: 0, // Not returned by this query
            drm_fourcc: query.out_fourcc,
            strides: query.out_strides,
            offsets: query.out_offsets,
            modifier: query.out_modifier,
            guest_cpu_mappable: false,
        })
    }

    fn get_resource_info_ext(
        &self,
        resource_id: u32,
    ) -> Result<ffi::virgl_renderer_resource_info_ext, VirglError> {
        let mut info_ext = unsafe {
            // SAFETY: `std::mem::zeroed` is used to create a zeroed struct, which is safe
            // as long as the struct does not have invalid bit patterns for its types,
            // which is the case for this FFI struct.
            std::mem::zeroed()
        };
        let ret = unsafe {
            // SAFETY: `virgl_renderer_resource_get_info_ext` takes a resource handle and a mutable
            // pointer to a stack variable. We check the return value to ensure the operation succeeded.
            ffi::virgl_renderer_resource_get_info_ext(resource_id as i32, &mut info_ext)
        };
        if ret != 0 {
            return Err(VirglError::ResourceInfoError);
        }
        Ok(info_ext)
    }

    fn get_fd_for_texture(&self, tex_id: u32) -> Result<i32, VirglError> {
        let mut fd = -1;
        let ret = unsafe {
            // SAFETY: `virgl_renderer_get_fd_for_texture` takes a texture ID and a mutable pointer
            // to a stack variable. We check the return value and the validity of the returned FD.
            ffi::virgl_renderer_get_fd_for_texture(tex_id, &mut fd)
        };
        if ret != 0 || fd < 0 {
            return Err(VirglError::IoError(std::io::Error::last_os_error()));
        }
        Ok(fd)
    }

    fn map_info(&self, resource_id: u32) -> Result<u32, VirglError> {
        let mut map_info: u32 = 0;
        let ret = unsafe {
            // SAFETY: `virgl_renderer_resource_get_map_info` takes a resource handle and a mutable
            // pointer to a stack variable. We check the return value.
            ffi::virgl_renderer_resource_get_map_info(resource_id, &mut map_info)
        };
        if ret != 0 {
            return Err(VirglError::MappingFailed);
        }
        Ok(map_info)
    }

    pub fn create_context(
        &self,
        ctx_id: u32,
        context_init: u32,
        context_name: Option<&str>,
    ) -> Result<(), VirglError> {
        let mut name: &str = "gpu_renderer";
        if let Some(name_string) = context_name.filter(|s| !s.is_empty()) {
            name = name_string;
        }

        let ret = unsafe {
            // SAFETY: `virgl_renderer_context_create` and `virgl_renderer_context_create_with_flags`
            // take a context ID, a name length, and a pointer to the name string.
            // We ensure the name pointer is valid and non-null and the length is correct.
            // The C functions do not retain ownership of the pointer. We check the return value.
            match context_init {
                0 => ffi::virgl_renderer_context_create(
                    ctx_id,
                    name.len() as u32,
                    name.as_ptr() as *const c_char,
                ),
                _ => ffi::virgl_renderer_context_create_with_flags(
                    ctx_id,
                    context_init,
                    name.len() as u32,
                    name.as_ptr() as *const c_char,
                ),
            }
        };

        if ret == 0 {
            Ok(())
        } else {
            Err(VirglError::ContextCreationError)
        }
    }

    pub fn destroy_context(&self, ctx_id: u32) {
        unsafe {
            // SAFETY: `virgl_renderer_context_destroy` validates the context and resource id,
            // if they are invalid, this is a NO-OP.
            ffi::virgl_renderer_context_destroy(ctx_id);
        };
    }

    pub fn ctx_attach_resource(&self, ctx_id: u32, resource_id: u32) {
        unsafe {
            // SAFETY: `virgl_renderer_ctx_attach_resource` validates the context and resource id,
            // if they are invalid, this is a NO-OP.
            ffi::virgl_renderer_ctx_attach_resource(ctx_id as i32, resource_id as i32)
        };
    }

    pub fn ctx_detach_resource(&self, ctx_id: u32, resource_id: u32) {
        unsafe {
            // SAFETY: `virgl_renderer_ctx_attach_resource` validates the context and resource id,
            // if they are invalid, this is a NO-OP.
            ffi::virgl_renderer_ctx_detach_resource(ctx_id as i32, resource_id as i32)
        };
    }

    pub fn submit_cmd(
        &self,
        ctx_id: u32,
        commands: &mut [u8],
        fence_ids: &[u64],
    ) -> Result<(), VirglError> {
        if !commands.len().is_multiple_of(size_of::<u32>()) {
            return Err(VirglError::InvalidCommandSize(commands.len()));
        }
        let dword_count = (commands.len() / size_of::<u32>()) as i32;
        #[cfg(not(feature = "virgl_renderer_unstable"))]
        // SAFETY:
        // Safe because the context and buffer are valid and virglrenderer will have been
        // initialized if there are Context instances.
        let ret = unsafe {
            ffi::virgl_renderer_submit_cmd(
                commands.as_mut_ptr() as *mut c_void,
                ctx_id as i32,
                dword_count,
            )
        };
        #[cfg(feature = "virgl_renderer_unstable")]
        // SAFETY:
        // Safe because the context and buffers are valid and virglrenderer will have been
        // initialized if there are Context instances.
        let ret = unsafe {
            ffi::virgl_renderer_submit_cmd2(
                commands.as_mut_ptr() as *mut c_void,
                ctx_id as i32,
                dword_count,
                fence_ids.as_ptr() as *mut u64,
                fence_ids.len() as u32,
            )
        };
        if ret == 0 {
            Ok(())
        } else {
            Err(VirglError::IoError(std::io::Error::last_os_error()))
        }
    }
}

impl Drop for VirglRenderer {
    fn drop(&mut self) {
        unsafe {
            // SAFETY: `virgl_renderer_cleanup` is called to clean up the global state.
            // We pass a null cookie, which is a valid argument. This is safe to call as
            // the `VirglRenderer` instance is the sole owner and is being dropped.
            ffi::virgl_renderer_cleanup(null_mut())
        };
    }
}