| Message ID | 20240109064628.595453-4-peterx@redhat.com |
|---|---|
| State | New |
| Headers | show |
| Series | docs/migration: Reorganize migration documentations | expand |
On 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.
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.