feat(api): POST /uffd/wp endpoint for snapshot-side WP

Add a Firecracker API endpoint that lets an external tool
(forkd-controller for the v0.4 live-fork path) arm UFFD-WP on
guest memory. FC creates the userfaultfd, issues UFFDIO_REGISTER
with WRITE_PROTECT mode against every guest_memory region, then
connects to the caller-supplied UDS and ships the fd via
SCM_RIGHTS along with a JSON descriptor of the regions.

Why FC has to be the one creating the uffd: UFFDIO_REGISTER can
only register VMAs in the same process that called
userfaultfd(2). KVM runs inside FC's process; guest writes go
through FC's EPT/VMA. A controller-side uffd registered against
its own mmap would never see KVM writes. Modeling on FC's
existing restore-side Uffd backend (which sends the fd from FC
to the page-fault handler), this new endpoint flips the direction
for the snapshot side.

Request shape:
  PUT /uffd/wp
  {"socket": "/run/forkd-controller/.../wp.sock"}

  -> 204 No Content
  -> SCM_RIGHTS message on the socket carrying the uffd fd plus
     a JSON array of GuestRegionUffdMapping describing what was
     registered (matches the existing restore-side handshake).

Patch covers five files because SnapshotType's pre-existing
exhaustive matches force a touch in each:
  - src/vmm/src/vmm_config/wp_uffd.rs  (new)  - request params
  - src/vmm/src/persist.rs                     - setup_wp_uffd + error type
  - src/vmm/src/rpc_interface.rs               - VmmAction variant + dispatch
  - src/firecracker/src/api_server/mod.rs      - metric branch
  - src/firecracker/src/api_server/request/wp_uffd.rs (new) - route parser
  - src/firecracker/src/api_server/parsed_request.rs - routing
  - src/firecracker/src/api_server/request/mod.rs   - mod declaration
  - src/vmm/Cargo.toml                         - userfaultfd "linux5_7" feature

End-to-end smoke test (via a memfd-backed restore so the WP target
VMA is shmem, not ext4):
  /snapshot/load -> 204
  FC mmap: /memfd:forkd-wp-test (deleted), 512 MiB, MAP_SHARED
  /uffd/wp -> 204
  Receiver got: 1 region (size=512MiB, page=4KiB), fd -> anon_inode:[userfaultfd]

Note: UFFD_WP requires shmem-backed (or anon) VMAs, not ext4
file-backed. Hitting this endpoint against a snapshot restored
with backend_type=File/backend_path=<ext4 file> returns
EINVAL on UFFDIO_REGISTER — the kernel correctly refuses to WP
a file-backed VMA. forkd-controller's v0.4 path goes through
memfd (Phase 5b: MemoryBackend::MemfdShared), so this is fine
for the intended caller.

Author: WaylandYang

src/firecracker/src/api_server/mod.rs

@@ -166,6 +166,12 @@ impl ApiServer {
             VmmAction::LoadSnapshot(_) => {
                 Some((&METRICS.latencies_us.load_snapshot, "load snapshot"))
             }
+            VmmAction::SetupWpUffd(_) => Some((
+                // Reuse full-snapshot bucket — setup is one syscall + send,
+                // doesn't warrant its own metric for v0.4 experimental.
+                &METRICS.latencies_us.full_create_snapshot,
+                "setup wp uffd",
+            )),
             VmmAction::Pause => Some((&METRICS.latencies_us.pause_vm, "pause vm")),
             VmmAction::Resume => Some((&METRICS.latencies_us.resume_vm, "resume vm")),
             _ => None,

src/firecracker/src/api_server/parsed_request.rs

@@ -25,6 +25,7 @@ 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};
 use super::request::snapshot::{parse_patch_vm_state, parse_put_snapshot};
+use super::request::wp_uffd::parse_put_uffd;
 use super::request::version::parse_get_version;
 use super::request::vsock::parse_put_vsock;
 
@@ -97,6 +98,7 @@ impl TryFrom<&Request> for ParsedRequest {
                 parse_put_net(body, path_tokens.next())
             }
             (Method::Put, "snapshot", Some(body)) => parse_put_snapshot(body, path_tokens.next()),
