From mboxrd@z Thu Jan 1 00:00:00 1970 From: Hongyang Yang Subject: Re: [Patch v6 01/13] docs: libxc migration stream specification Date: Tue, 8 Jul 2014 11:53:50 +0800 Message-ID: <53BB6B4E.30802@cn.fujitsu.com> References: <1404754682-28379-1-git-send-email-andrew.cooper3@citrix.com> <1404754682-28379-2-git-send-email-andrew.cooper3@citrix.com> Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii"; Format="flowed" Content-Transfer-Encoding: 7bit Return-path: In-Reply-To: <1404754682-28379-2-git-send-email-andrew.cooper3@citrix.com> List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Sender: xen-devel-bounces@lists.xen.org Errors-To: xen-devel-bounces@lists.xen.org To: Andrew Cooper , Xen-devel Cc: Ian Jackson , Ian Campbell List-Id: xen-devel@lists.xenproject.org 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 > CC: Ian Campbell > CC: Ian Jackson > > --- > 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.