docs/migration Specify migration v3 and STATIC_DATA_END

Migration data can be split into two parts - that which is invariant of
guest execution, and that which is not.  Separate these two with the
STATIC_DATA_END record.

The short term, we want to move the x86 CPU Policy data into the stream.
In the longer term, we want to provisionally send the static data only
to the destination as a more robust compatibility check.  In both cases,
we will want a callback into the higher level toolstack.

Mandate the presence of the STATIC_DATA_END record, and declare this v3,
along with instructions for how to compatibly interpret a v2 stream.

Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
Acked-by: Ian Jackson <ian.jackson@eu.citrix.com>

diff --git a/docs/specs/libxc-migration-stream.pandoc b/docs/specs/libxc-migration-stream.pandoc
index 89705c9207a9ddf7f9d4b53d8e984dd6e6d50a2e..346d2431755f5d8c525cdf7f9b470d0c7a9726a5 100644 (file)
--- a/docs/specs/libxc-migration-stream.pandoc
+++ b/docs/specs/libxc-migration-stream.pandoc
@@ -127,7 +127,7 @@ marker      0xFFFFFFFFFFFFFFFF.
 
 id          0x58454E46 ("XENF" in ASCII).
 
-version     0x00000002.  The version of this specification.
+version     0x00000003.  The version of this specification.
 
 options     bit 0: Endianness.  0 = little-endian, 1 = big-endian.
 
@@ -620,6 +620,21 @@ The count of pfns is: record->length/sizeof(uint64_t).
 
 \clearpage
 
+STATIC_DATA_END
+---------------
+
+A static data end record marks the end of the static state.  I.e. state which
+is invariant of guest execution.
+
+
+     0     1     2     3     4     5     6     7 octet
+    +-------------------------------------------------+
+
+The end record contains no fields; its body_length is 0.
+
+\clearpage
+
+
 Layout
 ======
 
@@ -639,7 +654,9 @@ A typical save record for an x86 PV guest image would look like:
 
 * Image header
 * Domain header
-* X86_PV_INFO record
+* Static data records:
+    * X86_PV_INFO record
+    * STATIC_DATA_END
 * X86_PV_P2M_FRAMES record
 * Many PAGE_DATA records
 * X86_TSC_INFO
@@ -667,6 +684,8 @@ A typical save record for an x86 HVM guest image would look like:
 
 * Image header
 * Domain header
+* Static data records:
+    * STATIC_DATA_END
 * Many PAGE_DATA records
 * X86_TSC_INFO
 * HVM_PARAMS
@@ -675,9 +694,23 @@ A typical save record for an x86 HVM guest image would look like:
 HVM_PARAMS must precede HVM_CONTEXT, as certain parameters can affect
 the validity of architectural state in the context.
 
+Compatibility with older versions
+=================================
+
+v3 compat with v2
+-----------------
+
+A v3 stream is compatible with a v2 stream, but mandates the presense of a
+STATIC_DATA_END record ahead of any memory/register content.  This is to ease
+the introduction of new static configuration records over time.
+
+A v3-compatible reciever interpreting a v2 stream should infer the position of
+STATIC_DATA_END based on finding the first X86_PV_P2M_FRAMES record (for PV
+guests), or PAGE_DATA record (for HVM guests) and behave as if STATIC_DATA_END
+had been sent.
 
 Legacy Images (x86 only)
-========================
+------------------------
 
 Restoring legacy images from older tools shall be handled by
 translating the legacy format image into this new format.

diff --git a/tools/libxc/xc_sr_common.c b/tools/libxc/xc_sr_common.c
index dd9a11b4b5a44d2d05b96e0158545e454faf9616..7f22cf0365d2319e46de71398872b95b478723d5 100644 (file)
--- a/tools/libxc/xc_sr_common.c
+++ b/tools/libxc/xc_sr_common.c
@@ -36,6 +36,7 @@ static const char *const mandatory_rec_types[] =
     [REC_TYPE_VERIFY]                       = "Verify",
     [REC_TYPE_CHECKPOINT]                   = "Checkpoint",
     [REC_TYPE_CHECKPOINT_DIRTY_PFN_LIST]    = "Checkpoint dirty pfn list",
+    [REC_TYPE_STATIC_DATA_END]              = "Static data end",
 };
 
 const char *rec_type_to_str(uint32_t type)

diff --git a/tools/libxc/xc_sr_stream_format.h b/tools/libxc/xc_sr_stream_format.h
index ae7c0de393ac017b0bb9a90fe31dbc8e35bc44a6..81c9765b0a5ed02f569a59a36532f03c729652e8 100644 (file)
--- a/tools/libxc/xc_sr_stream_format.h
+++ b/tools/libxc/xc_sr_stream_format.h
@@ -73,6 +73,7 @@ struct xc_sr_rhdr
 #define REC_TYPE_VERIFY                     0x0000000dU
 #define REC_TYPE_CHECKPOINT                 0x0000000eU
 #define REC_TYPE_CHECKPOINT_DIRTY_PFN_LIST  0x0000000fU
+#define REC_TYPE_STATIC_DATA_END            0x00000010U
 
 #define REC_TYPE_OPTIONAL             0x80000000U
 

diff --git a/tools/python/xen/migration/libxc.py b/tools/python/xen/migration/libxc.py
index 63b355802944a9723a6c4c180aadd4116fca3603..d0c4f3527d0ff5d96557a721b34a1b26f19898c4 100644 (file)
--- a/tools/python/xen/migration/libxc.py
+++ b/tools/python/xen/migration/libxc.py
@@ -56,6 +56,7 @@ REC_TYPE_x86_pv_vcpu_msrs           = 0x0000000c
 REC_TYPE_verify                     = 0x0000000d
 REC_TYPE_checkpoint                 = 0x0000000e
 REC_TYPE_checkpoint_dirty_pfn_list  = 0x0000000f
+REC_TYPE_static_data_end            = 0x00000010
 
 rec_type_to_str = {
     REC_TYPE_end                        : "End",
@@ -74,6 +75,7 @@ rec_type_to_str = {
     REC_TYPE_verify                     : "Verify",
     REC_TYPE_checkpoint                 : "Checkpoint",
     REC_TYPE_checkpoint_dirty_pfn_list  : "Checkpoint dirty pfn list",
+    REC_TYPE_static_data_end            : "Static data end",
 }
 
 # page_data