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.0peterx@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.
© 2016 - 2024 Red Hat, Inc.