+            (Method::Put, "uffd", Some(body)) => parse_put_uffd(body, path_tokens.next()),
             (Method::Put, "vsock", Some(body)) => parse_put_vsock(body),
             (Method::Put, "entropy", Some(body)) => parse_put_entropy(body),
             (Method::Put, _, None) => method_to_error(Method::Put),

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

@@ -14,6 +14,7 @@ pub mod metrics;
 pub mod mmds;
 pub mod net;
 pub mod snapshot;
+pub mod wp_uffd;
 pub mod version;
 pub mod vsock;
 pub use micro_http::{Body, Method, StatusCode};

src/vmm/Cargo.toml

@@ -36,7 +36,7 @@ serde_json = "1.0.140"
 slab = "0.4.7"
 thiserror = "2.0.12"
 timerfd = "1.5.0"
-userfaultfd = "0.8.1"
+userfaultfd = { version = "0.8.1", features = ["linux5_7"] }
 utils = { path = "../utils" }
 vhost = { version = "0.13.0", features = ["vhost-user-frontend"] }
 vm-allocator = "0.1.0"

src/vmm/src/persist.rs

@@ -37,7 +37,7 @@ use crate::vmm_config::machine_config::{HugePageConfig, MachineConfigError, Mach
 use crate::vmm_config::snapshot::{CreateSnapshotParams, LoadSnapshotParams, MemBackendType, SnapshotType};
 use crate::vstate::kvm::KvmState;
 use crate::vstate::memory;
-use crate::vstate::memory::{GuestMemoryState, GuestRegionMmap, MemoryError};
+use crate::vstate::memory::{GuestMemory, GuestMemoryRegion, GuestMemoryState, GuestRegionMmap, MemoryError};
 use crate::vstate::vcpu::{VcpuSendEventError, VcpuState};
 use crate::vstate::vm::VmState;
 use crate::{EventManager, Vmm, vstate};
@@ -485,6 +485,68 @@ pub enum GuestMemoryFromUffdError {
     Send(#[from] vmm_sys_util::errno::Error),
 }
 
+/// Error from [`setup_wp_uffd`].
+#[derive(Debug, thiserror::Error, displaydoc::Display)]
+pub enum SetupWpUffdError {
+    /// Failed to create userfaultfd: {0}
+    Create(userfaultfd::Error),
+    /// Failed to register guest memory region with userfaultfd: {0}
+    Register(userfaultfd::Error),
+    /// Failed to connect to listener UDS: {0}
+    Connect(#[from] std::io::Error),
+    /// Failed to send file descriptor: {0}
+    Send(#[from] vmm_sys_util::errno::Error),
+    /// Failed to serialize region descriptors: {0}
+    Serialize(#[from] serde_json::Error),
+}
+
+/// Set up a snapshot-side WP userfaultfd over the running VM's guest
+/// memory, then hand the fd to the listener at `socket_path` via
+/// SCM_RIGHTS.
+///
+/// Counterpart to [`guest_memory_from_uffd`] (the restore-side UFFD
+/// path): same handshake, but register mode is WP instead of MISSING,
+/// and we don't allocate new guest memory — we register over what FC
+/// is already running.
+pub fn setup_wp_uffd(
+    vmm: &crate::Vmm,
+    socket_path: &std::path::Path,
+) -> Result<(), SetupWpUffdError> {
+    use userfaultfd::{FeatureFlags, RegisterMode, UffdBuilder};
+
+    let uffd = UffdBuilder::new()
+        .require_features(FeatureFlags::PAGEFAULT_FLAG_WP)
+        .close_on_exec(true)
+        .non_blocking(true)
+        .user_mode_only(false)
+        .create()
+        .map_err(SetupWpUffdError::Create)?;
+
+    let guest_memory = vmm.vm.guest_memory();
+    let mut backend_mappings: Vec<GuestRegionUffdMapping> = Vec::new();
+    let mut offset = 0u64;
+    for region in guest_memory.iter() {
+        let addr = region.as_ptr() as *mut libc::c_void;
+        let size = region.size();
+        uffd.register_with_mode(addr, size, RegisterMode::WRITE_PROTECT)
+            .map_err(SetupWpUffdError::Register)?;
+        #[allow(deprecated)]
+        backend_mappings.push(GuestRegionUffdMapping {
+            base_host_virt_addr: region.as_ptr() as u64,
+            size,
+            offset,
+            page_size: 4096,
+            page_size_kib: 4096,
+        });
+        offset += size as u64;
+    }
+
+    let mappings_json = serde_json::to_string(&backend_mappings)?;
+    let socket = UnixStream::connect(socket_path)?;
+    socket.send_with_fd(mappings_json.as_bytes(), uffd.as_raw_fd())?;
+    Ok(())
+}
+
 fn guest_memory_from_uffd(
     mem_uds_path: &Path,
     mem_state: &GuestMemoryState,

src/vmm/src/rpc_interface.rs

@@ -34,6 +34,7 @@ use crate::vmm_config::net::{
     NetworkInterfaceConfig, NetworkInterfaceError, NetworkInterfaceUpdateConfig,
 };
 use crate::vmm_config::snapshot::{CreateSnapshotParams, LoadSnapshotParams, SnapshotType};
+use crate::vmm_config::wp_uffd::SetupWpUffdParams;
 use crate::vmm_config::vsock::{VsockConfigError, VsockDeviceConfig};
 use crate::vmm_config::{self, RateLimiterUpdate};
 
@@ -53,6 +54,12 @@ pub enum VmmAction {
     /// Create a snapshot using as input the `CreateSnapshotParams`. This action can only be called
     /// after the microVM has booted and only when the microVM is in `Paused` state.
     CreateSnapshot(CreateSnapshotParams),
+    /// Set up a write-protected userfaultfd over guest memory, register
+    /// every region in WP mode, and send the resulting fd to a UDS the
+    /// caller is listening on (via SCM_RIGHTS). Can only be called
+    /// after the microVM has booted; does not require the VM to be
+    /// paused.
+    SetupWpUffd(SetupWpUffdParams),
     /// Get the balloon device configuration.
     GetBalloonConfig,
     /// Get the ballon device latest statistics.
@@ -142,6 +149,8 @@ pub enum VmmActionError {
     InternalVmm(#[from] VmmError),
     /// Load snapshot error: {0}
     LoadSnapshot(#[from] LoadSnapshotError),
+    /// Setup WP uffd error: {0}
+    SetupWpUffd(#[from] crate::persist::SetupWpUffdError),
     /// Logger error: {0}
     Logger(#[from] crate::logger::LoggerUpdateError),
     /// Machine config error: {0}
@@ -438,6 +447,7 @@ impl<'a> PrebootApiController<'a> {
             SetEntropyDevice(config) => self.set_entropy_device(config),
             // Operations not allowed pre-boot.
             CreateSnapshot(_)
+            | SetupWpUffd(_)
             | FlushMetrics
             | Pause
             | Resume
@@ -627,6 +637,7 @@ impl RuntimeApiController {
         match request {
             // Supported operations allowed post-boot.
             CreateSnapshot(snapshot_create_cfg) => self.create_snapshot(&snapshot_create_cfg),
+            SetupWpUffd(params) => self.setup_wp_uffd(&params),
             FlushMetrics => self.flush_metrics(),
             GetBalloonConfig => self
                 .vmm
@@ -749,6 +760,17 @@ impl RuntimeApiController {
             .map_err(VmmActionError::InternalVmm)
     }
 
+    fn setup_wp_uffd(
+        &mut self,
+        params: &SetupWpUffdParams,
+    ) -> Result<VmmData, VmmActionError> {
+        log_dev_preview_warning("Snapshot-side WP userfaultfd", None);
+        let locked_vmm = self.vmm.lock().expect("Poisoned lock");
+        crate::persist::setup_wp_uffd(&locked_vmm, &params.socket)
+            .map_err(VmmActionError::SetupWpUffd)?;
+        Ok(VmmData::Empty)
+    }
+
     fn create_snapshot(
         &mut self,
         create_params: &CreateSnapshotParams,

src/vmm/src/vmm_config/mod.rs

@@ -32,6 +32,7 @@ pub mod mmds;
 pub mod net;
 /// Wrapper for configuring microVM snapshots and the microVM state.
 pub mod snapshot;
+pub mod wp_uffd;
 /// Wrapper for configuring the vsock devices attached to the microVM.
 pub mod vsock;