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 <bchalios@amazon.es>

Author: Babis Chalios

CHANGELOG.md

@@ -10,8 +10,23 @@ 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/20260107132514.437-1-bchalios@amazon.es/).
+  More information can be found in
+  [docs](docs/snapshotting/snapshot-support.md#userspace-notifications-of-loading-virtual-machine-snapshots).
+
 ### Changed
 
+- [#5564](https://github.com/firecracker-microvm/firecracker/pull/5564): which
+  added support for VMClock, uses one extra GSI for the VMClock device itself
+  which reduces the available GSIs for VirtIO devices. New maximum values is 93
+  devices on Aarch64 and 17 devices on x86.
+
 ### Deprecated
 
 ### Removed

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,41 @@ 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/20260107132514.437-1-bchalios@amazon.es/).
+> 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