docs/devel/migration/best-practices.rst

   1 ==============
   2 Best practices
   3 ==============
   4
   5 Debugging
   6 =========
   7
   8 The migration stream can be analyzed thanks to ``scripts/analyze-migration.py``.
   9
  10 Example usage:
  11
  12 .. code-block:: shell
  13
  14   $ qemu-system-x86_64 -display none -monitor stdio
  15   (qemu) migrate "exec:cat > mig"
  16   (qemu) q
  17   $ ./scripts/analyze-migration.py -f mig
  18   {
  19     "ram (3)": {
  20         "section sizes": {
  21             "pc.ram": "0x0000000008000000",
  22   ...
  23
  24 See also ``analyze-migration.py -h`` help for more options.
  25
  26 Firmware
  27 ========
  28
  29 Migration migrates the copies of RAM and ROM, and thus when running
  30 on the destination it includes the firmware from the source. Even after
  31 resetting a VM, the old firmware is used.  Only once QEMU has been restarted
  32 is the new firmware in use.
  33
  34 - Changes in firmware size can cause changes in the required RAMBlock size
  35   to hold the firmware and thus migration can fail.  In practice it's best
  36   to pad firmware images to convenient powers of 2 with plenty of space
  37   for growth.
  38
  39 - Care should be taken with device emulation code so that newer
  40   emulation code can work with older firmware to allow forward migration.
  41
  42 - Care should be taken with newer firmware so that backward migration
  43   to older systems with older device emulation code will work.
  44
  45 In some cases it may be best to tie specific firmware versions to specific
  46 versioned machine types to cut down on the combinations that will need
  47 support.  This is also useful when newer versions of firmware outgrow
  48 the padding.