arcbox_hypervisor/
lib.rs

1//! # arcbox-hypervisor
2//!
3//! Cross-platform hypervisor abstraction layer for `ArcBox`.
4//!
5//! This crate provides platform-agnostic traits for virtualization:
6//! - [`Hypervisor`]: Main entry point for creating VMs
7//! - [`VirtualMachine`]: VM lifecycle management
8//! - [`Vcpu`]: Virtual CPU execution
9//! - [`GuestMemory`]: Guest memory access
10//!
11//! ## Platform Backends
12//!
13//! - **macOS**: Uses `Virtualization.framework`
14//! - **Linux**: Uses KVM (`/dev/kvm`)
15//!
16//! ## Example
17//!
18//! ```ignore
19//! use arcbox_hypervisor::{create_hypervisor, VmConfig};
20//!
21//! let hypervisor = create_hypervisor()?;
22//! let config = VmConfig::builder()
23//!     .vcpu_count(4)
24//!     .memory_size(4 * 1024 * 1024 * 1024) // 4GB
25//!     .build();
26//! let vm = hypervisor.create_vm(config)?;
27//! ```
28
29// FFI bindings require extensive pointer casts.
30#![allow(clippy::ptr_as_ptr)]
31#![allow(clippy::ptr_cast_constness)]
32#![allow(clippy::ref_as_ptr)]
33#![allow(clippy::borrow_as_ptr)]
34#![allow(clippy::field_reassign_with_default)]
35#![allow(clippy::unnecessary_cast)]
36#![allow(clippy::wildcard_enum_match_arm)]
37#![allow(unused_unsafe)]
38#![allow(clippy::let_and_return)]
39#![allow(clippy::manual_div_ceil)]
40#![allow(clippy::match_wildcard_for_single_variants)]
41#![allow(clippy::redundant_closure)]
42#![allow(clippy::map_unwrap_or)]
43#![allow(clippy::comparison_chain)]
44#![allow(clippy::expect_fun_call)]
45
46pub mod capability;
47pub mod config;
48pub mod error;
49pub mod memory;
50pub mod traits;
51pub mod types;
52
53#[cfg(target_os = "macos")]
54pub mod darwin;
55
56#[cfg(target_os = "linux")]
57pub mod linux;
58
59pub use capability::{NestedVirtSupport, host_nested_virt};
60pub use config::{VmConfig, VmConfigBuilder};
61pub use error::{HypervisorError, Result};
62pub use memory::{GuestAddress, MemoryRegion};
63pub use traits::{GuestMemory, Hypervisor, Vcpu, VirtualMachine};
64pub use types::{
65    Arm64Registers, BalloonStats, CpuArch, DeviceSnapshot, DirtyPageInfo, MemoryRegionSnapshot,
66    PlatformCapabilities, Registers, VcpuExit, VcpuSnapshot, VirtioDeviceConfig, VirtioDeviceType,
67    VmSnapshot, default_vm_cpu_count, default_vm_memory_size, host_memory_size,
68};
69
70/// Creates the appropriate hypervisor for the current platform.
71///
72/// # Errors
73///
74/// Returns an error if the hypervisor cannot be initialized.
75pub fn create_hypervisor() -> Result<impl Hypervisor> {
76    #[cfg(target_os = "macos")]
77    {
78        darwin::DarwinHypervisor::new()
79    }
80
81    #[cfg(target_os = "linux")]
82    {
83        linux::KvmHypervisor::new()
84    }
85
86    #[cfg(not(any(target_os = "macos", target_os = "linux")))]
87    {
88        compile_error!("Unsupported platform: only macOS and Linux are supported")
89    }
90}
arcbox_hypervisor/lib.rs

arcbox_hypervisor/
lib.rs
