[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [Xen-devel] [Patch v6 01/13] docs: libxc migration stream specification

On 07/08/2014 01:37 AM, Andrew Cooper wrote:
Add the specification for a new migration stream format.  The document
includes all the details but to summarize:

The existing (legacy) format is dependant on the word size of the
toolstack.  This prevents domains from migrating from hosts running
32-bit toolstacks to hosts running 64-bit toolstacks (and vice-versa).

The legacy format lacks any version information making it difficult to
extend in compatible way.

The new format has a header (the image header) with version information,
a domain header with basic information of the domain and a stream of
records for the image data.

The format will be used for future domain types (such as on ARM).

The specification is pandoc format (an extended markdown format) and the
documentation build system is extended to support pandoc format documents.

Signed-off-by: Andrew Cooper <andrew.cooper3@xxxxxxxxxx>
CC: Ian Campbell <Ian.Campbell@xxxxxxxxxx>
CC: Ian Jackson <Ian.Jackson@xxxxxxxxxxxxx>

  * Add pandoc -> txt/html conversion
  * Spelling fixes
  * Introduce SAVING_CPU record
  docs/Makefile                            |   11 +-
  docs/specs/libxc-migration-stream.pandoc |  677 ++++++++++++++++++++++++++++++
  2 files changed, 687 insertions(+), 1 deletion(-)


+A verify record indicates that, while all memory has now been sent, the sender
+shall send further memory records for debugging purposes.
+     0     1     2     3     4     5     6     7 octet
+    +-------------------------------------------------+
+The verify record contains no fields; its body_length is 0.
+A saving cpu record provides a human readable representation of the CPU on
+which the guest was saved.
+     0     1     2     3     4     5     6     7 octet
+    +------------------------+------------------------+
+    | 7bit ASCII String                               |
+    ...
+    +-------------------------------------------------+
+The information is purely informative as it doesn't directly affect how to
+save or restore the guest, but in the case of an error on restoration may help
+to narrow down the issue.
+x86 architecutres use the _CPUID_ 48 character processor brand string.
+The set of valid records depends on the guest architecture and type.
+x86 PV Guest
+An x86 PV guest image will have this order of records:
+1. Image header
+2. Domain header
+3. X86\_PV\_INFO record
+4. X86\_PV\_P2M\_FRAMES record
+5. Many PAGE\_DATA records
+7. SHARED\_INFO record
+8. VCPU context records for each online VCPU
+    a. X86\_PV\_VCPU\_BASIC record
+    b. X86\_PV\_VCPU\_EXTENDED record
+    c. X86\_PV\_VCPU\_XSAVE record
+    d. X86\_PV\_VCPU\_MSRS record
+9. END record
+x86 HVM Guest
+1. Image header
+2. Domain header
+3. Many PAGE\_DATA records

do VERIFY/SAVING_CPU records should be document here?
Although they are optional, we may need to know in which order
when they are included...

+Legacy Images (x86 only)
+Restoring legacy images from older tools shall be handled by
+translating the legacy format image into this new format.
+It shall not be possible to save in the legacy format.
+There are two different legacy images depending on whether they were
+generated by a 32-bit or a 64-bit toolstack. These shall be
+distinguished by inspecting octets 4-7 in the image.  If these are
+zero then it is a 64-bit image.
+Toolstack  Field                            Value
+---------  -----                            -----
+64-bit     Bit 31-63 of the p2m_size field  0 (since p2m_size < 2^32^)
+32-bit     extended-info chunk ID (PV)      0xFFFFFFFF
+32-bit     Chunk type (HVM)                 < 0
+32-bit     Page count (HVM)                 > 0
+Table: Possible values for octet 4-7 in legacy images
+This assumes the presence of the extended-info chunk which was
+introduced in Xen 3.0.
+Future Extensions
+All changes to the image or domain headers require the image version
+to be increased.
+The format may be extended by adding additional record types.
+Extending an existing record type must be done by adding a new record
+type.  This allows old images with the old record to still be
+The image header may only be extended by _appending_ additional
+fields.  In particular, the `marker`, `id` and `version` fields must
+never change size or location.


Xen-devel mailing list



Lists.xenproject.org is hosted with RackSpace, monitoring our
servers 24x7x365 and backed by RackSpace's Fanatical Support®.