[PATCH 1/2] docs/migration: document that postcopy can be used with multifd

[Bin Guo <guobin@linux.alibaba.com>]

Since commit e27418861288 ("migration: enable multifd and postcopy
together") in the 10.1 release, the multifd and postcopy-ram capabilities
are no longer mutually exclusive, but the postcopy documentation does not
mention multifd at all, leaving users unaware that the two features can be
combined.

Add a short section describing how they interact: multifd carries the
pages of the precopy phase, the channels are flushed and synced before the
switchover (because loading a page in a multifd receive thread is not
atomic with regard to a running vCPU), and the postcopy phase itself does
not use the multifd channels.

Signed-off-by: Bin Guo <guobin@linux.alibaba.com>
---
 docs/devel/migration/postcopy.rst | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/docs/devel/migration/postcopy.rst b/docs/devel/migration/postcopy.rst
index e319388d8f..570a3a1ce6 100644
--- a/docs/devel/migration/postcopy.rst
+++ b/docs/devel/migration/postcopy.rst
@@ -294,6 +294,32 @@ the background migration channel.  Anyone who cares about latencies of page
 faults during a postcopy migration should enable this feature.  By default,
 it's not enabled.
 
+Postcopy with multifd
+---------------------
+
+The ``multifd`` capability can be enabled together with ``postcopy-ram``
+since the 10.1 QEMU release.  The two features apply to different phases of
+the migration:
+
+  - During the precopy phase, guest pages are sent over the multifd channels
+    as usual, so the initial RAM transfer can use all of them.
+
+  - Just before switching to postcopy, the source flushes and syncs the
+    multifd channels.  This guarantees that all the pages already queued on
+    those channels are loaded on the destination *before* the destination
+    CPUs are started, which is required because loading a page in a multifd
+    receive thread is not atomic with regard to a running vCPU.
+
+  - During the postcopy phase the multifd channels are no longer used for
+    guest pages.  Both the background stream and the pages requested by the
+    destination go through the background migration channel instead, or
+    through the preempt channel for the requested pages when postcopy
+    preemption is enabled.
+
+Consequently, multifd only speeds up the precopy phase of a postcopy
+migration.  The bandwidth available once postcopy has started is the same as
+without multifd.
+
 Postcopy blocktime statistics
 -----------------------------
 
-- 
2.50.1 (Apple Git-155)