feat(virtio-mem): add to VmmConfig and PUT API

Allow to configure the virtio-mem device from the VmmConfig and the PUT
API to /hotplug/memory.

Signed-off-by: Riccardo Mancini <[email protected]>

Author: Manciukic

src/firecracker/src/api_server/parsed_request.rs

@@ -27,6 +27,7 @@ use super::request::net::{parse_patch_net, parse_put_net};
 use super::request::snapshot::{parse_patch_vm_state, parse_put_snapshot};
 use super::request::version::parse_get_version;
 use super::request::vsock::parse_put_vsock;
+use crate::api_server::request::hotplug::parse_hotplug;
 
 #[derive(Debug)]
 pub(crate) enum RequestAction {
@@ -109,6 +110,7 @@ impl TryFrom<&Request> for ParsedRequest {
             }
             (Method::Patch, "vm", Some(body)) => parse_patch_vm_state(body),
             (Method::Patch, _, None) => method_to_error(Method::Patch),
+            (method, "hotplug", body) => parse_hotplug(method, path_tokens.next(), body),
             (method, unknown_uri, _) => Err(RequestError::InvalidPathMethod(
                 unknown_uri.to_string(),
                 method,

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

@@ -0,0 +1,64 @@
+// Copyright 2025 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+use micro_http::Body;
+use vmm::rpc_interface::VmmAction;
+use vmm::vmm_config::memory_hotplug::MemoryHotplugConfig;
+
+use crate::api_server::parsed_request::{ParsedRequest, RequestError};
+
+pub(crate) fn parse_put_memory_hotplug(body: &Body) -> Result<ParsedRequest, RequestError> {
+    Ok(ParsedRequest::new_sync(VmmAction::SetMemoryHotplugDevice(
+        serde_json::from_slice::<MemoryHotplugConfig>(body.raw())?,
+    )))
+}
+
+#[cfg(test)]
+mod tests {
+    use vmm::devices::virtio::mem::{VIRTIO_MEM_DEFAULT_BLOCK_SIZE, VIRTIO_MEM_DEFAULT_SLOT_SIZE};
+    use vmm::utils::bytes_to_mib;
+
+    use super::*;
+    use crate::api_server::parsed_request::tests::vmm_action_from_request;
+
+    #[test]
+    fn test_parse_put_memory_hotplug_request() {
+        parse_put_memory_hotplug(&Body::new("invalid_payload")).unwrap_err();
+
+        // PUT with invalid fields.
+        let body = r#"{
+            "total_size_mib": "bar"
+        }"#;
+        parse_put_memory_hotplug(&Body::new(body)).unwrap_err();
+
+        // PUT with valid input fields with defaults.
+        let body = r#"{
+            "total_size_mib": 2048
+        }"#;
+        let expected_config = MemoryHotplugConfig {
+            total_size_mib: 2048,
+            block_size_mib: bytes_to_mib(VIRTIO_MEM_DEFAULT_BLOCK_SIZE),
+            slot_size_mib: bytes_to_mib(VIRTIO_MEM_DEFAULT_SLOT_SIZE),
+        };
+        assert_eq!(
+            vmm_action_from_request(parse_put_memory_hotplug(&Body::new(body)).unwrap()),
+            VmmAction::SetMemoryHotplugDevice(expected_config)
+        );
+
+        // PUT with valid input fields.
+        let body = r#"{
+            "total_size_mib": 2048,
+            "block_size_mib": 64,
+            "slot_size_mib": 64
+        }"#;
+        let expected_config = MemoryHotplugConfig {
+            total_size_mib: 2048,
+            block_size_mib: 64,
+            slot_size_mib: 64,
+        };
+        assert_eq!(
+            vmm_action_from_request(parse_put_memory_hotplug(&Body::new(body)).unwrap()),
+            VmmAction::SetMemoryHotplugDevice(expected_config)
+        );
+    }
+}

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

@@ -0,0 +1,25 @@
+// Copyright 2025 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+mod memory;
+
+use micro_http::{Body, Method};
+
+use crate::api_server::parsed_request::{ParsedRequest, RequestError};
+use crate::api_server::request::hotplug::memory::parse_put_memory_hotplug;
+
+pub(crate) fn parse_hotplug(
+    method: Method,
+    token: Option<&str>,
+    body: Option<&Body>,
+) -> Result<ParsedRequest, RequestError> {
+    let token =
+        token.ok_or_else(|| RequestError::InvalidPathMethod("hotplug".to_string(), method))?;
+    match (method, token, body) {
+        (Method::Put, "memory", Some(body)) => parse_put_memory_hotplug(body),
+        (method, unknown_uri, _) => Err(RequestError::InvalidPathMethod(
+            unknown_uri.to_string(),
+            method,
+        )),
+    }
+}

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

