devel/migration/main.rst

15 the same devices that the one it was saved (this last requirement can
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
48   application to add its own metadata to the start of the file without
54   (see add-fd QMP command documentation). This method allows a
59     - the fdset must contain two file descriptors that are not
61     - if the direct-io capability is to be used, exactly one of the
63     - the file must be opened with WRONLY on the migration source side
66 - rdma migration: support is included for migration using RDMA, which
73 save/restore state devices.  This infrastructure is shared with the
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
88 infrastructure; these are *non-iterative* devices.  The data for these
89 devices is sent at the end of precopy migration, when the CPUs are paused.
90 There are also *iterative* devices, which contain a very large amount of
94 ------------------------------------
96 - The migration state saved should reflect the device being modelled rather
101 - When saving a migration stream the device code may walk and check
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
126 - Take care with internal device state or behaviour that might become
130   much more common if a default behaviour is changed.
132 - The state of the source should not be changed or destroyed by the
140 - Buses and devices should be able to explicitly specify addresses when
142   when hot adding USB devices it's important to specify the ports
148 -------
182 For devices that are ``qdev`` based, we can register the device in the class
187     dc->vmsd = &vmstate_kbd_isa;
203 ----------
230 ----------------------------------
238 QEMU n->n+1) and there are users who benefit from backward compatibility
242 -----------
276 fall back on default behaviour when the subsection isn't present.
286       return ((s->status & DRQ_STAT) != 0)
287           || (s->bus->error_status & BM_STATUS_PIO_RETRY);
332 ------------------------------------
341    a) Add a new property using ``DEFINE_PROP_BOOL`` - e.g. support-foo and
342       default it to true.
347    e) (potentially) Add an outer pre_load that sets up a default value
355 -----------------------------
359   - removing them will break migration compatibility
361   - making them version dependent and bumping the version will break backward migration
387 --------
390 migration of a device, and using them breaks backward-migration
400 - ``version_id``: the maximum version_id supported by VMState for that device.
401 - ``minimum_version_id``: the minimum version_id that VMState is able to understand
419 -------------------
430 - ``int (*pre_load)(void *opaque);``
434 - ``int (*post_load)(void *opaque, int version_id);``
438 - ``int (*pre_save)(void *opaque);``
442 - ``int (*post_save)(void *opaque);``
460   - memory_region_add_subregion()
461   - memory_region_del_subregion()
462   - memory_region_set_readonly()
463   - memory_region_set_nonvolatile()
464   - memory_region_set_enabled()
465   - memory_region_set_address()
466   - memory_region_set_alias_offset()
467   - portio_list_set_address()
468   - portio_list_set_enabled()
477 --------------------------
479 Some devices, such as RAM or certain platform devices,
482 devices an *iterative* approach is taken.
484 The iterative devices generally don't use VMState macros
492   - A ``save_setup`` function that initialises the data structures and
496   - A ``load_setup`` function that initialises the data structures on the
499   - A ``state_pending_exact`` function that indicates how much more
503   - A ``state_pending_estimate`` function that indicates how much more
507   - A ``save_live_iterate`` function should send a chunk of data until
511   - A ``save_live_complete_precopy`` function that must transmit the
514   - A ``load_state`` function used to load sections generated by
517   - ``cleanup`` functions for both save and load that are called
521 to be open-coded by the devices; care should be taken in parsing
525 ---------------
532 definition creates devices, however this is somewhat fragile.
545   - Header
547     - Magic
548     - Version
549     - VM configuration section
551        - Machine type
552        - Target page bits
553   - List of sections
556     - section type
557     - section id
558     - ID string (First section of each device)
559     - instance id (First section of each device)
560     - version id (First section of each device)
561     - <device data>
562     - Footer mark
563   - EOF mark
564   - VM Description structure
568 by the code described above.  For non-iterative devices they have a single
569 section; iterative devices have an initial and last section and a set
572 of the ``device data`` contents, that's up to the devices themselves.
577 and device address, PCI devices and storage devices hung off PCI controllers
578 fit this pattern well.  Some devices are fixed single instances (e.g. "pc-ram").
579 Others (especially either older devices or system devices which for
581 for otherwise identically named devices.
584 -----------
596      Forward path - written by migration thread
597      Return path  - opened by main thread, read by return-path thread
601      Forward path - read by main thread
602      Return path  - opened by main thread, written by main thread AND postcopy