[Qemu-devel] [PATCH 5/6] migration/announce: Document self-announce mechanism

[Dr. David Alan Gilbert (git)]

From: "Dr. David Alan Gilbert" <address@hidden>

Explain the timings and differences between the ARP and RARP
streams we send.

Signed-off-by: Dr. David Alan Gilbert <address@hidden>
---
 docs/migration.txt | 40 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/docs/migration.txt b/docs/migration.txt
index 1b940a8..6f939e1 100644
--- a/docs/migration.txt
+++ b/docs/migration.txt
@@ -553,3 +553,43 @@ Postcopy now works with hugetlbfs backed memory:
      hugepages works well, however 1GB hugepages are likely to be problematic
      since it takes ~1 second to transfer a 1GB hugepage across a 10Gbps link,
      and until the full page is transferred the destination thread is blocked.
+
+== Network self announce ==
+
+At the end of a migration QEMU sends a sequence of packets to 'announce' the 
VMs
+arrival on the new host in the hope that the L2 network will notice and start
+sending the packets to it.  This, 'self-announce' is split into two parts that
+happens at slightly different times:
+
+  a) RARP - a RARP sequence is sent when the last of the device data has been
+     received but before the guest CPUs are started.  Note that when -S is used
+     to stop QEMU starting the CPUs automatically, the RARPs are still sent
+     at the point where the device data is received and the guest CPUs are 
ready
+     to be started.
+
+  b) ARPs - for guests with virtio NICs and drivers new enough to support the
+     GUEST_ANNOUNCE feature, the guests are told to emit gratuitous ARPs just
+     after the guest CPUs are started after an incoming migration. Note the
+     packets are generated by the guest itself and have the advantage of 
knowing
+     the guests IP address.
+
+The two sets may overlap.
+
+In both cases a stream of packets are sent, the number and timing can be
+configured using the announce* migration parameters, which must be set prior
+to the end of the incoming migration.
+
+    <P> di <P> di+ds <P> di+2*ds <P> ..... <P>
+
+  'announce-rounds' packets are sent.
+  The gap between the 1st and 2nd packet is 'announce-initial'.
+  The gap between the 2nd and 3rd packet is increased by 'announce-step'
+  A maximum can be set such that the gap between subsequent packets stops
+  increasing.
+
+  The default is:
+   <P> 50ms <P> 150ms <P> 250ms <P> 350ms <P>
+
+Some complex network systems may take longer than this to reconfigure
+and thus it may be useful to increase the count or delays.
+
-- 
2.9.3