Re: [PATCH 03/10] docs/migration: Convert virtio.txt into rST
On 1/9/24 07:46, pet...@redhat.com wrote: From: Peter Xu Convert the plain old .txt into .rst, add it into migration/index.rst. Signed-off-by: Peter Xu Reviewed-by: Cédric Le Goater 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 00..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
[PATCH 03/10] docs/migration: Convert virtio.txt into rST
From: Peter Xu Convert the plain old .txt into .rst, add it into migration/index.rst. Signed-off-by: Peter Xu --- 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 00..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.
