arcbox_vm_driver/
lib.rs

1//! `arcbox-vm-driver` — the VM driver port: the vocabulary of "a VM on this
2//! host", and nothing else.
3//!
4//! ArcBox runs VMs under several VMMs — Firecracker and Cloud Hypervisor as
5//! external processes, Virtualization.framework as a managed VMM, its own
6//! Hypervisor.framework engine in-process. Orchestrators (the computer
7//! runtime, the engine's machine registry) must not know which. This crate
8//! is the seam between them: adapters implement it, orchestrators consume
9//! it, and only a composition root names both.
10//!
11//! # What is here
12//!
13//! - [`spec`] — the serializable per-VM shape: [`VmSpec`] and its parts.
14//! - [`driver`] — the port: [`VmDriver`] boots a spec into a [`VmHandle`],
15//!   whose mandatory surface is identify (`id`/`record`), observe
16//!   (`state`/`events`), and stop (`shutdown`); plus the handle vocabulary
17//!   ([`VmState`], [`VmEvent`], [`ExitStatus`], [`ShutdownMode`],
18//!   [`VmRecord`]) and [`DriverCapabilities`], what a driver claims.
19//! - [`capability`] — everything optional, one trait each: [`Vsock`],
20//!   [`VsockListen`], [`Checkpoint`], [`Adopt`]/[`Detach`], [`Prepare`],
21//!   [`Staging`], [`Balloon`], [`Console`], [`DebugSnapshot`]. A handle —
22//!   or the driver, for `Adopt` and `Prepare`; or the prepared VM *and*
23//!   the handle, for `Staging` — exposes each through an
24//!   `Option<&dyn Cap>` accessor, `Some` only when the driver can and the
25//!   spec asked; `capabilities()` must agree with the accessors.
26//! - [`net`] — the second port: [`net::GuestNetwork`] plans and builds
27//!   what a NIC is attached to and hands the driver a [`NicSpec`];
28//!   [`net::NetworkReconcile`] is its token-guarded cleanup protocol.
29//! - [`error`] — the one [`Error`] every port method speaks. There is no
30//!   `Unsupported` variant: what a driver cannot do is a capability
31//!   accessor returning `None`, never an error at call time.
32//! - `testkit` (feature) — the fakes and the contract test-kit: a
33//!   `FakeDriver` and `FakeNetwork` for runtime unit tests on any host, and
34//!   `driver_contract!`, the checks every adapter must pass.
35//!
36//! # Rules the crate is held to
37//!
38//! - No `arcbox-*` dependency, ever: the port sits below every adapter.
39//! - Data is `serde`; behavior is a trait object. A [`VmSpec`] can be
40//!   written in a TOML file; a driver cannot.
41//! - Node-wide knobs (binary paths, seccomp, jailer defaults) are the
42//!   adapter's own config, not part of the spec.
43//!
44//! Design: company repo `engineering/arcbox/architecture/vm-stack-redesign.md`
45//! (D-VM1, D-VM7, D-VM9).
46
47#![warn(missing_docs)]
48
49pub mod capability;
50pub mod driver;
51pub mod error;
52pub mod net;
53pub mod spec;
54#[cfg(feature = "testkit")]
55pub mod testkit;
56
57pub use capability::{
58    Adopt, AfterCheckpoint, Balloon, BalloonStats, Checkpoint, CheckpointFormat, CheckpointImage,
59    CheckpointKind, CheckpointOptions, Console, DebugSnapshot, Detach, DiskSource, Prepare,
60    PreparedVm, Staging, Vsock, VsockListen, VsockListener,
61};
62pub use driver::{
63    DriverCapabilities, ExitStatus, IoMode, JailRecord, NestedVirt, ProcessRecord, RestoreSpec,
64    ShutdownMode, VmDriver, VmEvent, VmHandle, VmRecord, VmState, VsockConn,
65};
66pub use error::{Error, Result};
67pub use spec::{
68    BootSpec, CacheMode, CgroupSpec, ConsoleSpec, DiskSpec, IsolationSpec, MacAddr, NicAttachment,
69    NicSpec, ShareSpec, VmId, VmSpec, VsockSpec,
70};
arcbox_vm_driver/lib.rs

arcbox_vm_driver/
lib.rs
