From: Peter Xu <pet...@redhat.com>
Move the two sections into a separate file called "best-practises.rst".
Add the entry into index.
Signed-off-by: Peter Xu <pet...@redhat.com>
---
docs/devel/migration/best-practises.rst | 48 +++++++++++++++++++++++++
docs/devel/migration/index.rst | 1 +
docs/devel/migration/main.rst | 44 -----------------------
3 files changed, 49 insertions(+), 44 deletions(-)
create mode 100644 docs/devel/migration/best-practises.rst
diff --git a/docs/devel/migration/best-practises.rst
b/docs/devel/migration/best-practises.rst
new file mode 100644
index 0000000000..ba122ae417
--- /dev/null
+++ b/docs/devel/migration/best-practises.rst
@@ -0,0 +1,48 @@
+==============
+Best practises
+==============
+
+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.
diff --git a/docs/devel/migration/index.rst b/docs/devel/migration/index.rst
index 7fc02b9520..c09623b38f 100644
--- a/docs/devel/migration/index.rst
+++ b/docs/devel/migration/index.rst
@@ -11,3 +11,4 @@ QEMU live migration works.
compatibility
vfio
virtio
+ best-practises
diff --git a/docs/devel/migration/main.rst b/docs/devel/migration/main.rst
index b3e31bb52f..97811ce371 100644
--- a/docs/devel/migration/main.rst
+++ b/docs/devel/migration/main.rst
@@ -52,27 +52,6 @@ All these migration protocols use the same infrastructure to
save/restore state devices. This infrastructure is shared with the
savevm/loadvm functionality.
-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.
-
Common infrastructure
=====================
@@ -970,26 +949,3 @@ 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.
-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.
--
2.41.0