@@ -7,6 +7,7 @@ pub mod boot_source;
 pub mod cpu_configuration;
 pub mod drive;
 pub mod entropy;
+pub mod hotplug;
 pub mod instance_info;
 pub mod logger;
 pub mod machine_configuration;

src/vmm/src/device_manager/pci_mngr.rs

@@ -670,6 +670,7 @@ mod tests {
         let _restored_dev_manager =
             PciDevices::restore(restore_args, &device_manager_state.pci_state).unwrap();
 
+        // TODO(virtio-mem): add memory-hotplug device when snapshot-restore is implemented
         let expected_vm_resources = format!(
             r#"{{
   "balloon": {{
@@ -728,7 +729,8 @@ mod tests {
   }},
   "entropy": {{
     "rate_limiter": null
-  }}
+  }},
+  "memory-hotplug": null
 }}"#,
             _block_files.last().unwrap().as_path().to_str().unwrap(),
             tmp_sock_file.as_path().to_str().unwrap()

src/vmm/src/device_manager/persist.rs

@@ -696,6 +696,7 @@ mod tests {
         let _restored_dev_manager =
             MMIODeviceManager::restore(restore_args, &device_manager_state.mmio_state).unwrap();
 
+        // TODO(virtio-mem): add memory-hotplug device when snapshot-restore is implemented
         let expected_vm_resources = format!(
             r#"{{
   "balloon": {{
@@ -754,7 +755,8 @@ mod tests {
   }},
   "entropy": {{
     "rate_limiter": null
-  }}
+  }},
+  "memory-hotplug": null
 }}"#,
             _block_files.last().unwrap().as_path().to_str().unwrap(),
             tmp_sock_file.as_path().to_str().unwrap()

src/vmm/src/resources.rs

@@ -25,6 +25,7 @@ use crate::vmm_config::instance_info::InstanceInfo;
 use crate::vmm_config::machine_config::{
     HugePageConfig, MachineConfig, MachineConfigError, MachineConfigUpdate,
 };
+use crate::vmm_config::memory_hotplug::{MemoryHotplugConfig, MemoryHotplugConfigError};
 use crate::vmm_config::metrics::{MetricsConfig, MetricsConfigError, init_metrics};
 use crate::vmm_config::mmds::{MmdsConfig, MmdsConfigError};
 use crate::vmm_config::net::*;
