From: Andrew Cooper <andrew.cooper3@citrix.com>
To: Xen-devel <xen-devel@lists.xen.org>
Cc: Wei Liu <wei.liu2@citrix.com>,
Yang Hongyang <yanghy@cn.fujitsu.com>,
Ian Jackson <Ian.Jackson@eu.citrix.com>,
Ian Campbell <Ian.Campbell@citrix.com>,
Andrew Cooper <andrew.cooper3@citrix.com>
Subject: [PATCH 10/27] docs: Libxl migration v2 stream specification
Date: Mon, 15 Jun 2015 14:44:23 +0100 [thread overview]
Message-ID: <1434375880-30914-11-git-send-email-andrew.cooper3@citrix.com> (raw)
In-Reply-To: <1434375880-30914-1-git-send-email-andrew.cooper3@citrix.com>
Signed-off-by: Andrew Cooper <andrew.cooper3@citrix.com>
---
docs/specs/libxl-migration-stream.pandoc | 205 ++++++++++++++++++++++++++++++
1 file changed, 205 insertions(+)
create mode 100644 docs/specs/libxl-migration-stream.pandoc
diff --git a/docs/specs/libxl-migration-stream.pandoc b/docs/specs/libxl-migration-stream.pandoc
new file mode 100644
index 0000000..7235317
--- /dev/null
+++ b/docs/specs/libxl-migration-stream.pandoc
@@ -0,0 +1,205 @@
+% LibXenLight Domain Image Format
+% Andrew Cooper <<andrew.cooper3@citrix.com>>
+% Draft B
+
+Introduction
+============
+
+For the purposes of this document, `xl` is used as a representation of any
+implementer of the `libxl` API. `xl` should be considered completely
+interchangeable with alternates, such as `libvirt` or `xenopsd-xl`.
+
+Purpose
+-------
+
+The _domain image format_ is the context of a running domain used for
+snapshots of a domain or for transferring domains between hosts during
+migration.
+
+There are a number of problems with the domain image format used in Xen 4.5
+and earlier (the _legacy format_)
+
+* There is no `libxl` context information. `xl` is required to send certain
+ pieces of `libxl` context itself.
+
+* The contents of the stream is passed directly through `libxl` to `libxc`.
+ The legacy `libxc` format contained some information which belonged at the
+ `libxl` level, resulting in awkward layer violation to return the
+ information back to `libxl`.
+
+* The legacy `libxc` format was inextensible, causing inextensibility in the
+ legacy `libxl` handling.
+
+This design addresses the above points, allowing for a completely
+self-contained, extensible stream with each layer responsibile for its own
+appropriate information.
+
+
+Not Yet Included
+----------------
+
+The following features are not yet fully specified and will be
+included in a future draft.
+
+* Remus
+
+* ARM
+
+
+Overview
+========
+
+The image format consists of a _Header_, followed by 1 or more _Records_.
+Each record consists of a type and length field, followed by any type-specific
+data.
+
+\clearpage
+
+Header
+======
+
+The header identifies the stream as a `libxl` stream, including the version of
+this specification that it complies with.
+
+All fields in this header shall be in _big-endian_ byte order, regardless of
+the setting of the endianness bit.
+
+ 0 1 2 3 4 5 6 7 octet
+ +-------------------------------------------------+
+ | ident |
+ +-----------------------+-------------------------+
+ | version | options |
+ +-----------------------+-------------------------+
+
+--------------------------------------------------------------------
+Field Description
+----------- --------------------------------------------------------
+ident 0x4c6962786c466d74 ("LibxlFmt" in ASCII).
+
+version 0x00000002. The version of this specification.
+
+options bit 0: Endianness. 0 = little-endian, 1 = big-endian.
+
+ bit 1: Legacy Format. If set, this stream was created by
+ the legacy conversion tool.
+
+ bits 2-31: Reserved.
+--------------------------------------------------------------------
+
+The endianness shall be 0 (little-endian) for images generated on an
+i386, x86_64, or arm host.
+
+\clearpage
+
+
+Records
+=======
+
+A record has a record header, type specific data and a trailing footer. If
+`length` is not a multiple of 8, the body is padded with zeroes to align the
+end of the record on an 8 octet boundary.
+
+ 0 1 2 3 4 5 6 7 octet
+ +-----------------------+-------------------------+
+ | type | body_length |
+ +-----------+-----------+-------------------------+
+ | body... |
+ ...
+ | | padding (0 to 7 octets) |
+ +-----------+-------------------------------------+
+
+--------------------------------------------------------------------
+Field Description
+----------- -------------------------------------------------------
+type 0x00000000: END
+
+ 0x00000001: LIBXC_CONTEXT
+
+ 0x00000002: XENSTORE_DATA
+
+ 0x00000003: EMULATOR_CONTEXT
+
+ 0x00000004 - 0x7FFFFFFF: Reserved for future _mandatory_
+ records.
+
+ 0x80000000 - 0xFFFFFFFF: Reserved for future _optional_
+ records.
+
+body_length Length in octets of the record body.
+
+body Content of the record.
+
+padding 0 to 7 octets of zeros to pad the whole record to a multiple
+ of 8 octets.
+--------------------------------------------------------------------
+
+\clearpage
+
+END
+----
+
+A end record marks the end of the image, and shall be the final record
+in the stream.
+
+ 0 1 2 3 4 5 6 7 octet
+ +-------------------------------------------------+
+
+The end record contains no fields; its body_length is 0.
+
+LIBXC\_CONTEXT
+--------------
+
+A libxc context record is a marker, indicating that the stream should be
+handed to `xc_domain_restore()`. `libxc` shall be resonsible for reading its
+own image format from the stream.
+
+ 0 1 2 3 4 5 6 7 octet
+ +-------------------------------------------------+
+
+The libxc context record contains no fields; its body_length is 0[^1].
+
+
+[^1]: The sending side cannot calculate ahead of time how much data `libxc`
+might write into the stream, especially for live migration where the quantity
+of data is partially proportional to the elapsed time.
+
+XENSTORE\_DATA
+-------------
+
+A record containing xenstore key/value pairs of data.
+
+ 0 1 2 3 4 5 6 7 octet
+ +-------------------------------------------------+
+ | xenstore key/value pairs |
+ ...
+ +-------------------------------------------------+
+
+EMULATOR\_CONTEXT
+----------------
+
+A context blob for a specific emulator associated with the domain.
+
+ 0 1 2 3 4 5 6 7 octet
+ +------------------------+------------------------+
+ | emulator_id | index |
+ +------------------------+------------------------+
+ | emulator_ctx |
+ ...
+ +-------------------------------------------------+
+
+--------------------------------------------------------------------
+Field Description
+------------ ---------------------------------------------------
+emulator_id 0x00000000: Unknown (In the case of a legacy stream)
+
+ 0x00000001: Qemu Traditional
+
+ 0x00000002: Qemu Upstream
+
+ 0x00000003 - 0xFFFFFFFF: Reserved for future emulators.
+
+index Index of this emulator for the domain, if multiple
+ emulators are in use.
+
+emulator_ctx Emulator context blob.
+--------------------------------------------------------------------
--
1.7.10.4
next prev parent reply other threads:[~2015-06-15 13:44 UTC|newest]
Thread overview: 107+ messages / expand[flat|nested] mbox.gz Atom feed top
2015-06-15 13:44 [PATCH 00/27] Libxl migration v2 Andrew Cooper
2015-06-15 13:44 ` [PATCH 01/27] tools/libxl: Fix libxl__ev_child_inuse() check for not-yet-initialised children Andrew Cooper
2015-06-16 13:21 ` Ian Campbell
2015-06-16 13:36 ` Andrew Cooper
2015-06-16 13:47 ` Ian Jackson
2015-06-16 14:05 ` Andrew Cooper
2015-06-16 15:26 ` Ian Campbell
2015-06-16 15:24 ` Ian Campbell
2015-06-16 13:39 ` Ian Jackson
2015-06-15 13:44 ` [PATCH 02/27] tools/libxc: Always compile the compat qemu variables into xc_sr_context Andrew Cooper
2015-06-16 13:22 ` Ian Campbell
2015-06-15 13:44 ` [PATCH 03/27] tools/libxl: Stash all restore parameters in domain_create_state Andrew Cooper
2015-06-16 13:37 ` Ian Campbell
2015-06-16 14:09 ` Andrew Cooper
2015-06-18 2:32 ` Yang Hongyang
2015-06-15 13:44 ` [PATCH 04/27] tools/xl: Mandatory flag indicating the format of the migration stream Andrew Cooper
2015-06-16 13:39 ` Ian Campbell
2015-06-16 14:10 ` Andrew Cooper
2015-06-15 13:44 ` [PATCH 05/27] tools/libxl: Introduce ROUNDUP() Andrew Cooper
2015-06-16 13:39 ` Ian Campbell
2015-06-15 13:44 ` [PATCH 06/27] libxl: cancellation: Preparations for save/restore cancellation Andrew Cooper
2015-06-15 13:44 ` [PATCH 07/27] libxl: cancellation: Handle SIGTERM in save/restore helper Andrew Cooper
2015-06-15 13:44 ` [PATCH 08/27] tools/libxl: Extra APIs for the save helper Andrew Cooper
2015-06-16 13:50 ` Ian Campbell
2015-06-16 15:03 ` Andrew Cooper
2015-06-15 13:44 ` [PATCH 09/27] tools/libxl: Pass restore_fd as a parameter to libxl__xc_domain_restore() Andrew Cooper
2015-06-16 13:53 ` Ian Campbell
2015-06-15 13:44 ` Andrew Cooper [this message]
2015-06-16 13:58 ` [PATCH 10/27] docs: Libxl migration v2 stream specification Ian Campbell
2015-07-08 13:49 ` Andrew Cooper
2015-07-08 13:58 ` Ian Campbell
2015-06-15 13:44 ` [PATCH 11/27] tools/python: Libxc migration v2 infrastructure Andrew Cooper
2015-06-16 14:01 ` Ian Campbell
2015-06-15 13:44 ` [PATCH 12/27] tools/python: Libxl " Andrew Cooper
2015-06-15 13:44 ` [PATCH 13/27] tools/python: Verification utility for v2 stream spec compliance Andrew Cooper
2015-06-15 13:44 ` [PATCH 14/27] tools/python: Conversion utility for legacy migration streams Andrew Cooper
2015-06-16 14:01 ` Ian Campbell
2015-06-15 13:44 ` [PATCH 15/27] tools/libxl: Migration v2 stream format Andrew Cooper
2015-06-16 14:04 ` Ian Campbell
2015-06-15 13:44 ` [PATCH 16/27] tools/libxl: Infrastructure for reading a libxl migration v2 stream Andrew Cooper
2015-06-16 14:31 ` Ian Campbell
2015-06-16 15:01 ` Andrew Cooper
2015-06-16 15:35 ` Ian Campbell
2015-06-16 15:46 ` Andrew Cooper
2015-06-17 3:09 ` Wen Congyang
2015-06-17 10:15 ` Ian Campbell
2015-06-17 10:49 ` Wen Congyang
2015-06-17 10:55 ` Ian Campbell
2015-06-17 6:03 ` Wen Congyang
2015-06-17 9:47 ` Andrew Cooper
2015-06-17 7:57 ` Wen Congyang
2015-06-17 9:50 ` Andrew Cooper
2015-06-17 10:01 ` Wen Congyang
2015-06-17 10:48 ` Andrew Cooper
2015-06-15 13:44 ` [PATCH 17/27] tools/libxl: Support converting a legacy stream to a " Andrew Cooper
2015-06-16 14:38 ` Ian Campbell
2015-06-16 15:13 ` Andrew Cooper
2015-06-16 15:38 ` Ian Campbell
2015-06-15 13:44 ` [PATCH 18/27] tools/libxl: Convert a legacy stream if needed Andrew Cooper
2015-06-15 13:44 ` [PATCH 19/27] tools/libxc+libxl+xl: Restore v2 streams Andrew Cooper
2015-06-16 14:53 ` Ian Campbell
2015-06-16 15:23 ` Andrew Cooper
2015-06-16 15:39 ` Ian Campbell
2015-06-15 13:44 ` [PATCH 20/27] tools/libxl: Infrastructure for writing a v2 stream Andrew Cooper
2015-06-16 14:57 ` Ian Campbell
2015-06-16 15:28 ` Andrew Cooper
2015-06-17 1:31 ` Yang Hongyang
2015-06-17 9:51 ` Andrew Cooper
2015-06-17 1:39 ` Wen Congyang
2015-06-17 2:24 ` Wen Congyang
2015-06-17 7:38 ` Yang Hongyang
2015-06-17 10:14 ` Wen Congyang
2015-07-10 10:55 ` Ian Campbell
2015-07-10 11:03 ` Andrew Cooper
2015-07-10 11:05 ` Ian Campbell
2015-06-15 13:44 ` [PATCH 21/27] tools/libxc+libxl+xl: Save v2 streams Andrew Cooper
2015-06-16 14:59 ` Ian Campbell
2015-06-15 13:44 ` [PATCH 22/27] docs/libxl: [RFC] Introduce CHECKPOINT_END to support migration v2 remus streams Andrew Cooper
2015-06-16 15:00 ` Ian Campbell
2015-06-16 15:30 ` Andrew Cooper
2015-06-17 3:30 ` Wen Congyang
2015-06-15 13:44 ` [PATCH 23/27] tools/libxl: [RFC] Write checkpoint records into the stream Andrew Cooper
2015-06-16 15:03 ` Ian Campbell
2015-06-16 15:53 ` Andrew Cooper
2015-06-17 7:30 ` Ian Campbell
2015-06-17 9:55 ` Andrew Cooper
2015-06-18 3:13 ` Wen Congyang
2015-06-18 9:44 ` Andrew Cooper
2015-06-15 13:44 ` [PATCH 24/27] tools/libx{c, l}: [RFC] Introduce restore_callbacks.checkpoint() Andrew Cooper
2015-06-16 2:23 ` Yang Hongyang
2015-06-17 8:20 ` Yang Hongyang
2015-06-15 13:44 ` [PATCH 25/27] tools/libxl: [RFC] Handle checkpoint records in a libxl migration v2 stream Andrew Cooper
2015-06-17 7:28 ` Wen Congyang
2015-06-15 13:44 ` [PATCH 26/27] tools/libxc: Drop all XG_LIBXL_HVM_COMPAT code from libxc Andrew Cooper
2015-06-16 15:03 ` Ian Campbell
2015-06-15 13:44 ` [PATCH 27/27] tools/libxl: Drop all knowledge of toolstack callbacks Andrew Cooper
2015-06-16 15:04 ` Ian Campbell
2015-06-16 15:06 ` Andrew Cooper
2015-06-17 10:14 ` Ian Campbell
2015-06-17 10:43 ` Andrew Cooper
2015-06-17 10:53 ` Ian Campbell
2015-06-16 2:21 ` [PATCH 00/27] Libxl migration v2 Yang Hongyang
2015-06-17 1:55 ` Wen Congyang
2015-06-17 9:45 ` Andrew Cooper
2015-07-02 7:33 ` Yang Hongyang
2015-07-02 9:26 ` Andrew Cooper
2015-07-02 9:33 ` Yang Hongyang
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=1434375880-30914-11-git-send-email-andrew.cooper3@citrix.com \
--to=andrew.cooper3@citrix.com \
--cc=Ian.Campbell@citrix.com \
--cc=Ian.Jackson@eu.citrix.com \
--cc=wei.liu2@citrix.com \
--cc=xen-devel@lists.xen.org \
--cc=yanghy@cn.fujitsu.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.