Split endpoints

Author: ValentaTomas

resources/seccomp/aarch64-unknown-linux-musl.json

@@ -220,6 +220,10 @@
                 "syscall": "madvise",
                 "comment": "Used by the VirtIO balloon device and by musl for some customer workloads. It is also used by aws-lc during random number generation. They setup a memory page that mark with MADV_WIPEONFORK to be able to detect forks. They also call it with -1 to see if madvise is supported in certain platforms." 
             },
+            {
+                "syscall": "mincore",
+                "comment": "Used by get_memory_dirty_bitmap to check if memory pages are resident"
+            },
             {
                 "syscall": "mmap",
                 "comment": "Used by the VirtIO balloon device",

resources/seccomp/x86_64-unknown-linux-musl.json

@@ -216,6 +216,10 @@
                 "syscall": "madvise",
                 "comment": "Used by the VirtIO balloon device and by musl for some customer workloads. It is also used by aws-lc during random number generation. They setup a memory page that mark with MADV_WIPEONFORK to be able to detect forks. They also call it with -1 to see if madvise is supported in certain platforms." 
             },
+            {
+                "syscall": "mincore",
+                "comment": "Used by get_memory_dirty_bitmap to check if memory pages are resident"
+            },
             {
                 "syscall": "mmap",
                 "comment": "Used by the VirtIO balloon device",
@@ -524,8 +528,8 @@
                 "comment": "sigaltstack is used by Rust stdlib to remove alternative signal stack during thread teardown."
             },
             {
-              "syscall": "getrandom",
-              "comment": "getrandom is used by `HttpServer` to reinialize `HashMap` after moving to the API thread"
+                "syscall": "getrandom",
+                "comment": "getrandom is used by `HttpServer` to reinialize `HashMap` after moving to the API thread"
             },
             {
                 "syscall": "accept4",
@@ -1276,4 +1280,4 @@
             }
         ]
     }
-}
+}

src/firecracker/src/api_server/parsed_request.rs

@@ -20,6 +20,7 @@ use super::request::logger::parse_put_logger;
 use super::request::machine_configuration::{
     parse_get_machine_config, parse_patch_machine_config, parse_put_machine_config,
 };
+use super::request::memory::{parse_get_memory, parse_get_memory_mappings};
 use super::request::metrics::parse_put_metrics;
 use super::request::mmds::{parse_get_mmds, parse_patch_mmds, parse_put_mmds};
 use super::request::net::{parse_patch_net, parse_put_net};
@@ -82,6 +83,14 @@ impl TryFrom<&Request> for ParsedRequest {
                 Ok(ParsedRequest::new_sync(VmmAction::GetFullVmConfig))
             }
             (Method::Get, "machine-config", None) => parse_get_machine_config(),
+            (Method::Get, "memory", None) => match path_tokens.next() {
+                Some("mappings") => parse_get_memory_mappings(),
+                None => parse_get_memory(),
+                _ => Err(RequestError::InvalidPathMethod(
+                    request_uri.to_string(),
+                    Method::Get,
+                )),
+            },
             (Method::Get, "mmds", None) => parse_get_mmds(),
             (Method::Get, _, Some(_)) => method_to_error(Method::Get),
             (Method::Put, "actions", Some(body)) => parse_put_actions(body),
@@ -172,6 +181,8 @@ impl ParsedRequest {
                 }
                 VmmData::BalloonStats(stats) => Self::success_response_with_data(stats),
                 VmmData::InstanceInformation(info) => Self::success_response_with_data(info),
+                VmmData::MemoryMappings(mappings) => Self::success_response_with_data(mappings),
+                VmmData::Memory(memory) => Self::success_response_with_data(memory),
                 VmmData::VmmVersion(version) => Self::success_response_with_data(
                     &serde_json::json!({ "firecracker_version": version.as_str() }),
                 ),
