devel/migration/main.rst

2 Migration framework
18 requested: migration.  This means that QEMU is able to start in one
22 Next was the "live migration" functionality.  This is important
25 migration allows the guest to continue running while the state is
28 unresponsive during live migration is the low hundred of milliseconds
36 The migration stream is normally just a byte stream that can be passed
39 - tcp migration: do the migration using tcp sockets
40 - unix migration: do the migration using unix sockets
41 - exec migration: do the migration using the stdin/stdout through a process.
42 - fd migration: do the migration using a file descriptor that is
44 - file migration: do the migration using a file that is passed to QEMU
48   data/metadata at the end of migration.
50   The file migration also supports using a file that has already been
53   management application to have control over the migration file
61     - the file must be opened with WRONLY on the migration source side
62       and RDONLY on the migration destination side.
64 - rdma migration: support is included for migration using RDMA, which
67   lower.  While the internals of RDMA migration are a bit different,
68   this isn't really visible outside the RAM migration code.
70 All these migration protocols use the same infrastructure to
77 The files, sockets or fd's that carry the migration stream are abstracted by
78 the  ``QEMUFile`` type (see ``migration/qemu-file.h``).  In most cases this
85 For most devices, the state is saved in a single call to the migration
87 devices is sent at the end of precopy migration, when the CPUs are paused.
94 - The migration state saved should reflect the device being modelled rather
96   later the migration stream will stay compatible.  That model may include
99 - When saving a migration stream the device code may walk and check
103   normal response from users is that *migration broke their VM* since it had
109 - The migration might happen at an inconvenient point,
116 - If you do need to fail a migration, ensure that sufficient information
119 - The destination should treat an incoming migration stream as hostile
121   into buffers and the like can't cause overruns.  Fail the incoming migration
125   migration version dependent.  For example, the order of PCI capabilities
126   is required to stay constant across migration.  Another example would
131   outgoing migration.  Migrations timing out or being failed by
134   Note that the management layer can validly revert the migration
135   even though the QEMU level of migration has succeeded as long as it
149 in ``include/migration/vmstate.h``).
227 Changing migration data structures
232 change the state to store more/different information.  Changing the migration
233 state saved for a device can break migration compatibility unless
235 to maintain forward migration compatibility (i.e. migrating from
253 don't understand, we just fail the migration.  If we understand all
260 can be made conditional on that case and the migration will still
262 critical, but in some use cases it's preferred that the migration
333 to send a subsection allows backward migration compatibility when
349 machine type and the migration stream will be accepted by older
357   - removing them will break migration compatibility
359   - making them version dependent and bumping the version will break backward migration
362 Adding a dummy field into the migration stream is normally the best way to preserve
388 migration of a device, and using them breaks backward-migration
448 The ``VMSTATE_WITH_TMP`` macro may be useful when the migration
450 intermediate temporary structure to be populated with migration
474 Iterative device migration
498     data we must save.  The core migration code will use this to
499     determine when to pause the CPUs and complete the migration.
516     at the end of migration.
518 Note that the contents of the sections for iterative migration tend
540 The stream tries to be word and endian agnostic, allowing migration between hosts
584 Only a unidirectional stream is required for normal migration, however a
587 flag to the source at the end of migration.
594      Forward path - written by migration thread