api: implement API for dirty memory

Implement API /memory/dirty which returns a bitmap tracking dirty guest
memory. The bitmap is structured as a vector of u64, so its length is:
total_number_of_pages.div_ceil(64).

Pages are ordered in the order of pages as reported by /memory/mappings.

Signed-off-by: Babis Chalios <[email protected]>

Author: bchalios

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

@@ -31,6 +31,9 @@
             {
                 "syscall": "mincore"
             },
+            {
+                "syscall": "pread64"
+            },
             {
                 "syscall": "writev",
                 "comment": "Used by the VirtIO net device to write to tap"

src/firecracker/src/api_server/parsed_request.rs

@@ -200,6 +200,7 @@ impl ParsedRequest {
                 VmmData::FullVmConfig(config) => Self::success_response_with_data(config),
                 VmmData::MemoryMappings(mappings) => Self::success_response_with_data(mappings),
                 VmmData::Memory(meminfo) => Self::success_response_with_data(meminfo),
+                VmmData::MemoryDirty(dirty) => Self::success_response_with_data(dirty),
             },
             Err(vmm_action_error) => {
                 let mut response = match vmm_action_error {
@@ -620,6 +621,9 @@ pub mod tests {
                 VmmData::Memory(meminfo) => {
                     http_response(&serde_json::to_string(meminfo).unwrap(), 200)
                 }
+                VmmData::MemoryDirty(dirty) => {
+                    http_response(&serde_json::to_string(dirty).unwrap(), 200)
+                }
             };
             let response = ParsedRequest::convert_to_response(&data);
             response.write_all(&mut buf).unwrap();

src/firecracker/src/api_server/request/memory_info.rs

@@ -9,6 +9,7 @@ where
 {
     match path_tokens.next() {
         Some("mappings") => Ok(ParsedRequest::new_sync(VmmAction::GetMemoryMappings)),
+        Some("dirty") => Ok(ParsedRequest::new_sync(VmmAction::GetMemoryDirty)),
         Some(unknown_path) => Err(RequestError::Generic(
             StatusCode::BadRequest,
             format!("Unrecognized GET request path `{unknown_path}`"),

src/vmm/src/lib.rs

@@ -256,6 +256,8 @@ pub enum VmmError {
     Block(#[from] BlockError),
     /// Balloon: {0}
     Balloon(#[from] BalloonError),
+    /// Pagemap error: {0}
+    Pagemap(#[from] utils::pagemap::PagemapError),
     /// Failed to create memory hotplug device: {0}
     VirtioMem(#[from] VirtioMemError),
 }
@@ -774,6 +776,49 @@ impl Vmm {
 
         Ok((resident, empty))
     }
+
+    /// Get dirty pages bitmap for guest memory
+    pub fn get_dirty_memory(&self, page_size: usize) -> Result<Vec<u64>, VmmError> {
+        let pagemap = utils::pagemap::PagemapReader::new(page_size)?;
+        let mut dirty_bitmap = vec![];
+
+        for mem_slot in self
+            .vm
+            .guest_memory()
+            .iter()
+            .flat_map(|region| region.plugged_slots())
+        {
+            let base_addr = mem_slot.slice.ptr_guard_mut().as_ptr() as usize;
+            let len = mem_slot.slice.len();
+            let nr_pages = len / page_size;
+
+            // Use mincore_bitmap to get resident pages at guest page size granularity
+            let resident_bitmap = vstate::vm::mincore_bitmap(base_addr as *mut u8, len, page_size)?;
+
+            // TODO: if we don't support UFFD/async WP, we can completely skip this bit. For the
+            // time being, we always do.
+            //
+            // Build dirty bitmap: check pagemap only for pages that mincore reports resident.
+            // This way we reduce the amount of times we read out of /proc/<pid>/pagemap.
+            let mut slot_bitmap = vec![0u64; nr_pages.div_ceil(64)];
+            for page_idx in 0..nr_pages {
+                // Check if page is resident in the bitmap.
+                // TODO: These operations (add to bitmap, check for presence, etc.) merit their own
+                // implementation, somewhere within a bitmap type).
+                let is_resident = (resident_bitmap[page_idx / 64] & (1u64 << (page_idx % 64))) != 0;
+                if is_resident {
+                    let virt_addr = base_addr + (page_idx * page_size);
+                    if pagemap.is_page_dirty(virt_addr)? {
+                        slot_bitmap[page_idx / 64] |= 1u64 << (page_idx % 64);
+                    }
+                }
+            }
+
+            dirty_bitmap.extend_from_slice(&slot_bitmap);
+        }
+
+        Ok(dirty_bitmap)
+    }
 }
 
 /// Process the content of the MPIDR_EL1 register in order to be able to pass it to KVM

src/vmm/src/rpc_interface.rs

@@ -28,9 +28,9 @@ 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::instance_info::{InstanceInfo, VmState};
 use crate::vmm_config::machine_config::{MachineConfig, MachineConfigError, MachineConfigUpdate};
-use crate::vmm_config::meminfo::{MemoryMapingsResponse, MemoryResponse};
+use crate::vmm_config::meminfo::{MemoryDirty, MemoryMapingsResponse, MemoryResponse};
 use crate::vmm_config::memory_hotplug::{
     MemoryHotplugConfig, MemoryHotplugConfigError, MemoryHotplugSizeUpdate,
 };
@@ -151,6 +151,8 @@ pub enum VmmAction {
     GetMemoryMappings,
     /// Get guest memory resident and empty pages information
     GetMemory,
+    /// Get guest memory dirty pages information
+    GetMemoryDirty,
 }
 
 /// Wrapper for all errors associated with VMM actions.
@@ -202,6 +204,8 @@ pub enum VmmActionError {
     OperationNotSupportedPostBoot,
     /// The requested operation is not supported before starting the microVM.
     OperationNotSupportedPreBoot,
+    /// The requested operation is not supported while the microVM is running.
+    OperationNotSupportedWhileRunning,
     /// Start microvm error: {0}
     StartMicrovm(#[from] StartMicrovmError),
     /// Vsock config error: {0}
@@ -237,6 +241,8 @@ pub enum VmmData {
     MemoryMappings(MemoryMapingsResponse),
     /// The guest memory resident and empty pages information
     Memory(MemoryResponse),
+    /// The guest memory dirty pages information
+    MemoryDirty(MemoryDirty),
 }
 
 /// Trait used for deduplicating the MMDS request handling across the two ApiControllers.
@@ -506,7 +512,8 @@ impl<'a> PrebootApiController<'a> {
             | GetFreePageHintingStatus
             | StopFreePageHinting
             | GetMemoryMappings
-            | GetMemory => Err(VmmActionError::OperationNotSupportedPreBoot),
+            | GetMemory
+            | GetMemoryDirty => Err(VmmActionError::OperationNotSupportedPreBoot),
             #[cfg(target_arch = "x86_64")]
             SendCtrlAltDel => Err(VmmActionError::OperationNotSupportedPreBoot),
         }
@@ -784,6 +791,7 @@ impl RuntimeApiController {
                 .map_err(VmmActionError::MemoryHotplugUpdate),
             GetMemoryMappings => self.get_guest_memory_mappings(),
             GetMemory => self.get_guest_memory_info(),
+            GetMemoryDirty => self.get_dirty_memory_info(),
             // Operations not allowed post-boot.
             ConfigureBootSource(_)
             | ConfigureLogger(_)
@@ -966,6 +974,20 @@ impl RuntimeApiController {
         let (resident, empty) = vmm.guest_memory_info(page_size)?;
         Ok(VmmData::Memory(MemoryResponse { resident, empty }))
     }
+
+    /// Get dirty pages information for guest memory
+    fn get_dirty_memory_info(&self) -> Result<VmmData, VmmActionError> {
+        let vmm = self.vmm.lock().expect("Poisoned lock");
+        
+        // Check if VM is paused
+        if vmm.instance_info.state != VmState::Paused {
+            return Err(VmmActionError::OperationNotSupportedWhileRunning);
+        }
+        
+        let page_size = self.vm_resources.machine_config.huge_pages.page_size();
+        let bitmap = vmm.get_dirty_memory(page_size)?;
+        Ok(VmmData::MemoryDirty(MemoryDirty { bitmap }))
+    }
 }
 
 #[cfg(test)]

src/vmm/src/utils/mod.rs

@@ -9,6 +9,8 @@ pub mod net;
 pub mod signal;
 /// Module with state machine
 pub mod sm;
+/// Module with pagemap utilities
+pub mod pagemap;
 
 use std::fs::{File, OpenOptions};
 use std::num::Wrapping;

src/vmm/src/utils/pagemap.rs

@@ -0,0 +1,115 @@
+//! Utilities for reading /proc/self/pagemap to track dirty pages.
+
+#![allow(clippy::cast_possible_wrap)]
+
+use std::fs::File;
+use std::os::unix::io::AsRawFd;
+
+use crate::arch::host_page_size;
+
+const PAGEMAP_ENTRY_SIZE: usize = 8;
+
+/// Errors related to pagemap operations
+#[derive(Debug, thiserror::Error, displaydoc::Display)]
+pub enum PagemapError {
+    /// Failed to open /proc/self/pagemap: {0}
+    OpenPagemap(#[source] std::io::Error),
+    /// Failed to read pagemap entry: {0}
+    ReadEntry(#[source] std::io::Error),
+    /// Failed to open /proc/self/clear_refs: {0}
+    OpenClearRefs(#[source] std::io::Error),
+    /// Failed to clear soft-dirty bits: {0}
+    ClearSoftDirty(#[source] std::io::Error),
+}
+
+/// Represents a single entry in /proc/pid/pagemap.
+///
+/// Each virtual page has an 8-byte entry with the following layout:
+/// - Bits 0-54:  Page frame number (PFN) if present
+/// - Bit 55:     Page is soft-dirty (written to since last clear)
+/// - Bit 56:     Page is exclusively mapped
+/// - Bit 57:     Page is write-protected via userfaultfd
+/// - Bit 58:     Unused
+/// - Bit 59-60:  Unused
+/// - Bit 61:     Page is file-page or shared-anon
+/// - Bit 62:     Page is swapped
+/// - Bit 63:     Page is present in RAM
+#[derive(Debug, Clone, Copy)]
+pub struct PagemapEntry {
+    raw: u64,
+}
+
+impl PagemapEntry {
+    /// Create a PagemapEntry from bytes (little-endian)
+    pub fn from_bytes(bytes: [u8; 8]) -> Self {
+        Self {
+            raw: u64::from_ne_bytes(bytes),
+        }
+    }
+
+    /// Check if page is write-protected via userfaultfd
+    pub fn is_write_protected(&self) -> bool {
+        (self.raw & (1u64 << 57)) != 0
+    }
+
+    /// Check if page is present in RAM (bit 63)
+    pub fn is_present(&self) -> bool {
+        (self.raw & (1u64 << 63)) != 0
+    }
+}
+
+/// Reader for /proc/self/pagemap
+#[derive(Debug)]
+pub struct PagemapReader {
+    pagemap_fd: File,
+}
+
+impl PagemapReader {
+    /// Create a new PagemapReader
+    pub fn new(_page_size: usize) -> Result<Self, PagemapError> {
+        let pagemap_fd = File::open("/proc/self/pagemap").map_err(PagemapError::OpenPagemap)?;
+
+        Ok(Self { pagemap_fd })
+    }
+
+    /// Check if a single page is dirty (write-protected bit cleared).
+    ///
+    /// Checks the first host page (4K) of the guest page at the given address.
+    /// For huge pages, all host pages within the huge page typically have the same
+    /// dirty status, so sampling the first is sufficient.
+    ///
+    /// # Arguments
+    /// * `virt_addr` - Virtual address of the page to check
+    ///
+    /// # Returns
+    /// True if the page is present and write-protected bit is cleared (dirty).
+    pub fn is_page_dirty(&self, virt_addr: usize) -> Result<bool, PagemapError> {
+        // Pagemap always uses host (4K) page size
+        let host_page_size = host_page_size();
+
+        // Calculate offset for this virtual page (using host page size)
+        let host_vpn = virt_addr / host_page_size;
+        let offset = (host_vpn * PAGEMAP_ENTRY_SIZE) as i64;
+
+        let mut entry_bytes = [0u8; 8];
+
+        // SAFETY: pread is safe as long as the fd is valid and the buffer is properly sized
+        let ret = unsafe {
+            libc::pread(
+                self.pagemap_fd.as_raw_fd(),
+                entry_bytes.as_mut_ptr().cast(),
+                PAGEMAP_ENTRY_SIZE,
+                offset,
+            )
+        };
+
+        if ret != PAGEMAP_ENTRY_SIZE as isize {
+            return Err(PagemapError::ReadEntry(std::io::Error::last_os_error()));
+        }
+
+        let entry = PagemapEntry::from_bytes(entry_bytes);
+
+        // Page must be present and the write_protected bit cleared (indicating it was written to)
+        Ok(entry.is_present() && !entry.is_write_protected())
+    }
+}

src/vmm/src/vmm_config/meminfo.rs

@@ -19,3 +19,11 @@ pub struct MemoryResponse {
     /// Each bit represents whether a page is empty (all 0s).
     pub empty: Vec<u64>,
 }
+
+/// Information about dirty guest memory pages
+#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize)]
+pub struct MemoryDirty {
+    /// Bitmap for dirty pages. The bitmap is encoded as a vector of u64 values.
+    /// Each bit represents whether a page has been written since the last snapshot.
+    pub bitmap: Vec<u64>,
+}