[05/10] docs/migration: Split "Debugging" and "Firmware"

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

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.

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.