docs: add documentation and CHANGELOG entry for VMClock

Mention support for VMClock and give pointers that required patches for
snapshot safety support.

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

Author: bchalios

CHANGELOG.md

@@ -10,6 +10,14 @@ and this project adheres to
 
 ### Added
 
+- [#5510](https://github.com/firecracker-microvm/firecracker/pull/5510),
+  [#5593](https://github.com/firecracker-microvm/firecracker/pull/5593),
+  [#5564](https://github.com/firecracker-microvm/firecracker/pull/5564):
+  Add support for the [VMClock device](https://uapi-group.org/specifications/specs/vmclock).
+  The implementation supports the snapshot safety features proposed
+  [here](https://lore.kernel.org/lkml/[email protected]/).
+  More information can be found in [docs](docs/snapshotting/snapshot-support.md#userspace-notifications-of-loading-virtual-machine-snapshots).
+
 ### Changed
 
 ### Deprecated

docs/snapshotting/snapshot-support.md

@@ -24,6 +24,7 @@
 - [Snapshot security and uniqueness](#snapshot-security-and-uniqueness)
   - [Secure and insecure usage examples](#usage-examples)
   - [Reusing snapshotted states securely](#reusing-snapshotted-states-securely)
+  - [Userspace notifications of loading Virtual Machine snapshots](#userspace-notifications-of-loading-virtual-machine-snapshots)
 - [Vsock device limitation](#vsock-device-limitation)
 - [VMGenID device limitation](#vmgenid-device-limitation)
 - [Where can I resume my snapshots?](#where-can-i-resume-my-snapshots)
@@ -590,6 +591,38 @@ identifiers, cached random numbers, cryptographic tokens, etc **will** still be
 replicated across multiple microVMs resumed from the same snapshot. Users need
 to implement mechanisms for ensuring de-duplication of such state, where needed.
 
+## Userspace notifications of loading Virtual Machine snapshots
+
+VMClock device ([specification](https://uapi-group.org/specifications/specs/vmclock/))
+is a device that enables efficient application clock synchronization against
+real wallclock time, for applications running inside Virtual Machines. VMCLock
+also takes care situations where there is some sort disruption happens to the
+clock. It handles these through fields in the
+[`vmlcock_abi`](https://uapi-group.org/specifications/specs/vmclock/#the-vmclock_abi-structure).
+Currently, it handles two cases:
+1. Live migration through the `disruption_marker` field.
+1. Virtual machine snapshots through the `vm_generation_counter`.
+
+Whenever a VM starts from a snapshot VMClock will present a new (different that
+what was previously stored) value in the `vm_generation_counter`. This happens
+in an atomic way, i.e. `vm_generation_counter` will include the new value as
+soon as vCPUs are resumed post snapshot loading.
+
+User space libraries, e.g. userspace PRNGs can mmap() `vmclock_abi` and monitor
+changes in `vm_generation_counter` to observe when they need to adapt and/or
+recreate state.
+
+Moreover, VMClock allows processes to call poll() on the VMClock device and get
+notified about changes through an event loop.
+
+> [!IMPORTANT]
+> Support for `vm_generation_counter` and `poll()` is implemented in Linux through
+> the patches [here](https://lore.kernel.org/lkml/[email protected]/).
+> We have backported these patches for AL kernels [here](../../resources/patches/vmclock)
+> 5.10 and 6.1 kernels. Using the kernels suggested from the [Getting Started Guide](../getting-started.md)
+> includes these patches. When using mainline kernels users need to make sure that
+> they apply the linked patches, until these get merged upstream.
+
 ## Vsock device reset
 
 The vsock device is reset across snapshot/restore to avoid inconsistent state