feat: complete KVM pre-fault stats

CHANGELOG.md

@@ -6,6 +6,16 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.15.1-patch-v2]
+
+### Added
+
+- Release the existing paused-only `PUT /vm/pre-fault-memory` API from PR #18.
+  On x86_64 with `KVM_CAP_PRE_FAULT_MEMORY`, it distributes validated,
+  page-aligned guest-physical ranges across the available vCPUs using
+  `KVM_PRE_FAULT_MEMORY`; aarch64 remains unsupported. This release does not
+  change startup, restore behavior, or the snapshot serialization/data format.
+
 ## [1.15.1]
 
 ### Added

src/cpu-template-helper/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "cpu-template-helper"
-version = "1.15.1-patch-v1"
+version = "1.15.1-patch-v2"
 authors = ["Amazon Firecracker team <firecracker-devel@amazon.com>"]
 edition = "2024"
 license = "Apache-2.0"

src/firecracker/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "firecracker"
-version = "1.15.1-patch-v1"
+version = "1.15.1-patch-v2"
 authors = ["Amazon Firecracker team <firecracker-devel@amazon.com>"]
 edition = "2024"
 build = "build.rs"

src/firecracker/src/api_server/parsed_request.rs

@@ -89,6 +89,9 @@ impl TryFrom<&Request> for ParsedRequest {
                 Some("dirty-memory-ranges") => {
                     Ok(ParsedRequest::new_sync(VmmAction::GetDirtyMemoryRanges))
                 }
+                Some("resident-memory-ranges") => {
+                    Ok(ParsedRequest::new_sync(VmmAction::GetResidentMemoryRanges))
+                }
                 Some("guest-memory-regions") => {
                     Ok(ParsedRequest::new_sync(VmmAction::GetGuestMemoryRegions))
                 }
@@ -214,7 +217,9 @@ impl ParsedRequest {
                 ),
                 VmmData::FullVmConfig(config) => Self::success_response_with_data(config),
                 VmmData::DirtyMemoryRanges(ranges) => Self::success_response_with_data(ranges),
+                VmmData::ResidentMemoryRanges(ranges) => Self::success_response_with_data(ranges),
                 VmmData::GuestMemoryRegions(regions) => Self::success_response_with_data(regions),
+                VmmData::PreFaultMemoryStats(stats) => Self::success_response_with_data(stats),
             },
             Err(vmm_action_error) => {
                 let mut response = match vmm_action_error {
@@ -367,7 +372,9 @@ pub mod tests {
     use vmm::vmm_config::balloon::{BalloonDeviceConfig, BalloonStats};
     use vmm::vmm_config::instance_info::InstanceInfo;
     use vmm::vmm_config::machine_config::MachineConfig;
-    use vmm::vstate::memory::{DirtyMemoryRange, DirtyMemoryRanges};
+    use vmm::vstate::memory::{
+        DirtyMemoryRange, DirtyMemoryRanges, ResidentMemoryRange, ResidentMemoryRanges,
+    };
 
     use super::*;
 
@@ -690,9 +697,15 @@ pub mod tests {
                 VmmData::DirtyMemoryRanges(ranges) => {
                     http_response(&serde_json::to_string(ranges).unwrap(), 200)
                 }
+                VmmData::ResidentMemoryRanges(ranges) => {
+                    http_response(&serde_json::to_string(ranges).unwrap(), 200)
+                }
                 VmmData::GuestMemoryRegions(regions) => {
                     http_response(&serde_json::to_string(regions).unwrap(), 200)
                 }
+                VmmData::PreFaultMemoryStats(stats) => {
+                    http_response(&serde_json::to_string(stats).unwrap(), 200)
+                }
                 VmmData::MachineConfiguration(cfg) => {
                     http_response(&serde_json::to_string(cfg).unwrap(), 200)
                 }
@@ -732,13 +745,23 @@ pub mod tests {
                 length: 4096,
             }],
         }));
