vmm: Introduce Cloud Hypervisor IPC

Cloud Hypervisor IPC is a simple, mpsc based protocol for threads to
send command to the furture VMM thread. This patch adds the API
definition for that IPC, which will be used by both the main thread
to e.g. start a new VM based on the CLI arguments and the future HTTP
server to relay external requests received from a local Unix domain
socket.
We are moving it to its own "api" module because this is where the
external API (HTTP based) will also be implemented.

The VMM thread will be listening for IPC requests from an mpsc receiver,
process them and send a response back through another mpsc channel.

Signed-off-by: Samuel Ortiz <sameo@linux.intel.com>

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<ApiResponsePayload, ApiError>;
+
+#[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<VmConfig>, Sender<ApiResponse>),
+
+    /// 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<ApiResponse>),
+}

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;