devel/migration/main.rst

4 Migration framework
20 requested: migration.  This means that QEMU is able to start in one
24 Next was the "live migration" functionality.  This is important
27 migration allows the guest to continue running while the state is
30 unresponsive during live migration is the low hundred of milliseconds
38 The migration stream is normally just a byte stream that can be passed
41 - tcp migration: do the migration using tcp sockets
42 - unix migration: do the migration using unix sockets
43 - exec migration: do the migration using the stdin/stdout through a process.
44 - fd migration: do the migration using a file descriptor that is
46 - file migration: do the migration using a file that is passed to QEMU
50   data/metadata at the end of migration.
52   The file migration also supports using a file that has already been
55   management application to have control over the migration file
63     - the file must be opened with WRONLY on the migration source side
64       and RDONLY on the migration destination side.
66 - rdma migration: support is included for migration using RDMA, which
69   lower.  While the internals of RDMA migration are a bit different,
70   this isn't really visible outside the RAM migration code.
72 All these migration protocols use the same infrastructure to
79 The files, sockets or fd's that carry the migration stream are abstracted by
80 the  ``QEMUFile`` type (see ``migration/qemu-file.h``).  In most cases this
87 For most devices, the state is saved in a single call to the migration
89 devices is sent at the end of precopy migration, when the CPUs are paused.
96 - The migration state saved should reflect the device being modelled rather
98   later the migration stream will stay compatible.  That model may include
101 - When saving a migration stream the device code may walk and check
105   normal response from users is that *migration broke their VM* since it had
111 - The migration might happen at an inconvenient point,
118 - If you do need to fail a migration, ensure that sufficient information
121 - The destination should treat an incoming migration stream as hostile
123   into buffers and the like can't cause overruns.  Fail the incoming migration
127   migration version dependent.  For example, the order of PCI capabilities
128   is required to stay constant across migration.  Another example would
133   outgoing migration.  Migrations timing out or being failed by
136   Note that the management layer can validly revert the migration
137   even though the QEMU level of migration has succeeded as long as it
151 in ``include/migration/vmstate.h``).
229 Changing migration data structures
234 change the state to store more/different information.  Changing the migration
235 state saved for a device can break migration compatibility unless
237 to maintain forward migration compatibility (i.e. migrating from
255 don't understand, we just fail the migration.  If we understand all
262 can be made conditional on that case and the migration will still
264 critical, but in some use cases it's preferred that the migration
335 to send a subsection allows backward migration compatibility when
351 machine type and the migration stream will be accepted by older
359   - removing them will break migration compatibility
361   - making them version dependent and bumping the version will break backward migration
364 Adding a dummy field into the migration stream is normally the best way to preserve
390 migration of a device, and using them breaks backward-migration
450 The ``VMSTATE_WITH_TMP`` macro may be useful when the migration
452 intermediate temporary structure to be populated with migration
476 Iterative device migration
500     data we must save.  The core migration code will use this to
501     determine when to pause the CPUs and complete the migration.
518     at the end of migration.
520 Note that the contents of the sections for iterative migration tend
542 The stream tries to be word and endian agnostic, allowing migration between hosts
586 Only a unidirectional stream is required for normal migration, however a
589 flag to the source at the end of migration.
596      Forward path - written by migration thread