Add API endpoint for hotplugging

Create a new endpoint `hotplug` in `parsed_request.rs` and implement
basic skeleton of endpoint implementation.

Signed-off-by: James Curtis <jxcurtis@amazon.co.uk>

Author: JamesC1305

src/firecracker/src/api_server/parsed_request.rs

@@ -15,6 +15,8 @@ use super::request::boot_source::parse_put_boot_source;
 use super::request::cpu_configuration::parse_put_cpu_config;
 use super::request::drive::{parse_patch_drive, parse_put_drive};
 use super::request::entropy::parse_put_entropy;
+#[cfg(target_arch = "x86_64")]
+use super::request::hotplug::parse_put_hotplug;
 use super::request::instance_info::parse_get_instance_info;
 use super::request::logger::parse_put_logger;
 use super::request::machine_configuration::{
@@ -89,6 +91,8 @@ impl TryFrom<&Request> for ParsedRequest {
             (Method::Put, "boot-source", Some(body)) => parse_put_boot_source(body),
             (Method::Put, "cpu-config", Some(body)) => parse_put_cpu_config(body),
             (Method::Put, "drives", Some(body)) => parse_put_drive(body, path_tokens.next()),
+            #[cfg(target_arch = "x86_64")]
+            (Method::Put, "hotplug", Some(body)) => parse_put_hotplug(body),
             (Method::Put, "logger", Some(body)) => parse_put_logger(body),
             (Method::Put, "machine-config", Some(body)) => parse_put_machine_config(body),
             (Method::Put, "metrics", Some(body)) => parse_put_metrics(body),
@@ -746,6 +750,22 @@ pub mod tests {
         ParsedRequest::try_from(&req).unwrap();
     }
 
+    #[test]
+    #[cfg(target_arch = "x86_64")]
+    fn test_try_from_put_hotplug_vcpu() {
+        let (mut sender, receiver) = UnixStream::pair().unwrap();
+        let mut connection = HttpConnection::new(receiver);
+        let body = r#"{
+            "Vcpu": { "add": 1 }
+        }"#;
+        sender
+            .write_all(http_request("PUT", "/hotplug", Some(body)).as_bytes())
+            .unwrap();
+        connection.try_read().unwrap();
+        let req = connection.pop_parsed_request().unwrap();
+        ParsedRequest::try_from(&req).unwrap();
+    }
+
     #[test]
     fn test_try_from_put_logger() {
         let (mut sender, receiver) = UnixStream::pair().unwrap();

src/firecracker/src/api_server/request/hotplug.rs

@@ -0,0 +1,47 @@
+// Copyright 2024 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+use vmm::logger::{IncMetric, METRICS};
+use vmm::rpc_interface::VmmAction;
+use vmm::vmm_config::hotplug::HotplugRequestConfig;
+
+use super::super::parsed_request::{ParsedRequest, RequestError};
+use super::Body;
+
+pub(crate) fn parse_put_hotplug(body: &Body) -> Result<ParsedRequest, RequestError> {
+    METRICS.put_api_requests.hotplug.inc();
+    METRICS.hotplug.hotplug_request_count.inc();
+    let config = serde_json::from_slice::<HotplugRequestConfig>(body.raw()).map_err(|err| {
+        METRICS.hotplug.hotplug_request_fails.inc();
+        err
+    })?;
+    Ok(ParsedRequest::new_sync(VmmAction::HotplugRequest(config)))
+}
+
+#[cfg(test)]
+mod tests {
+
+    use hotplug::parse_put_hotplug;
+    use vmm::rpc_interface::VmmAction;
+    use vmm::vmm_config::hotplug::{HotplugRequestConfig, HotplugVcpuConfig};
+
+    use super::super::*;
+    use crate::api_server::parsed_request::tests::vmm_action_from_request;
+
+    #[test]
+    fn test_parse_put_hotplug() {
+        // Case 1. Invalid body
+        parse_put_hotplug(&Body::new("invalid body")).unwrap_err();
+
+        // Case 2. vCPU Resource
+        let body = r#"{
+            "Vcpu" : { "add": 4 }
+        }"#;
+
+        let expected_config = HotplugVcpuConfig { add: 4 };
+
+        assert_eq!(
+            vmm_action_from_request(parse_put_hotplug(&Body::new(body)).unwrap()),
+            VmmAction::HotplugRequest(HotplugRequestConfig::Vcpu(expected_config))
+        );
+    }
+}

src/firecracker/src/api_server/request/mod.rs

@@ -7,6 +7,8 @@ pub mod boot_source;
 pub mod cpu_configuration;
 pub mod drive;
 pub mod entropy;
+#[cfg(target_arch = "x86_64")]
+pub mod hotplug;
 pub mod instance_info;
 pub mod logger;
 pub mod machine_configuration;

src/firecracker/swagger/firecracker.yaml

@@ -282,6 +282,30 @@ paths:
           schema:
             $ref: "#/definitions/Error"
 
+  /hotplug:
+    put:
+      summary: Hotplugs resources to the microVM. Only available for x86_64 hosts. Post-boot only.
+      description:
+        Adds new resources to the VM.
+      parameters:
+        - name: body
+          in: body
+          description: The resource type and amount to be hotplugged.
+          required: true
+          schema: 
+            $ref: "#/definitions/Hotplug"
+      responses:
+        204:
+          description: Resources hotplugged successfully.
+        400: 
+          description: Resources cannot be hotplugged due to bad input or a VMM-related error.
+          schema:
+            $ref: "#/definitions/Error"
+        default:
+          description: Internal server error.
+          schema:
+            $ref: "#/definitions/Error"
+
   /logger:
     put:
       summary: Initializes the logger by specifying a named pipe or a file for the logs output.
@@ -943,6 +967,21 @@ definitions:
       vsock:
         $ref: "#/definitions/Vsock"
 
+  Hotplug:
+    type: object
+    description:
+      Defines the configuration for hot plugging.
+    properties:
+      Vcpu:
+        type: object
+        description: Hotplug requests relating to vCPU cores.
+        properties:
+          add:
+            description: Number of vCPUs cores to be added to the VM
+            type: integer
+            minimum: 1
+
+
   InstanceActionInfo:
     type: object
     description:

src/vmm/src/logger/metrics.rs

@@ -410,6 +410,10 @@ pub struct PutRequestsMetrics {
     pub drive_count: SharedIncMetric,
     /// Number of failures in attaching a block device.
     pub drive_fails: SharedIncMetric,
+    /// Number of PUTs for hotplugging
+    pub hotplug: SharedIncMetric,
+    /// Number of failures for hotplugging.
+    pub hotplug_fails: SharedIncMetric,
     /// Number of PUTs for initializing the logging system.
     pub logger_count: SharedIncMetric,
     /// Number of failures in initializing the logging system.
@@ -449,6 +453,8 @@ impl PutRequestsMetrics {
             boot_source_fails: SharedIncMetric::new(),
             drive_count: SharedIncMetric::new(),
             drive_fails: SharedIncMetric::new(),
+            hotplug: SharedIncMetric::new(),
+            hotplug_fails: SharedIncMetric::new(),
             logger_count: SharedIncMetric::new(),
             logger_fails: SharedIncMetric::new(),
             machine_cfg_count: SharedIncMetric::new(),
@@ -824,6 +830,28 @@ impl VmmMetrics {
     }
 }
 
+/// Metrics specific to hotplugging
+#[derive(Debug, Default, Serialize)]
+pub struct HotplugMetrics {
+    pub hotplug_request_count: SharedIncMetric,
+    pub hotplug_request_fails: SharedIncMetric,
+    pub vcpu_hotplug_request_fails: SharedIncMetric,
+    pub vcpus_added: SharedIncMetric,
+}
+
+impl HotplugMetrics {
+    /// Const default construction.
+
+    pub const fn new() -> Self {
+        Self {
+            hotplug_request_count: SharedIncMetric::new(),
+            hotplug_request_fails: SharedIncMetric::new(),
+            vcpu_hotplug_request_fails: SharedIncMetric::new(),
+            vcpus_added: SharedIncMetric::new(),
+        }
+    }
+}
+
 // The sole purpose of this struct is to produce an UTC timestamp when an instance is serialized.
 #[derive(Debug, Default)]
 struct SerializeToUtcTimestampMs;
@@ -887,6 +915,8 @@ pub struct FirecrackerMetrics {
     pub deprecated_api: DeprecatedApiMetrics,
     /// Metrics related to API GET requests.
     pub get_api_requests: GetRequestsMetrics,
+    /// Metrics related to hot-plugging.
+    pub hotplug: HotplugMetrics,
     #[serde(flatten)]
     /// Metrics related to the legacy device.
     pub legacy_dev_ser: LegacyDevMetricsSerializeProxy,
@@ -931,6 +961,7 @@ impl FirecrackerMetrics {
             block_ser: BlockMetricsSerializeProxy {},
             deprecated_api: DeprecatedApiMetrics::new(),
             get_api_requests: GetRequestsMetrics::new(),
+            hotplug: HotplugMetrics::new(),
             legacy_dev_ser: LegacyDevMetricsSerializeProxy {},
             latencies_us: PerformanceMetrics::new(),
             logger: LoggerSystemMetrics::new(),

src/vmm/src/rpc_interface.rs

@@ -20,6 +20,8 @@ use super::{
 };
 use crate::builder::StartMicrovmError;
 use crate::cpu_config::templates::{CustomCpuTemplate, GuestConfigError};
+#[cfg(target_arch = "x86_64")]
+use crate::logger::METRICS;
 use crate::logger::{info, warn, LoggerConfig, *};
 use crate::mmds::data_store::{self, Mmds};
 use crate::persist::{CreateSnapshotError, RestoreFromSnapshotError, VmInfo};
@@ -31,6 +33,8 @@ use crate::vmm_config::balloon::{
 use crate::vmm_config::boot_source::{BootSourceConfig, BootSourceConfigError};
 use crate::vmm_config::drive::{BlockDeviceConfig, BlockDeviceUpdateConfig, DriveError};
 use crate::vmm_config::entropy::{EntropyDeviceConfig, EntropyDeviceError};
+#[cfg(target_arch = "x86_64")]
+use crate::vmm_config::hotplug::{HotplugRequestConfig, HotplugRequestError};
 use crate::vmm_config::instance_info::InstanceInfo;
 use crate::vmm_config::machine_config::{MachineConfig, MachineConfigUpdate, VmConfigError};
 use crate::vmm_config::metrics::{MetricsConfig, MetricsConfigError};
@@ -75,6 +79,9 @@ pub enum VmmAction {
     GetVmmVersion,
     /// Flush the metrics. This action can only be called after the logger has been configured.
     FlushMetrics,
+    /// Hotplug resources into the VM.
+    #[cfg(target_arch = "x86_64")]
+    HotplugRequest(HotplugRequestConfig),
     /// Add a new block device or update one that already exists using the `BlockDeviceConfig` as
     /// input. This action can only be called before the microVM has booted.
     InsertBlockDevice(BlockDeviceConfig),
@@ -144,6 +151,9 @@ pub enum VmmActionError {
     DriveConfig(#[from] DriveError),
     /// Entropy device error: {0}
     EntropyDevice(#[from] EntropyDeviceError),
+    /// Hotplug error: {0}
+    #[cfg(target_arch = "x86_64")]
+    HotplugRequest(#[from] HotplugRequestError),
     /// Internal VMM error: {0}
     InternalVmm(#[from] VmmError),
     /// Load snapshot error: {0}
@@ -453,6 +463,8 @@ impl<'a> PrebootApiController<'a> {
             | UpdateNetworkInterface(_) => Err(VmmActionError::OperationNotSupportedPreBoot),
             #[cfg(target_arch = "x86_64")]
             SendCtrlAltDel => Err(VmmActionError::OperationNotSupportedPreBoot),
+            #[cfg(target_arch = "x86_64")]
+            HotplugRequest(_) => Err(VmmActionError::OperationNotSupportedPreBoot),
         }
     }
 
@@ -657,6 +669,8 @@ impl RuntimeApiController {
             GetVmmVersion => Ok(VmmData::VmmVersion(
                 self.vmm.lock().expect("Poisoned lock").version(),
             )),
+            #[cfg(target_arch = "x86_64")]
+            HotplugRequest(config) => Ok(VmmData::Empty),
             PatchMMDS(value) => self.patch_mmds(value),
             Pause => self.pause(),
             PutMMDS(value) => self.put_mmds(value),

src/vmm/src/vmm_config/hotplug.rs

@@ -0,0 +1,47 @@
+// Copyright 2024 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+use std::io;
+
+use serde::{Deserialize, Serialize};
+
+use crate::vstate::vcpu::VcpuError;
+use crate::StartVcpusError;
+/// Unifying enum for all types of hotplug request configs.
+/// Currently only Vcpus may be hotplugged.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
+pub enum HotplugRequestConfig {
+    /// Vcpu hotplug request
+    Vcpu(HotplugVcpuConfig),
+}
+
+/// Errors related to different types of hotplugging.
+/// Currently only Vcpus can be hotplugged.
+#[derive(Debug, thiserror::Error, displaydoc::Display)]
+pub enum HotplugRequestError {
+    /// Vcpu hotplugging error: {0}
+    Vcpu(#[from] HotplugVcpuError),
+}
+
+/// Errors associated with hot-plugging vCPUs
+#[derive(Debug, thiserror::Error, displaydoc::Display)]
+pub enum HotplugVcpuError {
+    /// The number of vCPUs added must be greater than 0.
+    VcpuCountTooLow,
+    /// The number of vCPUs added must be less than 32.
+    VcpuCountTooHigh,
+    /// Event fd error: {0}
+    EventFd(io::Error),
+    /// Error creating the vcpu: {0}
+    VcpuCreate(VcpuError),
+    /// Failed to start vCPUs
+    VcpuStart(StartVcpusError),
+}
+
+/// Config for hotplugging vCPUS
+#[derive(Clone, Debug, PartialEq, Eq, Deserialize, Serialize)]
+#[serde(deny_unknown_fields)]
+pub struct HotplugVcpuConfig {
+    /// Number of vcpus to start.
+    pub add: u8,
+}

src/vmm/src/vmm_config/mod.rs

@@ -20,6 +20,9 @@ pub mod boot_source;
 pub mod drive;
 /// Wrapper for configuring the entropy device attached to the microVM.
 pub mod entropy;
+/// Wrapper over hotplug configuration.
+#[cfg(target_arch = "x86_64")]
+pub mod hotplug;
 /// Wrapper over the microVM general information attached to the microVM.
 pub mod instance_info;
 /// Wrapper for configuring the memory and CPU of the microVM.

tests/host_tools/fcmetrics.py

@@ -152,6 +152,12 @@ def validate_fc_metrics(metrics):
             "mmds_count",
             "vmm_version_count",
         ],
+        "hotplug": [
+            "hotplug_request_count",
+            "hotplug_request_fails",
+            "vcpu_hotplug_request_fails",
+            "vcpus_added",
+        ],
         "i8042": [
             "error_count",
             "missed_read_count",
@@ -209,6 +215,8 @@ def validate_fc_metrics(metrics):
             "boot_source_fails",
             "drive_count",
             "drive_fails",
+            "hotplug",
+            "hotplug_fails",
             "logger_count",
             "logger_fails",
             "machine_cfg_count",