Merge tag 'migration-20240116-pull-request' of https://gitlab.com/peterx/qemu into staging

Migration pull request 2nd batch for 9.0

- Het's cleanup on migration qmp command paths
- Fabiano's migration cleanups and test improvements
- Fabiano's patch to re-enable multifd-cancel test
- Peter's migration doc reorganizations
- Nick Briggs's fix for Solaries build on rdma

# -----BEGIN PGP SIGNATURE-----
#
# iIgEABYKADAWIQS5GE3CDMRX2s990ak7X8zN86vXBgUCZaX1PhIccGV0ZXJ4QHJl
# ZGhhdC5jb20ACgkQO1/MzfOr1wZSzwEAq6sp/ylNHLzNoMdWL28JLqCsb4DPYH2i
# u7XgYgT1qDAA/0vwoe4a5uFn1aaGCS+2d2syjJ8kOE7h+eZrbK520jsA
# =1zUG
# -----END PGP SIGNATURE-----
# gpg: Signature made Tue 16 Jan 2024 03:17:18 GMT
# gpg:                using EDDSA key B9184DC20CC457DACF7DD1A93B5FCCCDF3ABD706
# gpg:                issuer "peterx@redhat.com"
# gpg: Good signature from "Peter Xu <xzpeter@gmail.com>" [marginal]
# gpg:                 aka "Peter Xu <peterx@redhat.com>" [marginal]
# gpg: WARNING: This key is not certified with sufficiently trusted signatures!
# gpg:          It is not certain that the signature belongs to the owner.
# Primary key fingerprint: B918 4DC2 0CC4 57DA CF7D  D1A9 3B5F CCCD F3AB D706

* tag 'migration-20240116-pull-request' of https://gitlab.com/peterx/qemu:
  migration/rdma: define htonll/ntohll only if not predefined
  docs/migration: Further move virtio to be feature of migration
  docs/migration: Further move vfio to be feature of migration
  docs/migration: Organize "Postcopy" page
  docs/migration: Split "dirty limit"
  docs/migration: Split "Postcopy"
  docs/migration: Split "Debugging" and "Firmware"
  docs/migration: Split "Backwards compatibility" separately
  docs/migration: Convert virtio.txt into rST
  docs/migration: Create index page
  docs/migration: Create migration/ directory
  tests/qtest: Re-enable multifd cancel test
  tests/qtest/migration: Use the new migration_test_add
  tests/qtest/migration: Add a wrapper to print test names
  tests/qtest/migration: Print migration incoming errors
  migration: Report error in incoming migration
  migration/multifd: Change multifd_pages_init argument
  migration/multifd: Remove QEMUFile from where it is not needed
  migration/multifd: Remove MultiFDPages_t::packet_num
  migration: Simplify initial conditionals in migration for better readability

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>

1 files changed, 48 insertions, 0 deletions

diff --git a/docs/devel/migration/best-practices.rst b/docs/devel/migration/best-practices.rst
new file mode 100644
index 0000000000..d7c34a3014
--- /dev/null
+++ b/docs/devel/migration/best-practices.rst
@@ -0,0 +1,48 @@
+==============
+Best practices
+==============
+
+Debugging
+=========
+
+The migration stream can be analyzed thanks to ``scripts/analyze-migration.py``.
+
+Example usage:
+
+.. code-block:: shell
+
+  $ qemu-system-x86_64 -display none -monitor stdio
+  (qemu) migrate "exec:cat > mig"
+  (qemu) q
+  $ ./scripts/analyze-migration.py -f mig
+  {
+    "ram (3)": {
+        "section sizes": {
+            "pc.ram": "0x0000000008000000",
+  ...
+
+See also ``analyze-migration.py -h`` help for more options.
+
+Firmware
+========
+
+Migration migrates the copies of RAM and ROM, and thus when running
+on the destination it includes the firmware from the source. Even after
+resetting a VM, the old firmware is used.  Only once QEMU has been restarted
+is the new firmware in use.
+
+- Changes in firmware size can cause changes in the required RAMBlock size
+  to hold the firmware and thus migration can fail.  In practice it's best
+  to pad firmware images to convenient powers of 2 with plenty of space
+  for growth.
+
+- Care should be taken with device emulation code so that newer
+  emulation code can work with older firmware to allow forward migration.
+
+- Care should be taken with newer firmware so that backward migration
+  to older systems with older device emulation code will work.
+
+In some cases it may be best to tie specific firmware versions to specific
+versioned machine types to cut down on the combinations that will need
+support.  This is also useful when newer versions of firmware outgrow
+the padding.