+        verify_ok_response_with(VmmData::ResidentMemoryRanges(ResidentMemoryRanges {
+            page_size: 4096,
+            memory_size: 8192,
+            ranges: vec![ResidentMemoryRange {
+                base_host_virt_addr: 0x7f0000000000,
+                image_offset: 0,
+                length: 4096,
+            }],
+        }));
         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::VmmVersion(String::default()));
         #[allow(deprecated)]
         verify_ok_response_with(VmmData::GuestMemoryRegions(vec![GuestRegionUffdMapping {
             base_host_virt_addr: 0x7f0000000000,
+            guest_phys_addr: 0,
             size: 0x10000000,
             offset: 0,
             page_size: 4096,
@@ -872,6 +895,22 @@ pub mod tests {
         );
     }
 
+    #[test]
+    fn test_try_from_get_resident_memory_ranges() {
+        let (mut sender, receiver) = UnixStream::pair().unwrap();
+        let mut connection = HttpConnection::new(receiver);
+        sender
+            .write_all(http_request("GET", "/vm/resident-memory-ranges", None).as_bytes())
+            .unwrap();
+        connection.try_read().unwrap();
+        let req = connection.pop_parsed_request().unwrap();
+        let parsed = ParsedRequest::try_from(&req).unwrap();
+        assert_eq!(
+            vmm_action_from_request(parsed),
+            VmmAction::GetResidentMemoryRanges
+        );
+    }
+
     #[test]
     fn test_try_from_put_actions() {
         let (mut sender, receiver) = UnixStream::pair().unwrap();

src/firecracker/swagger/firecracker.yaml

@@ -5,7 +5,7 @@ info:
     The API is accessible through HTTP calls on specific URLs
     carrying JSON modeled data.
     The transport medium is a Unix Domain Socket.
-  version: 1.15.1-patch-v1
+  version: 1.15.1-patch-v2
   termsOfService: ""
   contact:
     email: "firecracker-maintainers@amazon.com"
@@ -843,8 +843,10 @@ paths:
           schema:
             $ref: "#/definitions/PreFaultMemoryRequest"
       responses:
-        204:
+        200:
           description: Pre-fault completed successfully.
+          schema:
+            $ref: "#/definitions/PreFaultMemoryStats"
         400:
           description: Invalid request, unsupported host capability, or VM state.
           schema:
@@ -906,6 +908,29 @@ paths:
           schema:
             $ref: "#/definitions/Error"
 
+  /vm/resident-memory-ranges:
+    get:
+      summary: Returns resident guest memory ranges.
+      description:
+        Returns host-resident guest memory ranges in the same contiguous image
+        layout used by Firecracker memory snapshots. Residency is sampled with
+        mincore(2); this API neither reads nor changes KVM dirty-page state.
+        Post-boot only.
+      operationId: getResidentMemoryRanges
+      responses:
+        200:
+          description: Resident guest memory ranges
+          schema:
+            $ref: "#/definitions/ResidentMemoryRanges"
+        400:
+          description: VM is not in a valid state for this operation
+          schema:
+            $ref: "#/definitions/Error"
+        default:
+          description: Internal server error
+          schema:
+            $ref: "#/definitions/Error"
+
   /vm/config:
     get:
       summary: Gets the full VM configuration.
@@ -1357,11 +1382,12 @@ definitions:
     type: object
     description:
       Describes a guest memory region mapping, providing the host virtual address,
-      region size, offset within a contiguous snapshot layout, and page size. Used
-      by external processes to read guest memory directly from the Firecracker
-      process address space via process_vm_readv().
+      guest physical address, region size, offset within a contiguous snapshot
+      layout, and page size. Used by external processes to read guest memory
+      directly from the Firecracker process address space via process_vm_readv().
     required:
       - base_host_virt_addr
+      - guest_phys_addr
       - size
       - offset
       - page_size
@@ -1370,6 +1396,13 @@ definitions:
         type: integer
         format: int64
         description: Base host virtual address of the guest memory region.
+      guest_phys_addr:
+        type: integer
+        format: int64
+        description:
+          Guest physical address at which this region begins. Unlike offset,
+          this preserves holes in the guest physical address space and is used
+          to translate a host virtual address in the region back to GPAs.
       size:
         type: integer
         format: int64
@@ -1423,6 +1456,77 @@ definitions:
         items:
           $ref: "#/definitions/PreFaultMemoryRange"
 
+  PreFaultMemoryWorkerStats:
+    type: object
+    description: Completion statistics for work assigned to one vCPU worker.
+    additionalProperties: false
+    required:
+      - vcpu_id
+      - range_count
+      - requested_bytes
+      - completed_bytes
+      - remaining_bytes
+      - ioctl_count
+      - wall_time_us
+    properties:
+      vcpu_id:
+        type: integer
+        format: int32
+      range_count:
+        type: integer
+        format: int64
+      requested_bytes:
+        type: integer
+        format: int64
+      completed_bytes:
+        type: integer
+        format: int64
+      remaining_bytes:
+        type: integer
+        format: int64
+      ioctl_count:
+        type: integer
+        format: int64
+      wall_time_us:
+        type: integer
+        format: int64
+
+  PreFaultMemoryStats:
+    type: object
+    description: Completion statistics for a paused guest-memory pre-fault request.
+    additionalProperties: false
+    required:
+      - range_count
+      - requested_bytes
+      - completed_bytes
+      - remaining_bytes
+      - ioctl_count
+      - wall_time_us
+      - workers
+    properties:
+      range_count:
+        type: integer
+        format: int64
+      requested_bytes:
+        type: integer
+        format: int64
+      completed_bytes:
+        type: integer
+        format: int64
+      remaining_bytes:
+        type: integer
+        format: int64
+      ioctl_count:
+        type: integer
+        format: int64
+      wall_time_us:
+        type: integer
+        format: int64
+      workers:
+        type: array
+        items:
+          $ref: "#/definitions/PreFaultMemoryWorkerStats"
+
   DirtyMemoryRange:
     type: object
     description:
@@ -1470,6 +1574,53 @@ definitions:
         items:
           $ref: "#/definitions/DirtyMemoryRange"
 
+  ResidentMemoryRange:
+    type: object
+    description:
+      Describes a contiguous host-resident guest-memory range in the
+      contiguous snapshot image layout.
+    required:
+      - base_host_virt_addr
+      - image_offset
+      - length
+    properties:
+      base_host_virt_addr:
+        type: integer
+        format: int64
+        description: Base host virtual address of the resident range.
+      image_offset:
+        type: integer
+        format: int64
+        description:
+          Cumulative byte offset of this range in the contiguous memory snapshot
+          image layout. This is not a Guest Physical Address.
+      length:
+        type: integer
+        format: int64
+        description: Resident range length in bytes.
+
+  ResidentMemoryRanges:
+    type: object
+    description:
+      Resident memory ranges for a VM, sampled with mincore(2), using the same
+      contiguous memory image layout as snapshot files.
+    required:
+      - page_size
+      - memory_size
+      - ranges
+    properties:
+      page_size:
+        type: integer
+        description: Page size used by mincore(2).
+      memory_size:
+        type: integer
+        format: int64
+        description: Total byte size of the contiguous memory snapshot image.
+      ranges:
+        type: array
+        items:
+          $ref: "#/definitions/ResidentMemoryRange"
+
   FullVmConfiguration:
     type: object
     properties: