devel/migration/main.rst

5 QEMU has code to load/save the state of the guest that it is running.
7 that, saves the state for each device that the guest is running.
12 two times.  I.e. it can only restore the state in one guest that has
13 the same devices that the one it was saved (this last requirement can
14 be relaxed a bit, but for now we can consider that configuration has
17 Once that we are able to save/restore a guest, a new functionality is
18 requested: migration.  This means that QEMU is able to start in one
27 the guest to be stopped.  Typically the time that the guest is
29 (notice that this depends on a lot of things).
36 The migration stream is normally just a byte stream that can be passed
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
47   QEMU interference. Note that QEMU does not flush cached file
50   The file migration also supports using a file that has already been
57     - the fdset must contain two file descriptors that are not
77 The files, sockets or fd's that carry the migration stream are abstracted by
95   than the way your implementation works.  That way if you change the implementation
96   later the migration stream will stay compatible.  That model may include
97   internal state that's not directly visible in a register.
101   discovering internal state is corrupt or that the guest has done something bad).
103   normal response from users is that *migration broke their VM* since it had
112   It's strongly preferred that migrations do not fail in this situation,
114   VMs that the administrator doesn't directly control.
116 - If you do need to fail a migration, ensure that sufficient information
120   (which we do to varying degrees in the existing code).  Check that offsets
124 - Take care with internal device state or behaviour that might become
127   be that a special case handled by subsections (see below) might become
133   not unusual, and in that case the VM is restarted on the source.
134   Note that the management layer can validly revert the migration
173 have an id that is different for each instance of the device:
180 For devices that are ``qdev`` based, we can register the device in the class
187 The VMState macros take care of ensuring that the device data section
196 Note that the format on the wire is still very raw; i.e. a VMSTATE_UINT32
218 and ``load_state`` functions.  Notice that ``load_state`` receives a version_id
222 Note that because the VMState macros still save the data in a raw
224 with a carefully constructed VMState description that matches the
243 a newer form of device, or adding that state that you previously
247 has a Boolean function that tells if that values are needed to be sent
249 Subsections have a unique name, that is looked for on the receiving
252 On the receiving side, if we found a subsection for a device that we
255 that a subsection is loaded, so a newer QEMU that knows about a subsection
256 can (with care) load a stream from an older QEMU that didn't send
260 can be made conditional on that case and the migration will still
261 succeed to older QEMUs in most cases.  This is OK for data that's
262 critical, but in some use cases it's preferred that the migration
270 One important note is that the outer post_load() function is called "after"
272 value that it uses.  A flag, and the combination of outer pre_load and
325 (that is what ``ide_drive_pio_state_needed()`` checks).  If DRQ_STAT is
326 not enabled, the values on that fields are garbage and don't need to
332 Using a condition function that checks a 'property' to determine whether
341    b) Add an entry to the ``hw_compat_`` for the previous version that sets
343    c) Add a static bool  support_foo function that tests the property.
345    e) (potentially) Add an outer pre_load that sets up a default value
348 Now that subsection will not be generated when using an older
377    Note that for backward compatibility it's important to fill in the structure with
378    data that the destination will understand.
396 You can see that there are two version fields:
398 - ``version_id``: the maximum version_id supported by VMState for that device.
399 - ``minimum_version_id``: the minimum version_id that VMState is able to understand
400   for that device.
411 only loads that field for versions 2 and newer.
422 need to ask kvm to copy to QEMU the state that it is using.  And the
424 load the state for the cpu that we have just loaded from the QEMUFile.
426 The functions to do that are inside a vmstate definition, and are called:
445 Example: You can look at hpet.c, that uses the first three functions
446 to massage the state that is transferred.
453 If you use memory or portio_list API functions that update memory layout outside
455 indication that you need to call these functions in a ``post_load`` callback.
470 callbacks. (For instance, don't do anything that calls ``update_irq()``
478 have large amounts of data that would mean that the CPUs would be
490   - A ``save_setup`` function that initialises the data structures and
494   - A ``load_setup`` function that initialises the data structures on the
497   - A ``state_pending_exact`` function that indicates how much more
501   - A ``state_pending_estimate`` function that indicates how much more
506     the point that stream bandwidth limits tell it to stop.  Each call
509   - A ``save_live_complete_precopy`` function that must transmit the
513     any of the save functions that generate sections.
515   - ``cleanup`` functions for both save and load that are called
518 Note that the contents of the sections for iterative migration tend
569 Note that there is very little checking by the common code of the integrity
570 of the ``device data`` contents, that's up to the devices themselves.