@@ -61,6 +62,8 @@ pub enum ResourcesError {
     VsockDevice(#[from] VsockConfigError),
     /// Entropy device error: {0}
     EntropyDevice(#[from] EntropyDeviceError),
+    /// Memory hotplug config error: {0}
+    MemoryHotplugConfig(#[from] MemoryHotplugConfigError),
 }
 
 #[derive(Serialize, Deserialize, PartialEq, Eq, Debug)]
@@ -86,6 +89,7 @@ pub struct VmmConfig {
     network_interfaces: Vec<NetworkInterfaceConfig>,
     vsock: Option<VsockDeviceConfig>,
     entropy: Option<EntropyDeviceConfig>,
+    memory_hotplug: Option<MemoryHotplugConfig>,
 }
 
 /// A data structure that encapsulates the device configurations
@@ -106,6 +110,8 @@ pub struct VmResources {
     pub net_builder: NetBuilder,
     /// The entropy device builder.
     pub entropy: EntropyDeviceBuilder,
+    /// The memory hotplug configuration.
+    pub memory_hotplug: Option<MemoryHotplugConfig>,
     /// The optional Mmds data store.
     // This is initialised on demand (if ever used), so that we don't allocate it unless it's
     // actually used.
@@ -193,6 +199,10 @@ impl VmResources {
             resources.build_entropy_device(entropy_device_config)?;
         }
 
+        if let Some(memory_hotplug_config) = vmm_config.memory_hotplug {
+            resources.set_memory_hotplug_config(memory_hotplug_config)?;
+        }
+
         Ok(resources)
     }
 
@@ -380,6 +390,16 @@ impl VmResources {
         self.entropy.insert(body)
     }
 
+    /// Sets the memory hotplug configuration.
+    pub fn set_memory_hotplug_config(
+        &mut self,
+        config: MemoryHotplugConfig,
+    ) -> Result<(), MemoryHotplugConfigError> {
+        config.validate()?;
+        self.memory_hotplug = Some(config);
+        Ok(())
+    }
+
     /// Setter for mmds config.
     pub fn set_mmds_config(
         &mut self,
@@ -506,6 +526,7 @@ impl From<&VmResources> for VmmConfig {
             network_interfaces: resources.net_builder.configs(),
             vsock: resources.vsock.config(),
             entropy: resources.entropy.config(),
+            memory_hotplug: resources.memory_hotplug.clone(),
         }
     }
 }
@@ -617,6 +638,7 @@ mod tests {
             mmds_size_limit: HTTP_MAX_PAYLOAD_SIZE,
             entropy: Default::default(),
             pci_enabled: false,
+            memory_hotplug: Default::default(),
         }
     }
 

src/vmm/src/rpc_interface.rs

@@ -28,6 +28,7 @@ use crate::vmm_config::drive::{BlockDeviceConfig, BlockDeviceUpdateConfig, Drive
 use crate::vmm_config::entropy::{EntropyDeviceConfig, EntropyDeviceError};
 use crate::vmm_config::instance_info::InstanceInfo;
 use crate::vmm_config::machine_config::{MachineConfig, MachineConfigError, MachineConfigUpdate};
+use crate::vmm_config::memory_hotplug::{MemoryHotplugConfig, MemoryHotplugConfigError};
 use crate::vmm_config::metrics::{MetricsConfig, MetricsConfigError};
 use crate::vmm_config::mmds::{MmdsConfig, MmdsConfigError};
 use crate::vmm_config::net::{
@@ -103,6 +104,9 @@ pub enum VmmAction {
     /// Set the entropy device using `EntropyDeviceConfig` as input. This action can only be called
     /// before the microVM has booted.
     SetEntropyDevice(EntropyDeviceConfig),
+    /// Set the memory hotplug device using `MemoryHotplugConfig` as input. This action can only be
+    /// called before the microVM has booted.
+    SetMemoryHotplugDevice(MemoryHotplugConfig),
     /// Launch the microVM. This action can only be called before the microVM has booted.
     StartMicroVm,
     /// Send CTRL+ALT+DEL to the microVM, using the i8042 keyboard function. If an AT-keyboard
@@ -138,6 +142,8 @@ pub enum VmmActionError {
     DriveConfig(#[from] DriveError),
     /// Entropy device error: {0}
     EntropyDevice(#[from] EntropyDeviceError),
+    /// Memory hotplug config error: {0}
+    MemoryHotplugConfig(#[from] MemoryHotplugConfigError),
     /// Internal VMM error: {0}
     InternalVmm(#[from] VmmError),
     /// Load snapshot error: {0}
@@ -438,6 +444,7 @@ impl<'a> PrebootApiController<'a> {
             StartMicroVm => self.start_microvm(),
             UpdateMachineConfiguration(config) => self.update_machine_config(config),
             SetEntropyDevice(config) => self.set_entropy_device(config),
+            SetMemoryHotplugDevice(config) => self.set_memory_hotplug_device(config),
             // Operations not allowed pre-boot.
             CreateSnapshot(_)
             | FlushMetrics
@@ -537,6 +544,16 @@ impl<'a> PrebootApiController<'a> {
         Ok(VmmData::Empty)
     }
 
+    fn set_memory_hotplug_device(
+        &mut self,
+        cfg: MemoryHotplugConfig,
+    ) -> Result<VmmData, VmmActionError> {
+        self.boot_path = true;
+        cfg.validate()?;
+        self.vm_resources.set_memory_hotplug_config(cfg)?;
+        Ok(VmmData::Empty)
+    }
+
     // On success, this command will end the pre-boot stage and this controller
     // will be replaced by a runtime controller.
     fn start_microvm(&mut self) -> Result<VmmData, VmmActionError> {
@@ -684,6 +701,7 @@ impl RuntimeApiController {
             | SetVsockDevice(_)
             | SetMmdsConfiguration(_)
             | SetEntropyDevice(_)
+            | SetMemoryHotplugDevice(_)
             | StartMicroVm
             | UpdateMachineConfiguration(_) => Err(VmmActionError::OperationNotSupportedPostBoot),
         }
@@ -1262,5 +1280,8 @@ mod tests {
         check_unsupported(runtime_request(VmmAction::SetEntropyDevice(
             EntropyDeviceConfig::default(),
         )));
+        check_unsupported(runtime_request(VmmAction::SetMemoryHotplugDevice(
+            MemoryHotplugConfig::default(),
+        )));
     }
 }

src/vmm/src/utils/mod.rs

@@ -54,6 +54,11 @@ pub const fn mib_to_bytes(mib: usize) -> usize {
     mib << MIB_TO_BYTES_SHIFT
 }
 
+/// Converts Bytes to MiB, truncating any remainder
+pub const fn bytes_to_mib(bytes: usize) -> usize {
+    bytes >> MIB_TO_BYTES_SHIFT
+}
+
 /// Align address up to the aligment.
 pub const fn align_up(addr: u64, align: u64) -> u64 {
     debug_assert!(align != 0);