@@ -568,6 +579,12 @@ pub mod tests {
                 VmmData::InstanceInformation(info) => {
                     http_response(&serde_json::to_string(info).unwrap(), 200)
                 }
+                VmmData::MemoryMappings(mappings) => {
+                    http_response(&serde_json::to_string(mappings).unwrap(), 200)
+                }
+                VmmData::Memory(memory) => {
+                    http_response(&serde_json::to_string(memory).unwrap(), 200)
+                }
                 VmmData::VmmVersion(version) => http_response(
                     &serde_json::json!({ "firecracker_version": version.as_str() }).to_string(),
                     200,
@@ -589,6 +606,15 @@ pub mod tests {
         verify_ok_response_with(VmmData::MachineConfiguration(MachineConfig::default()));
         verify_ok_response_with(VmmData::MmdsValue(serde_json::from_str("{}").unwrap()));
         verify_ok_response_with(VmmData::InstanceInformation(InstanceInfo::default()));
+        verify_ok_response_with(VmmData::MemoryMappings(
+            vmm::vmm_config::instance_info::MemoryMappingsResponse { mappings: vec![] },
+        ));
+        verify_ok_response_with(VmmData::Memory(
+            vmm::vmm_config::instance_info::MemoryResponse {
+                resident: vec![],
+                empty: vec![],
+            },
+        ));
         verify_ok_response_with(VmmData::VmmVersion(String::default()));
 
         // Error.
@@ -662,6 +688,30 @@ pub mod tests {
         ParsedRequest::try_from(&req).unwrap();
     }
 
+    #[test]
+    fn test_try_from_get_memory_mappings() {
+        let (mut sender, receiver) = UnixStream::pair().unwrap();
+        let mut connection = HttpConnection::new(receiver);
+        sender
+            .write_all(http_request("GET", "/memory/mappings", None).as_bytes())
+            .unwrap();
+        connection.try_read().unwrap();
+        let req = connection.pop_parsed_request().unwrap();
+        ParsedRequest::try_from(&req).unwrap();
+    }
+
+    #[test]
+    fn test_try_from_get_memory() {
+        let (mut sender, receiver) = UnixStream::pair().unwrap();
+        let mut connection = HttpConnection::new(receiver);
+        sender
+            .write_all(http_request("GET", "/memory", None).as_bytes())
+            .unwrap();
+        connection.try_read().unwrap();
+        let req = connection.pop_parsed_request().unwrap();
+        ParsedRequest::try_from(&req).unwrap();
+    }
+
     #[test]
     fn test_try_from_get_version() {
         let (mut sender, receiver) = UnixStream::pair().unwrap();

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

@@ -0,0 +1,39 @@
+// Copyright 2025 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 super::super::parsed_request::{ParsedRequest, RequestError};
+
+pub(crate) fn parse_get_memory_mappings() -> Result<ParsedRequest, RequestError> {
+    METRICS.get_api_requests.instance_info_count.inc();
+    Ok(ParsedRequest::new_sync(VmmAction::GetMemoryMappings))
+}
+
+pub(crate) fn parse_get_memory() -> Result<ParsedRequest, RequestError> {
+    METRICS.get_api_requests.instance_info_count.inc();
+    Ok(ParsedRequest::new_sync(VmmAction::GetMemory))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::api_server::parsed_request::RequestAction;
+
+    #[test]
+    fn test_parse_get_memory_mappings_request() {
+        match parse_get_memory_mappings().unwrap().into_parts() {
+            (RequestAction::Sync(action), _) if *action == VmmAction::GetMemoryMappings => {}
+            _ => panic!("Test failed."),
+        }
+    }
+
+    #[test]
+    fn test_parse_get_memory_request() {
+        match parse_get_memory().unwrap().into_parts() {
+            (RequestAction::Sync(action), _) if *action == VmmAction::GetMemory => {}
+            _ => panic!("Test failed."),
+        }
+    }
+}

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

@@ -10,6 +10,7 @@ pub mod entropy;
 pub mod instance_info;
 pub mod logger;
 pub mod machine_configuration;
+pub mod memory;
 pub mod metrics;
 pub mod mmds;
 pub mod net;

src/firecracker/swagger/firecracker.yaml

@@ -618,6 +618,35 @@ paths:
           schema:
             $ref: "#/definitions/Error"
 
+  /memory/mappings:
+    get:
+      summary: Gets the memory mappings with skippable pages bitmap.
+      operationId: getMemoryMappings
+      responses:
+        200:
+          description: OK
+          schema:
+            $ref: "#/definitions/MemoryMappingsResponse"
+        default:
+          description: Internal server error
+          schema:
+            $ref: "#/definitions/Error"
+
+  /memory:
+    get:
+      summary: Gets the memory info (resident and empty pages).
+      description: Returns an object with resident and empty bitmaps. The resident bitmap marks all pages that are resident. The empty bitmap marks zero pages (subset of resident pages). This is checked at the pageSize of each region. All regions must have the same page size.
+      operationId: getMemory
+      responses:
+        200:
+          description: OK
+          schema:
+            $ref: "#/definitions/MemoryResponse"
+        default:
+          description: Internal server error
+          schema:
+            $ref: "#/definitions/Error"
+
   /version:
     get:
       summary: Gets the Firecracker version.
@@ -990,11 +1019,6 @@ definitions:
       vmm_version:
         description: MicroVM hypervisor build version.
         type: string
-      memory_regions:
-        type: array
-        description: The regions of the guest memory.
-        items:
-          $ref: "#/definitions/GuestMemoryRegionMapping"
 
   GuestMemoryRegionMapping:
     type: object
@@ -1017,6 +1041,38 @@ definitions:
         description: The page size in bytes.
         type: integer
 
+  MemoryMappingsResponse:
+    type: object
+    description: Response containing memory region mappings.
+    required:
+      - mappings
+    properties:
+      mappings:
+        type: array
+        description: The memory region mappings.
+        items:
+          $ref: "#/definitions/GuestMemoryRegionMapping"
+
+  MemoryResponse:
+    type: object
+    description: Response containing the memory info (resident and empty pages).
+    required:
+      - resident
+      - empty
+    properties:
+      resident:
+        type: array
+        description: The resident bitmap as a vector of u64 values. Each bit represents if the page is resident.
+        items:
+          type: integer
+          format: uint64
+      empty:
+        type: array
+        description: The empty bitmap as a vector of u64 values. Each bit represents if the page is zero (empty). This is a subset of the resident pages.
+        items:
+          type: integer
+          format: uint64
+
   Logger:
     type: object
     description:

src/vmm/src/rpc_interface.rs

@@ -25,8 +25,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};
-use crate::vmm_config::instance_info::InstanceInfo;
-use crate::vmm_config::machine_config::{MachineConfig, MachineConfigUpdate, VmConfigError};
+use crate::vmm_config::instance_info::{InstanceInfo, MemoryMappingsResponse, MemoryResponse};
+use crate::vmm_config::machine_config::{MachineConfig, MachineConfigError, MachineConfigUpdate};
 use crate::vmm_config::metrics::{MetricsConfig, MetricsConfigError};
 use crate::vmm_config::mmds::{MmdsConfig, MmdsConfigError};
 use crate::vmm_config::net::{
@@ -65,6 +65,10 @@ pub enum VmmAction {
     GetVmMachineConfig,
     /// Get microVM instance information.
     GetVmInstanceInfo,
+    /// Get memory mappings with skippable pages bitmap.
+    GetMemoryMappings,
+    /// Get memory info (resident and empty pages).
+    GetMemory,
     /// Get microVM version.
     GetVmmVersion,
     /// Flush the metrics. This action can only be called after the logger has been configured.
@@ -189,6 +193,10 @@ pub enum VmmData {
     MmdsValue(serde_json::Value),
     /// The microVM instance information.
     InstanceInformation(InstanceInfo),
+    /// Memory mappings with skippable pages bitmap.
+    MemoryMappings(MemoryMappingsResponse),
+    /// Memory info (resident and empty pages).
+    Memory(MemoryResponse),
     /// The microVM version.
     VmmVersion(String),
 }
@@ -419,6 +427,7 @@ impl<'a> PrebootApiController<'a> {
                 &self.vm_resources.vm_config,
             ))),
             GetVmInstanceInfo => Ok(VmmData::InstanceInformation(self.instance_info.clone())),
+            GetMemoryMappings | GetMemory => Err(VmmActionError::OperationNotSupportedPreBoot),
             GetVmmVersion => Ok(VmmData::VmmVersion(self.instance_info.vmm_version.clone())),
             InsertBlockDevice(config) => self.insert_block_device(config),
             InsertNetworkDevice(config) => self.insert_net_device(config),
@@ -648,14 +657,28 @@ impl RuntimeApiController {
             ))),
             GetVmInstanceInfo => {
                 let locked_vmm = self.vmm.lock().expect("Poisoned lock");
-
-                let mut instance_info = locked_vmm.instance_info();
-
-                instance_info.memory_regions =
-                    Some(locked_vmm.guest_memory_mappings(&VmInfo::from(&self.vm_resources)));
-
+                let instance_info = locked_vmm.instance_info();
                 Ok(VmmData::InstanceInformation(instance_info))
             }
+            GetMemoryMappings => {
+                let locked_vmm = self.vmm.lock().expect("Poisoned lock");
+                let mappings = locked_vmm
+                    .vm
+                    .guest_memory_mappings(&VmInfo::from(&self.vm_resources));
+
+                Ok(VmmData::MemoryMappings(MemoryMappingsResponse { mappings }))
+            }
+            GetMemory => {
+                let locked_vmm = self.vmm.lock().expect("Poisoned lock");
+                let (resident_bitmap, empty_bitmap) = locked_vmm
+                    .vm
+                    .get_memory_info(&VmInfo::from(&self.vm_resources))
+                    .map_err(|e| VmmActionError::InternalVmm(VmmError::Vm(e)))?;
+                Ok(VmmData::Memory(MemoryResponse {
+                    resident: resident_bitmap,
+                    empty: empty_bitmap,
+                }))
+            }
             GetVmmVersion => Ok(VmmData::VmmVersion(
                 self.vmm.lock().expect("Poisoned lock").version(),
             )),

src/vmm/src/vmm_config/instance_info.rs

@@ -51,3 +51,20 @@ pub struct InstanceInfo {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub memory_regions: Option<Vec<GuestMemoryRegionMapping>>,
 }
+
+/// Response structure for the memory mappings endpoint.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
+pub struct MemoryMappingsResponse {
+    /// The memory region mappings.
+    pub mappings: Vec<GuestMemoryRegionMapping>,
+}
+
+/// Response structure for the memory endpoint.
+#[derive(Clone, Debug, PartialEq, Eq, Serialize)]
+pub struct MemoryResponse {
+    /// The resident bitmap as a vector of u64 values. Each bit represents if the page is resident.
+    pub resident: Vec<u64>,
+    /// The empty bitmap as a vector of u64 values. Each bit represents if the page is zero (empty).
+    /// This is a subset of the resident pages.
+    pub empty: Vec<u64>,
+}