From: Peter Xu <peterx@redhat.com>

Move the two sections into a separate file called "best-practises.rst".
Add the entry into index.

Signed-off-by: Peter Xu <peterx@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

peterx@redhat.com writes:

> From: Peter Xu <peterx@redhat.com>
>
> Move the two sections into a separate file called "best-practises.rst".

s/practises/practices/

On Tue, Jan 09, 2024 at 02:03:04PM -0300, Fabiano Rosas wrote:
> peterx@redhat.com writes:
> 
> > From: Peter Xu <peterx@redhat.com>
> >
> > Move the two sections into a separate file called "best-practises.rst".
> 
> s/practises/practices/

Will fix, thanks.

-- 
Peter Xu

On 1/9/24 07:46, peterx@redhat.com wrote:
> From: Peter Xu <peterx@redhat.com>
> 
> Move the two sections into a separate file called "best-practises.rst".
> Add the entry into index.
> 
> Signed-off-by: Peter Xu <peterx@redhat.com>


Reviewed-by: Cédric Le Goater <clg@redhat.com>

Thanks,

C.


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