Commit bf8156b03d for qemu.org

commit bf8156b03d263a66c00707d38b3f852bd9560fb0
Author: Bin Guo <guobin@linux.alibaba.com>
Date:   Tue Sep 15 14:37:18 2026 +0800

    docs/migration: document that postcopy can be used with multifd

    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>
    Acked-by: Fabiano Rosas <farosas@suse.de>
    Reviewed-by: Peter Xu <peterx@redhat.com>
    Signed-off-by: Fabiano Rosas <farosas@suse.de>

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
 -----------------------------