devel/migration/main.rst

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
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
64       and RDONLY on the migration destination side.
66 - rdma migration: support is included for migration using RDMA, which
80 the  ``QEMUFile`` type (see ``migration/qemu-file.h``).  In most cases this
88 infrastructure; these are *non-iterative* devices.  The data for these
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
132 - The state of the source should not be changed or destroyed by the
134   higher levels of management, or failures of the destination host are
138   does it before starting execution on the destination.
140 - Buses and devices should be able to explicitly specify addresses when
144   may be different on the destination.  This can result in the
148 -------
187     dc->vmsd = &vmstate_kbd_isa;
203 ----------
230 ----------------------------------
238 QEMU n->n+1) and there are users who benefit from backward compatibility
242 -----------
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
355 -----------------------------
359   - removing them will break migration compatibility
361   - making them version dependent and bumping the version will break backward migration
380    data that the destination will understand.
382 Any difference in the predicates on the source and destination will end up
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 --------------------------
492   - A ``save_setup`` function that initialises the data structures and
496   - A ``load_setup`` function that initialises the data structures on the
497     destination.
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 ---------------
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
578 fit this pattern well.  Some devices are fixed single instances (e.g. "pc-ram").
584 -----------
596      Forward path - written by migration thread
597      Return path  - opened by main thread, read by return-path thread
599   Destination side
601      Forward path - read by main thread
602      Return path  - opened by main thread, written by main thread AND postcopy