diff --git a/vmm/src/api/mod.rs b/vmm/src/api/mod.rs new file mode 100644 index 000000000..e71f9e151 --- /dev/null +++ b/vmm/src/api/mod.rs @@ -0,0 +1,66 @@ +// Copyright © 2019 Intel Corporation +// +// SPDX-License-Identifier: Apache-2.0 +// + +//! The internal VMM API for Cloud Hypervisor. +//! +//! This API is a synchronous, [mpsc](https://doc.rust-lang.org/std/sync/mpsc/) +//! based IPC for sending commands to the VMM thread, from other +//! Cloud Hypervisor threads. The IPC follows a command-response protocol, i.e. +//! each command will receive a response back. +//! +//! The main Cloud Hypervisor thread creates an API event file descriptor +//! to notify the VMM thread about pending API commands, together with an +//! API mpsc channel. The former is the IPC control plane, the latter is the +//! IPC data plane. +//! In order to use the IPC, a Cloud Hypervisor thread needs to have a clone +//! of both the API event file descriptor and the channel Sender. Then it must +//! go through the following steps: +//! +//! 1. The thread creates an mpsc channel for receiving the command response. +//! 2. The thread sends an ApiRequest to the Sender endpoint. The ApiRequest +//! contains the response channel Sender, for the VMM API server to be able +//! to send the response back. +//! 3. The thread writes to the API event file descriptor to notify the VMM +//! API server about a pending command. +//! 4. The thread reads the response back from the VMM API server, from the +//! response channel Receiver. +//! 5. The thread handles the response and forwards potential errors. + +use crate::config::VmConfig; +use crate::vm::Error; +use std::sync::mpsc::Sender; +use std::sync::Arc; + +/// API errors are sent back from the VMM API server through the ApiResponse. +#[derive(Debug)] +pub enum ApiError { + /// The VM could not be created. + VmCreate(Error), + + /// The VM could not start. + VmStart(Error), +} + +pub enum ApiResponsePayload { + /// No data is sent on the channel. + Empty, +} + +/// This is the response sent by the VMM API server through the mpsc channel. +pub type ApiResponse = std::result::Result; + +#[allow(clippy::large_enum_variant)] +pub enum ApiRequest { + /// Create the virtual machine. This request payload is a VM configuration + /// (VmConfig). + /// If the VMM API server could not create the VM, it will send a VmCreate + /// error back. + VmCreate(Arc, Sender), + + /// Start the previously created virtual machine. + /// If the VM was not previously created, the VMM API server will send a + /// VmStart error back. + VmStart(Sender), +} diff --git a/vmm/src/lib.rs b/vmm/src/lib.rs index 04dec0b3c..270488d08 100644 --- a/vmm/src/lib.rs +++ b/vmm/src/lib.rs @@ -14,6 +14,7 @@ use std::result; use std::sync::Arc; use vmm_sys_util::eventfd::EventFd; +pub mod api; pub mod config; pub mod device_manager; pub mod vm;