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

[Hongyang Yang <yanghy@cn.fujitsu.com>]

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@citrix.com>
> CC: Ian Campbell <Ian.Campbell@citrix.com>
> CC: Ian Jackson <Ian.Jackson@eu.citrix.com>
>
> ---
> v6:
>   * 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(-)

...snip...

> +
> +VERIFY
> +------
> +
> +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.
> +
> +\clearpage
> +
> +SAVING\_CPU
> +----------
> +
> +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.
> +
> +\clearpage
> +
> +Layout
> +======
> +
> +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
> +6. TSC\_INFO
> +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
> +4. TSC\_INFO
> +5. HVM\_CONTEXT
> +6. HVM\_PARAMS
> +

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
> +restored.
> +
> +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.
>

-- 
Thanks,
Yang.