docs(snapshot): document version_map caveats

There is some usability issues due to how versioning is implemented in
relation with the snapshot versioning feature. How this is exhibited is
in two ways:

1. When running `firecracker --describe-snapshot SNAPSHOT`.

   This will return the version of firecracker that introduced that
   snapshot version, which may be different from the firecracker version
   is was taken with.

2. When requesting a `version` in the `/snapshot/create` HTTP API.

   Again, this has to be the version of firecracker that introduced the
   snapshot version, not the firecracker version.

Signed-off-by: Pablo Barbáchano <pablob@amazon.com>

Author: pb8o

docs/snapshotting/snapshot-support.md

@@ -293,15 +293,24 @@ the snapshot.
     dirtied page bitmap and marks all pages clean (from a diff snapshot point
     of view).
   - If a `version` is specified, the new snapshot is saved at that version,
-    otherwise it will be saved at the same version of the running Firecracker.
-    The version is only used for the microVM state file as it contains internal
-    state structures for device emulation, vCPUs and others that can change
-    their format from a Firecracker version to another. Versioning is not
-    required for the block and memory files. The separate block device file
-    components of the snapshot have to be handled by the user.
+    otherwise it will be saved at the latest snapshot version of the running
+    Firecracker. The version is only used for the microVM state file as it
+    contains internal state structures for device emulation, vCPUs and others
+    that can change their format from a Firecracker version to another.
+    Versioning is not required for the block and memory files.
 
 - _on failure_: no side-effects.
 
+**Notes**:
+
+- The separate block device file components of the snapshot have to be handled
+  by the user.
+- If specified, `version` must match the firecracker version that introduced a
+  snapshot version, which may differ from the running Firecracker version. For
+  example, if you are running on `1.1.2` and want to target version `1.0.4`, you
+  should specify `1.0.0`. Not specifying `version` uses the latest snapshot
+  version available to that version.
+
 #### Creating diff snapshots
 
 For creating a diff snapshot, you should use the same API command, but with

src/vmm/src/version_map.rs

@@ -63,6 +63,15 @@ lazy_static! {
 
     /// Static instance used for creating a 1:1 mapping between Firecracker release version
     /// and snapshot data format version.
+    /// !CAVEAT!
+    /// This map is supposed to be strictly one-to-one (i.e. bijective) because
+    /// describe-snapshot inverts it to look up the release that matches the
+    /// snapshot version. If two version map to the snap_version, the results
+    /// are non-deterministic.
+    /// This means
+    /// - Do not insert patch releases here.
+    /// - Every minor version should be represented here.
+    /// - When requesting a `target_version`, these are the versions we expect.
     pub static ref FC_VERSION_TO_SNAP_VERSION: HashMap<String, u16> = {
         let mut mapping = HashMap::new();
         #[cfg(not(target_arch = "aarch64"))]