vmm: config: add memory_restore_mode to RestoreConfig

Add a MemoryRestoreMode enum (Copy | OnDemand) to RestoreConfig so
the restore path can be selected at restore time. Copy preserves the
existing eager read-copy behavior. OnDemand enables userfaultfd-based
demand paging and fails restore if the kernel does not support it.

Validate that prefault=on is not combined with OnDemand mode.

Update the OpenAPI spec with the new enum field.

Signed-off-by: Shayon Mukherjee <shayonj@gmail.com>

docs/snapshot_restore.md

@@ -93,6 +93,28 @@ start using it.
 At this point, the VM is fully restored and is identical to the VM which was
 snapshot earlier.
 
+Restore also supports selecting how guest memory is populated:
+
+```bash
+./cloud-hypervisor \
+    --api-socket /tmp/cloud-hypervisor.sock \
+    --restore source_url=file:///home/foo/snapshot,memory_restore_mode=ondemand
+```
+
+If `memory_restore_mode` is omitted, Cloud Hypervisor uses the eager-copy
+restore path (`copy`).
+
+With `memory_restore_mode=ondemand`, restore uses `userfaultfd` to fault snapshot
+pages in on first access instead of copying the full `memory-ranges` file into
+guest RAM before restore completes. This mode is strict: if Cloud Hypervisor
+cannot enable the `userfaultfd` restore path, restore fails instead of falling
+back to `copy`.
+
+Current constraints for `memory_restore_mode=ondemand`:
+
+- `prefault=on` is not supported
+- the snapshot memory ranges must be page-aligned
+
 ## Restore a VM with new Net FDs
 For a VM created with FDs explicitly passed to NetConfig, a set of valid FDs
 need to be provided along with the VM restore command in the following syntax: