motorhead/qemu
1
0
Fork 0
mirror of https://github.com/Motorhead1991/qemu.git synced 2025-09-09 08:17:53 -06:00
Code Issues Projects Releases Packages Wiki Activity Actions

migration: update docs

Browse source 
Update the migration docs:

Among other changes:
  * Added a general list of advice for device authors
  * Reordered the section on conditional state (subsections etc)
    into the order we prefer.
  * Add a note about firmware

Signed-off-by: Dr. David Alan Gilbert <dgilbert@redhat.com>
Reviewed-by: Peter Xu <peterx@redhat.com>
Reviewed-by: Balamuruhan S <bala24@linux.vnet.ibm.com>
Reviewed-by: Juan Quintela <quintela@redhat.com>
Message-Id: <20180503191059.19576-1-dgilbert@redhat.com>
Signed-off-by: Juan Quintela <quintela@redhat.com>
This commit is contained in:
Dr. David Alan Gilbert 2018-05-03 20:10:59 +01:00 • committed by Juan Quintela
parent d37297dc66
commit edd7080692
1 changed files with 368 additions and 148 deletions
Download patch file Download diff file Expand all files Collapse all files

516
docs/devel/migration.rst
View file

@ -28,11 +28,11 @@ the guest to be stopped. Typically the time that the guest is
unresponsive during live migration is the low hundred of milliseconds unresponsive during live migration is the low hundred of milliseconds
(notice that this depends on a lot of things). (notice that this depends on a lot of things).
Types of migration Transports
================== ==========
Now that we have talked about live migration, there are several ways The migration stream is normally just a byte stream that can be passed
to do migration: over any transport.
- tcp migration: do the migration using tcp sockets - tcp migration: do the migration using tcp sockets
- unix migration: do the migration using unix sockets - unix migration: do the migration using unix sockets
@ -40,16 +40,16 @@ to do migration:
- fd migration: do the migration using an file descriptor that is - fd migration: do the migration using an file descriptor that is
passed to QEMU. QEMU doesn't care how this file descriptor is opened. passed to QEMU. QEMU doesn't care how this file descriptor is opened.
All these four migration protocols use the same infrastructure to In addition, support is included for migration using RDMA, which
transports the page data using ``RDMA``, where the hardware takes care of
transporting the pages, and the load on the CPU is much lower. While the
internals of RDMA migration are a bit different, this isn't really visible
outside the RAM migration code.
All these migration protocols use the same infrastructure to
save/restore state devices. This infrastructure is shared with the save/restore state devices. This infrastructure is shared with the
savevm/loadvm functionality. savevm/loadvm functionality.
State Live Migration
====================
This is used for RAM and block devices. It is not yet ported to vmstate.
<Fill more information here>
Common infrastructure Common infrastructure
===================== =====================
@ -57,60 +57,75 @@ The files, sockets or fd's that carry the migration stream are abstracted by
the ``QEMUFile`` type (see `migration/qemu-file.h`). In most cases this the ``QEMUFile`` type (see `migration/qemu-file.h`). In most cases this
is connected to a subtype of ``QIOChannel`` (see `io/`). is connected to a subtype of ``QIOChannel`` (see `io/`).
Saving the state of one device Saving the state of one device
============================== ==============================
The state of a device is saved using intermediate buffers. There are For most devices, the state is saved in a single call to the migration
some helper functions to assist this saving. infrastructure; these are *non-iterative* devices. The data for these
devices is sent at the end of precopy migration, when the CPUs are paused.
There are also *iterative* devices, which contain a very large amount of
data (e.g. RAM or large tables). See the iterative device section below.
There is a new concept that we have to explain here: device state General advice for device developers
version. When we migrate a device, we save/load the state as a series ------------------------------------
of fields. Some times, due to bugs or new functionality, we need to
change the state to store more/different information. We use the
version to identify each time that we do a change. Each version is
associated with a series of fields saved. The `save_state` always saves
the state as the newer version. But `load_state` sometimes is able to
load state from an older version.
Legacy way - The migration state saved should reflect the device being modelled rather
---------- than the way your implementation works. That way if you change the implementation
later the migration stream will stay compatible. That model may include
internal state that's not directly visible in a register.
This way is going to disappear as soon as all current users are ported to VMSTATE. - When saving a migration stream the device code may walk and check
the state of the device. These checks might fail in various ways (e.g.
discovering internal state is corrupt or that the guest has done something bad).
Consider carefully before asserting/aborting at this point, since the
normal response from users is that *migration broke their VM* since it had
apparently been running fine until then. In these error cases, the device
should log a message indicating the cause of error, and should consider
putting the device into an error state, allowing the rest of the VM to
continue execution.
Each device has to register two functions, one to save the state and - The migration might happen at an inconvenient point,
another to load the state back. e.g. right in the middle of the guest reprogramming the device, during
guest reboot or shutdown or while the device is waiting for external IO.
It's strongly preferred that migrations do not fail in this situation,
since in the cloud environment migrations might happen automatically to
VMs that the administrator doesn't directly control.
.. code:: c - If you do need to fail a migration, ensure that sufficient information
is logged to identify what went wrong.
int register_savevm(DeviceState *dev, - The destination should treat an incoming migration stream as hostile
const char *idstr, (which we do to varying degrees in the existing code). Check that offsets
int instance_id, into buffers and the like can't cause overruns. Fail the incoming migration
int version_id, in the case of a corrupted stream like this.
SaveStateHandler *save_state,
LoadStateHandler *load_state,
void *opaque);
typedef void SaveStateHandler(QEMUFile *f, void *opaque); - Take care with internal device state or behaviour that might become
typedef int LoadStateHandler(QEMUFile *f, void *opaque, int version_id); migration version dependent. For example, the order of PCI capabilities
is required to stay constant across migration. Another example would
be that a special case handled by subsections (see below) might become
much more common if a default behaviour is changed.
The important functions for the device state format are the `save_state` - The state of the source should not be changed or destroyed by the
and `load_state`. Notice that `load_state` receives a version_id outgoing migration. Migrations timing out or being failed by
parameter to know what state format is receiving. `save_state` doesn't higher levels of management, or failures of the destination host are
have a version_id parameter because it always uses the latest version. not unusual, and in that case the VM is restarted on the source.
Note that the management layer can validly revert the migration
even though the QEMU level of migration has succeeded as long as it
does it before starting execution on the destination.
- Buses and devices should be able to explicitly specify addresses when
instantiated, and management tools should use those. For example,
when hot adding USB devices it's important to specify the ports
and addresses, since implicit ordering based on the command line order
may be different on the destination. This can result in the
device state being loaded into the wrong device.
VMState VMState
------- -------
The legacy way of saving/loading state of the device had the problem Most device data can be described using the ``VMSTATE`` macros (mostly defined
that we have to maintain two functions in sync. If we did one change in ``include/migration/vmstate.h``).
in one of them and not in the other, we would get a failed migration.
VMState changed the way that state is saved/loaded. Instead of using
a function to save the state and another to load it, it was changed to
a declarative way of what the state consisted of. Now VMState is able
to interpret that definition to be able to load/save the state. As
the state is declared only once, it can't go out of sync in the
save/load functions.
An example (from hw/input/pckbd.c) An example (from hw/input/pckbd.c)
@ -137,103 +152,99 @@ We registered this with:
vmstate_register(NULL, 0, &vmstate_kbd, s); vmstate_register(NULL, 0, &vmstate_kbd, s);
Note: talk about how vmstate <-> qdev interact, and what the instance ids mean. For devices that are `qdev` based, we can register the device in the class
init function:
You can search for ``VMSTATE_*`` macros for lots of types used in QEMU in .. code:: c
include/hw/hw.h.
More about versions dc->vmsd = &vmstate_kbd_isa;
-------------------
Version numbers are intended for major incompatible changes to the The VMState macros take care of ensuring that the device data section
migration of a device, and using them breaks backwards-migration is formatted portably (normally big endian) and make some compile time checks
compatibility; in general most changes can be made by adding Subsections against the types of the fields in the structures.
(see below) or _TEST macros (see below) which won't break compatibility.
You can see that there are several version fields: VMState macros can include other VMStateDescriptions to store substructures
(see ``VMSTATE_STRUCT_``), arrays (``VMSTATE_ARRAY_``) and variable length
arrays (``VMSTATE_VARRAY_``). Various other macros exist for special
cases.
- `version_id`: the maximum version_id supported by VMState for that device. Note that the format on the wire is still very raw; i.e. a VMSTATE_UINT32
- `minimum_version_id`: the minimum version_id that VMState is able to understand ends up with a 4 byte bigendian representation on the wire; in the future
for that device. it might be possible to use a more structured format.
- `minimum_version_id_old`: For devices that were not able to port to vmstate, we can
assign a function that knows how to read this old state. This field is
ignored if there is no `load_state_old` handler.
So, VMState is able to read versions from minimum_version_id to Legacy way
version_id. And the function ``load_state_old()`` (if present) is able to ----------
load state from minimum_version_id_old to minimum_version_id. This
function is deprecated and will be removed when no more users are left.
Saving state will always create a section with the 'version_id' value This way is going to disappear as soon as all current users are ported to VMSTATE;
and thus can't be loaded by any older QEMU. although converting existing code can be tricky, and thus 'soon' is relative.
Massaging functions Each device has to register two functions, one to save the state and
------------------- another to load the state back.
Sometimes, it is not enough to be able to save the state directly .. code:: c
from one structure, we need to fill the correct values there. One
example is when we are using kvm. Before saving the cpu state, we
need to ask kvm to copy to QEMU the state that it is using. And the
opposite when we are loading the state, we need a way to tell kvm to
load the state for the cpu that we have just loaded from the QEMUFile.
The functions to do that are inside a vmstate definition, and are called: int register_savevm_live(DeviceState *dev,
const char *idstr,
int instance_id,
int version_id,
SaveVMHandlers *ops,
void *opaque);
- ``int (*pre_load)(void *opaque);`` Two functions in the ``ops`` structure are the `save_state`
and `load_state` functions. Notice that `load_state` receives a version_id
parameter to know what state format is receiving. `save_state` doesn't
have a version_id parameter because it always uses the latest version.
This function is called before we load the state of one device. Note that because the VMState macros still save the data in a raw
format, in many cases it's possible to replace legacy code
with a carefully constructed VMState description that matches the
byte layout of the existing code.
- ``int (*post_load)(void *opaque, int version_id);`` Changing migration data structures
----------------------------------
This function is called after we load the state of one device. When we migrate a device, we save/load the state as a series
of fields. Sometimes, due to bugs or new functionality, we need to
- ``int (*pre_save)(void *opaque);`` change the state to store more/different information. Changing the migration
state saved for a device can break migration compatibility unless
This function is called before we save the state of one device. care is taken to use the appropriate techniques. In general QEMU tries
to maintain forward migration compatibility (i.e. migrating from
Example: You can look at hpet.c, that uses the three function to QEMU n->n+1) and there are users who benefit from backward compatibility
massage the state that is transferred. as well.
If you use memory API functions that update memory layout outside
initialization (i.e., in response to a guest action), this is a strong
indication that you need to call these functions in a `post_load` callback.
Examples of such memory API functions are:
- memory_region_add_subregion()
- memory_region_del_subregion()
- memory_region_set_readonly()
- memory_region_set_enabled()
- memory_region_set_address()
- memory_region_set_alias_offset()
Subsections Subsections
----------- -----------
The use of version_id allows to be able to migrate from older versions The most common structure change is adding new data, e.g. when adding
to newer versions of a device. But not the other way around. This a newer form of device, or adding that state that you previously
makes very complicated to fix bugs in stable branches. If we need to forgot to migrate. This is best solved using a subsection.
add anything to the state to fix a bug, we have to disable migration
to older versions that don't have that bug-fix (i.e. a new field).
But sometimes, that bug-fix is only needed sometimes, not always. For A subsection is "like" a device vmstate, but with a particularity, it
instance, if the device is in the middle of a DMA operation, it is has a Boolean function that tells if that values are needed to be sent
using a specific functionality, .... or not. If this functions returns false, the subsection is not sent.
Subsections have a unique name, that is looked for on the receiving
It is impossible to create a way to make migration from any version to side.
any other version to work. But we can do better than only allowing
migration from older versions to newer ones. For that fields that are
only needed sometimes, we add the idea of subsections. A subsection
is "like" a device vmstate, but with a particularity, it has a Boolean
function that tells if that values are needed to be sent or not. If
this functions returns false, the subsection is not sent.
On the receiving side, if we found a subsection for a device that we On the receiving side, if we found a subsection for a device that we
don't understand, we just fail the migration. If we understand all don't understand, we just fail the migration. If we understand all
the subsections, then we load the state with success. the subsections, then we load the state with success. There's no check
that a subsection is loaded, so a newer QEMU that knows about a subsection
can (with care) load a stream from an older QEMU that didn't send
the subsection.
If the new data is only needed in a rare case, then the subsection
can be made conditional on that case and the migration will still
succeed to older QEMUs in most cases. This is OK for data that's
critical, but in some use cases it's preferred that the migration
should succeed even with the data missing. To support this the
subsection can be connected to a device property and from there
to a versioned machine type.
One important note is that the post_load() function is called "after" One important note is that the post_load() function is called "after"
loading all subsections, because a newer subsection could change same loading all subsections, because a newer subsection could change same
value that it uses. value that it uses. A flag, and the combination of pre_load and post_load
can be used to detect whether a subsection was loaded, and to
fall back on default behaviour when the subsection isn't present.
Example: Example:
@ -288,9 +299,13 @@ save/send this state when we are in the middle of a pio operation
not enabled, the values on that fields are garbage and don't need to not enabled, the values on that fields are garbage and don't need to
be sent. be sent.
Connecting subsections to properties
------------------------------------
Using a condition function that checks a 'property' to determine whether Using a condition function that checks a 'property' to determine whether
to send a subsection allows backwards migration compatibility when to send a subsection allows backward migration compatibility when
new subsections are added. new subsections are added, especially when combined with versioned
machine types.
For example: For example:
@ -305,21 +320,7 @@ For example:
Now that subsection will not be generated when using an older Now that subsection will not be generated when using an older
machine type and the migration stream will be accepted by older machine type and the migration stream will be accepted by older
QEMU versions. pre-load functions can be used to initialise state QEMU versions.
on the newer version so that they default to suitable values
when loading streams created by older QEMU versions that do not
generate the subsection.
In some cases subsections are added for data that had been accidentally
omitted by earlier versions; if the missing data causes the migration
process to succeed but the guest to behave badly then it may be better
to send the subsection and cause the migration to explicitly fail
with the unknown subsection error. If the bad behaviour only happens
with certain data values, making the subsection conditional on
the data value (rather than the machine type) allows migrations to succeed
in most cases. In general the preference is to tie the subsection to
the machine type, and allow reliable migrations, unless the behaviour
from omission of the subsection is really bad.
Not sending existing elements Not sending existing elements
----------------------------- -----------------------------
@ -328,9 +329,13 @@ Sometimes members of the VMState are no longer needed:
- removing them will break migration compatibility - removing them will break migration compatibility
- making them version dependent and bumping the version will break backwards migration compatibility. - making them version dependent and bumping the version will break backward migration
compatibility.
The best way is to: Adding a dummy field into the migration stream is normally the best way to preserve
compatibility.
If the field really does need to be removed then:
a) Add a new property/compatibility/function in the same way for subsections above. a) Add a new property/compatibility/function in the same way for subsections above.
b) replace the VMSTATE macro with the _TEST version of the macro, e.g.: b) replace the VMSTATE macro with the _TEST version of the macro, e.g.:
@ -342,18 +347,208 @@ The best way is to:
``VMSTATE_UINT32_TEST(foo, barstruct, pre_version_baz)`` ``VMSTATE_UINT32_TEST(foo, barstruct, pre_version_baz)``
Sometime in the future when we no longer care about the ancient versions these can be killed off. Sometime in the future when we no longer care about the ancient versions these can be killed off.
Note that for backward compatibility it's important to fill in the structure with
data that the destination will understand.
Any difference in the predicates on the source and destination will end up
with different fields being enabled and data being loaded into the wrong
fields; for this reason conditional fields like this are very fragile.
Versions
--------
Version numbers are intended for major incompatible changes to the
migration of a device, and using them breaks backward-migration
compatibility; in general most changes can be made by adding Subsections
(see above) or _TEST macros (see above) which won't break compatibility.
Each version is associated with a series of fields saved. The `save_state` always saves
the state as the newer version. But `load_state` sometimes is able to
load state from an older version.
You can see that there are several version fields:
- `version_id`: the maximum version_id supported by VMState for that device.
- `minimum_version_id`: the minimum version_id that VMState is able to understand
for that device.
- `minimum_version_id_old`: For devices that were not able to port to vmstate, we can
assign a function that knows how to read this old state. This field is
ignored if there is no `load_state_old` handler.
VMState is able to read versions from minimum_version_id to
version_id. And the function ``load_state_old()`` (if present) is able to
load state from minimum_version_id_old to minimum_version_id. This
function is deprecated and will be removed when no more users are left.
There are *_V* forms of many ``VMSTATE_`` macros to load fields for version dependent fields,
e.g.
.. code:: c
VMSTATE_UINT16_V(ip_id, Slirp, 2),
only loads that field for versions 2 and newer.
Saving state will always create a section with the 'version_id' value
and thus can't be loaded by any older QEMU.
Massaging functions
-------------------
Sometimes, it is not enough to be able to save the state directly
from one structure, we need to fill the correct values there. One
example is when we are using kvm. Before saving the cpu state, we
need to ask kvm to copy to QEMU the state that it is using. And the
opposite when we are loading the state, we need a way to tell kvm to
load the state for the cpu that we have just loaded from the QEMUFile.
The functions to do that are inside a vmstate definition, and are called:
- ``int (*pre_load)(void *opaque);``
This function is called before we load the state of one device.
- ``int (*post_load)(void *opaque, int version_id);``
This function is called after we load the state of one device.
- ``int (*pre_save)(void *opaque);``
This function is called before we save the state of one device.
Example: You can look at hpet.c, that uses the three function to
massage the state that is transferred.
The ``VMSTATE_WITH_TMP`` macro may be useful when the migration
data doesn't match the stored device data well; it allows an
intermediate temporary structure to be populated with migration
data and then transferred to the main structure.
If you use memory API functions that update memory layout outside
initialization (i.e., in response to a guest action), this is a strong
indication that you need to call these functions in a `post_load` callback.
Examples of such memory API functions are:
- memory_region_add_subregion()
- memory_region_del_subregion()
- memory_region_set_readonly()
- memory_region_set_enabled()
- memory_region_set_address()
- memory_region_set_alias_offset()
Iterative device migration
--------------------------
Some devices, such as RAM, Block storage or certain platform devices,
have large amounts of data that would mean that the CPUs would be
paused for too long if they were sent in one section. For these
devices an *iterative* approach is taken.
The iterative devices generally don't use VMState macros
(although it may be possible in some cases) and instead use
qemu_put_*/qemu_get_* macros to read/write data to the stream. Specialist
versions exist for high bandwidth IO.
An iterative device must provide:
- A ``save_setup`` function that initialises the data structures and
transmits a first section containing information on the device. In the
case of RAM this transmits a list of RAMBlocks and sizes.
- A ``load_setup`` function that initialises the data structures on the
destination.
- A ``save_live_pending`` function that is called repeatedly and must
indicate how much more data the iterative data must save. The core
migration code will use this to determine when to pause the CPUs
and complete the migration.
- A ``save_live_iterate`` function (called after ``save_live_pending``
when there is significant data still to be sent). It should send
a chunk of data until the point that stream bandwidth limits tell it
to stop. Each call generates one section.
- A ``save_live_complete_precopy`` function that must transmit the
last section for the device containing any remaining data.
- A ``load_state`` function used to load sections generated by
any of the save functions that generate sections.
- ``cleanup`` functions for both save and load that are called
at the end of migration.
Note that the contents of the sections for iterative migration tend
to be open-coded by the devices; care should be taken in parsing
the results and structuring the stream to make them easy to validate.
Device ordering
---------------
There are cases in which the ordering of device loading matters; for
example in some systems where a device may assert an interrupt during loading,
if the interrupt controller is loaded later then it might lose the state.
Some ordering is implicitly provided by the order in which the machine
definition creates devices, however this is somewhat fragile.
The ``MigrationPriority`` enum provides a means of explicitly enforcing
ordering. Numerically higher priorities are loaded earlier.
The priority is set by setting the ``priority`` field of the top level
``VMStateDescription`` for the device.
Stream structure
================
The stream tries to be word and endian agnostic, allowing migration between hosts
of different characteristics running the same VM.
- Header
- Magic
- Version
- VM configuration section
- Machine type
- Target page bits
- List of sections
Each section contains a device, or one iteration of a device save.
- section type
- section id
- ID string (First section of each device)
- instance id (First section of each device)
- version id (First section of each device)
- <device data>
- Footer mark
- EOF mark
- VM Description structure
Consisting of a JSON description of the contents for analysis only
The ``device data`` in each section consists of the data produced
by the code described above. For non-iterative devices they have a single
section; iterative devices have an initial and last section and a set
of parts in between.
Note that there is very little checking by the common code of the integrity
of the ``device data`` contents, that's up to the devices themselves.
The ``footer mark`` provides a little bit of protection for the case where
the receiving side reads more or less data than expected.
The ``ID string`` is normally unique, having been formed from a bus name
and device address, PCI devices and storage devices hung off PCI controllers
fit this pattern well. Some devices are fixed single instances (e.g. "pc-ram").
Others (especially either older devices or system devices which for
some reason don't have a bus concept) make use of the ``instance id``
for otherwise identically named devices.
Return path Return path
----------- -----------
In most migration scenarios there is only a single data path that runs Only a unidirectional stream is required for normal migration, however a
from the source VM to the destination, typically along a single fd (although ``return path`` can be created when bidirectional communication is desired.
possibly with another fd or similar for some fast way of throwing pages across). This is primarily used by postcopy, but is also used to return a success
flag to the source at the end of migration.
However, some uses need two way communication; in particular the Postcopy
destination needs to be able to request pages on demand from the source.
For these scenarios there is a 'return path' from the destination to the source;
``qemu_file_get_return_path(QEMUFile* fwdpath)`` gives the QEMUFile* for the return ``qemu_file_get_return_path(QEMUFile* fwdpath)`` gives the QEMUFile* for the return
path. path.
@ -632,3 +827,28 @@ Retro-fitting postcopy to existing clients is possible:
identified and the implication understood; for example if the identified and the implication understood; for example if the
guest memory access is made while holding a lock then all other guest memory access is made while holding a lock then all other
threads waiting for that lock will also be blocked. threads waiting for that lock will also be blocked.
Firmware
========
Migration migrates the copies of RAM and ROM, and thus when running
on the destination it includes the firmware from the source. Even after
resetting a VM, the old firmware is used. Only once QEMU has been restarted
is the new firmware in use.
- Changes in firmware size can cause changes in the required RAMBlock size
to hold the firmware and thus migration can fail. In practice it's best
to pad firmware images to convenient powers of 2 with plenty of space
for growth.
- Care should be taken with device emulation code so that newer
emulation code can work with older firmware to allow forward migration.
- Care should be taken with newer firmware so that backward migration
to older systems with older device emulation code will work.
In some cases it may be best to tie specific firmware versions to specific
versioned machine types to cut down on the combinations that will need
support. This is also useful when newer versions of firmware outgrow
the padding.