From: Peter Xu <peterx@redhat.com>
Convert the plain old .txt into .rst, add it into migration/index.rst.
Signed-off-by: Peter Xu <peterx@redhat.com>
---
docs/devel/migration/index.rst | 1 +
docs/devel/migration/virtio.rst | 115 ++++++++++++++++++++++++++++++++
docs/devel/migration/virtio.txt | 108 ------------------------------
3 files changed, 116 insertions(+), 108 deletions(-)
create mode 100644 docs/devel/migration/virtio.rst
delete mode 100644 docs/devel/migration/virtio.txt
diff --git a/docs/devel/migration/index.rst b/docs/devel/migration/index.rst
index 02cfdcc969..2cb701c77c 100644
--- a/docs/devel/migration/index.rst
+++ b/docs/devel/migration/index.rst
@@ -9,3 +9,4 @@ QEMU live migration works.
main
vfio
+ virtio
diff --git a/docs/devel/migration/virtio.rst b/docs/devel/migration/virtio.rst
new file mode 100644
index 0000000000..611a18b821
--- /dev/null
+++ b/docs/devel/migration/virtio.rst
@@ -0,0 +1,115 @@
+=======================
+Virtio device migration
+=======================
+
+Copyright 2015 IBM Corp.
+
+This work is licensed under the terms of the GNU GPL, version 2 or later. See
+the COPYING file in the top-level directory.
+
+Saving and restoring the state of virtio devices is a bit of a twisty maze,
+for several reasons:
+
+- state is distributed between several parts:
+
+ - virtio core, for common fields like features, number of queues, ...
+
+ - virtio transport (pci, ccw, ...), for the different proxy devices and
+ transport specific state (msix vectors, indicators, ...)
+
+ - virtio device (net, blk, ...), for the different device types and their
+ state (mac address, request queue, ...)
+
+- most fields are saved via the stream interface; subsequently, subsections
+ have been added to make cross-version migration possible
+
+This file attempts to document the current procedure and point out some
+caveats.
+
+Save state procedure
+====================
+
+::
+
+ virtio core virtio transport virtio device
+ ----------- ---------------- -------------
+
+ save() function registered
+ via VMState wrapper on
+ device class
+ virtio_save() <----------
+ ------> save_config()
+ - save proxy device
+ - save transport-specific
+ device fields
+ - save common device
+ fields
+ - save common virtqueue
+ fields
+ ------> save_queue()
+ - save transport-specific
+ virtqueue fields
+ ------> save_device()
+ - save device-specific
+ fields
+ - save subsections
+ - device endianness,
+ if changed from
+ default endianness
+ - 64 bit features, if
+ any high feature bit
+ is set
+ - virtio-1 virtqueue
+ fields, if VERSION_1
+ is set
+
+Load state procedure
+====================
+
+::
+
+ virtio core virtio transport virtio device
+ ----------- ---------------- -------------
+
+ load() function registered
+ via VMState wrapper on
+ device class
+ virtio_load() <----------
+ ------> load_config()
+ - load proxy device
+ - load transport-specific
+ device fields
+ - load common device
+ fields
+ - load common virtqueue
+ fields
+ ------> load_queue()
+ - load transport-specific
+ virtqueue fields
+ - notify guest
+ ------> load_device()
+ - load device-specific
+ fields
+ - load subsections
+ - device endianness
+ - 64 bit features
+ - virtio-1 virtqueue
+ fields
+ - sanitize endianness
+ - sanitize features
+ - virtqueue index sanity
+ check
+ - feature-dependent setup
+
+Implications of this setup
+==========================
+
+Devices need to be careful in their state processing during load: The
+load_device() procedure is invoked by the core before subsections have
+been loaded. Any code that depends on information transmitted in subsections
+therefore has to be invoked in the device's load() function _after_
+virtio_load() returned (like e.g. code depending on features).
+
+Any extension of the state being migrated should be done in subsections
+added to the core for compatibility reasons. If transport or device specific
+state is added, core needs to invoke a callback from the new subsection.
diff --git a/docs/devel/migration/virtio.txt b/docs/devel/migration/virtio.txt
deleted file mode 100644
index 98a6b0ffb5..0000000000
--- a/docs/devel/migration/virtio.txt
+++ /dev/null
@@ -1,108 +0,0 @@
-Virtio devices and migration
-============================
-
-Copyright 2015 IBM Corp.
-
-This work is licensed under the terms of the GNU GPL, version 2 or later. See
-the COPYING file in the top-level directory.
-
-Saving and restoring the state of virtio devices is a bit of a twisty maze,
-for several reasons:
-- state is distributed between several parts:
- - virtio core, for common fields like features, number of queues, ...
- - virtio transport (pci, ccw, ...), for the different proxy devices and
- transport specific state (msix vectors, indicators, ...)
- - virtio device (net, blk, ...), for the different device types and their
- state (mac address, request queue, ...)
-- most fields are saved via the stream interface; subsequently, subsections
- have been added to make cross-version migration possible
-
-This file attempts to document the current procedure and point out some
-caveats.
-
-
-Save state procedure
-====================
-
-virtio core virtio transport virtio device
------------ ---------------- -------------
-
- save() function registered
- via VMState wrapper on
- device class
-virtio_save() <----------
- ------> save_config()
- - save proxy device
- - save transport-specific
- device fields
-- save common device
- fields
-- save common virtqueue
- fields
- ------> save_queue()
- - save transport-specific
- virtqueue fields
- ------> save_device()
- - save device-specific
- fields
-- save subsections
- - device endianness,
- if changed from
- default endianness
- - 64 bit features, if
- any high feature bit
- is set
- - virtio-1 virtqueue
- fields, if VERSION_1
- is set
-
-
-Load state procedure
-====================
-
-virtio core virtio transport virtio device
------------ ---------------- -------------
-
- load() function registered
- via VMState wrapper on
- device class
-virtio_load() <----------
- ------> load_config()
- - load proxy device
- - load transport-specific
- device fields
-- load common device
- fields
-- load common virtqueue
- fields
- ------> load_queue()
- - load transport-specific
- virtqueue fields
-- notify guest
- ------> load_device()
- - load device-specific
- fields
-- load subsections
- - device endianness
- - 64 bit features
- - virtio-1 virtqueue
- fields
-- sanitize endianness
-- sanitize features
-- virtqueue index sanity
- check
- - feature-dependent setup
-
-
-Implications of this setup
-==========================
-
-Devices need to be careful in their state processing during load: The
-load_device() procedure is invoked by the core before subsections have
-been loaded. Any code that depends on information transmitted in subsections
-therefore has to be invoked in the device's load() function _after_
-virtio_load() returned (like e.g. code depending on features).
-
-Any extension of the state being migrated should be done in subsections
-added to the core for compatibility reasons. If transport or device specific
-state is added, core needs to invoke a callback from the new subsection.
--
2.41.0On 1/9/24 07:46, peterx@redhat.com wrote: > From: Peter Xu <peterx@redhat.com> > > Convert the plain old .txt into .rst, add it into migration/index.rst. > > Signed-off-by: Peter Xu <peterx@redhat.com> Reviewed-by: Cédric Le Goater <clg@redhat.com> Thanks, C. > --- > docs/devel/migration/index.rst | 1 + > docs/devel/migration/virtio.rst | 115 ++++++++++++++++++++++++++++++++ > docs/devel/migration/virtio.txt | 108 ------------------------------ > 3 files changed, 116 insertions(+), 108 deletions(-) > create mode 100644 docs/devel/migration/virtio.rst > delete mode 100644 docs/devel/migration/virtio.txt > > diff --git a/docs/devel/migration/index.rst b/docs/devel/migration/index.rst > index 02cfdcc969..2cb701c77c 100644 > --- a/docs/devel/migration/index.rst > +++ b/docs/devel/migration/index.rst > @@ -9,3 +9,4 @@ QEMU live migration works. > > main > vfio > + virtio > diff --git a/docs/devel/migration/virtio.rst b/docs/devel/migration/virtio.rst > new file mode 100644 > index 0000000000..611a18b821 > --- /dev/null > +++ b/docs/devel/migration/virtio.rst > @@ -0,0 +1,115 @@ > +======================= > +Virtio device migration > +======================= > + > +Copyright 2015 IBM Corp. > + > +This work is licensed under the terms of the GNU GPL, version 2 or later. See > +the COPYING file in the top-level directory. > + > +Saving and restoring the state of virtio devices is a bit of a twisty maze, > +for several reasons: > + > +- state is distributed between several parts: > + > + - virtio core, for common fields like features, number of queues, ... > + > + - virtio transport (pci, ccw, ...), for the different proxy devices and > + transport specific state (msix vectors, indicators, ...) > + > + - virtio device (net, blk, ...), for the different device types and their > + state (mac address, request queue, ...) > + > +- most fields are saved via the stream interface; subsequently, subsections > + have been added to make cross-version migration possible > + > +This file attempts to document the current procedure and point out some > +caveats. > + > +Save state procedure > +==================== > + > +:: > + > + virtio core virtio transport virtio device > + ----------- ---------------- ------------- > + > + save() function registered > + via VMState wrapper on > + device class > + virtio_save() <---------- > + ------> save_config() > + - save proxy device > + - save transport-specific > + device fields > + - save common device > + fields > + - save common virtqueue > + fields > + ------> save_queue() > + - save transport-specific > + virtqueue fields > + ------> save_device() > + - save device-specific > + fields > + - save subsections > + - device endianness, > + if changed from > + default endianness > + - 64 bit features, if > + any high feature bit > + is set > + - virtio-1 virtqueue > + fields, if VERSION_1 > + is set > + > +Load state procedure > +==================== > + > +:: > + > + virtio core virtio transport virtio device > + ----------- ---------------- ------------- > + > + load() function registered > + via VMState wrapper on > + device class > + virtio_load() <---------- > + ------> load_config() > + - load proxy device > + - load transport-specific > + device fields > + - load common device > + fields > + - load common virtqueue > + fields > + ------> load_queue() > + - load transport-specific > + virtqueue fields > + - notify guest > + ------> load_device() > + - load device-specific > + fields > + - load subsections > + - device endianness > + - 64 bit features > + - virtio-1 virtqueue > + fields > + - sanitize endianness > + - sanitize features > + - virtqueue index sanity > + check > + - feature-dependent setup > + > +Implications of this setup > +========================== > + > +Devices need to be careful in their state processing during load: The > +load_device() procedure is invoked by the core before subsections have > +been loaded. Any code that depends on information transmitted in subsections > +therefore has to be invoked in the device's load() function _after_ > +virtio_load() returned (like e.g. code depending on features). > + > +Any extension of the state being migrated should be done in subsections > +added to the core for compatibility reasons. If transport or device specific > +state is added, core needs to invoke a callback from the new subsection. > diff --git a/docs/devel/migration/virtio.txt b/docs/devel/migration/virtio.txt > deleted file mode 100644 > index 98a6b0ffb5..0000000000 > --- a/docs/devel/migration/virtio.txt > +++ /dev/null > @@ -1,108 +0,0 @@ > -Virtio devices and migration > -============================ > - > -Copyright 2015 IBM Corp. > - > -This work is licensed under the terms of the GNU GPL, version 2 or later. See > -the COPYING file in the top-level directory. > - > -Saving and restoring the state of virtio devices is a bit of a twisty maze, > -for several reasons: > -- state is distributed between several parts: > - - virtio core, for common fields like features, number of queues, ... > - - virtio transport (pci, ccw, ...), for the different proxy devices and > - transport specific state (msix vectors, indicators, ...) > - - virtio device (net, blk, ...), for the different device types and their > - state (mac address, request queue, ...) > -- most fields are saved via the stream interface; subsequently, subsections > - have been added to make cross-version migration possible > - > -This file attempts to document the current procedure and point out some > -caveats. > - > - > -Save state procedure > -==================== > - > -virtio core virtio transport virtio device > ------------ ---------------- ------------- > - > - save() function registered > - via VMState wrapper on > - device class > -virtio_save() <---------- > - ------> save_config() > - - save proxy device > - - save transport-specific > - device fields > -- save common device > - fields > -- save common virtqueue > - fields > - ------> save_queue() > - - save transport-specific > - virtqueue fields > - ------> save_device() > - - save device-specific > - fields > -- save subsections > - - device endianness, > - if changed from > - default endianness > - - 64 bit features, if > - any high feature bit > - is set > - - virtio-1 virtqueue > - fields, if VERSION_1 > - is set > - > - > -Load state procedure > -==================== > - > -virtio core virtio transport virtio device > ------------ ---------------- ------------- > - > - load() function registered > - via VMState wrapper on > - device class > -virtio_load() <---------- > - ------> load_config() > - - load proxy device > - - load transport-specific > - device fields > -- load common device > - fields > -- load common virtqueue > - fields > - ------> load_queue() > - - load transport-specific > - virtqueue fields > -- notify guest > - ------> load_device() > - - load device-specific > - fields > -- load subsections > - - device endianness > - - 64 bit features > - - virtio-1 virtqueue > - fields > -- sanitize endianness > -- sanitize features > -- virtqueue index sanity > - check > - - feature-dependent setup > - > - > -Implications of this setup > -========================== > - > -Devices need to be careful in their state processing during load: The > -load_device() procedure is invoked by the core before subsections have > -been loaded. Any code that depends on information transmitted in subsections > -therefore has to be invoked in the device's load() function _after_ > -virtio_load() returned (like e.g. code depending on features). > - > -Any extension of the state being migrated should be done in subsections > -added to the core for compatibility reasons. If transport or device specific > -state is added, core needs to invoke a callback from the new subsection.
© 2016 - 2024 Red Hat, Inc.