hw/arm/virt: pass VirtMachineState instead of VirtGuestInfo
[qemu.git] / docs / virtio-migration.txt
1 Virtio devices and migration
2 ============================
3
4 Copyright 2015 IBM Corp.
5
6 This work is licensed under the terms of the GNU GPL, version 2 or later.  See
7 the COPYING file in the top-level directory.
8
9 Saving and restoring the state of virtio devices is a bit of a twisty maze,
10 for several reasons:
11 - state is distributed between several parts:
12   - virtio core, for common fields like features, number of queues, ...
13   - virtio transport (pci, ccw, ...), for the different proxy devices and
14     transport specific state (msix vectors, indicators, ...)
15   - virtio device (net, blk, ...), for the different device types and their
16     state (mac address, request queue, ...)
17 - most fields are saved via the stream interface; subsequently, subsections
18   have been added to make cross-version migration possible
19
20 This file attempts to document the current procedure and point out some
21 caveats.
22
23
24 Save state procedure
25 ====================
26
27 virtio core               virtio transport          virtio device
28 -----------               ----------------          -------------
29
30                                                     save() function registered
31                                                     via VMState wrapper on
32                                                     device class
33 virtio_save()                                       <----------
34              ------>      save_config()
35                           - save proxy device
36                           - save transport-specific
37                             device fields
38 - save common device
39   fields
40 - save common virtqueue
41   fields
42              ------>      save_queue()
43                           - save transport-specific
44                             virtqueue fields
45              ------>                               save_device()
46                                                    - save device-specific
47                                                      fields
48 - save subsections
49   - device endianness,
50     if changed from
51     default endianness
52   - 64 bit features, if
53     any high feature bit
54     is set
55   - virtio-1 virtqueue
56     fields, if VERSION_1
57     is set
58
59
60 Load state procedure
61 ====================
62
63 virtio core               virtio transport          virtio device
64 -----------               ----------------          -------------
65
66                                                     load() function registered
67                                                     via VMState wrapper on
68                                                     device class
69 virtio_load()                                       <----------
70              ------>      load_config()
71                           - load proxy device
72                           - load transport-specific
73                             device fields
74 - load common device
75   fields
76 - load common virtqueue
77   fields
78              ------>      load_queue()
79                           - load transport-specific
80                             virtqueue fields
81 - notify guest
82              ------>                               load_device()
83                                                    - load device-specific
84                                                      fields
85 - load subsections
86   - device endianness
87   - 64 bit features
88   - virtio-1 virtqueue
89     fields
90 - sanitize endianness
91 - sanitize features
92 - virtqueue index sanity
93   check
94                                                    - feature-dependent setup
95
96
97 Implications of this setup
98 ==========================
99
100 Devices need to be careful in their state processing during load: The
101 load_device() procedure is invoked by the core before subsections have
102 been loaded. Any code that depends on information transmitted in subsections
103 therefore has to be invoked in the device's load() function _after_
104 virtio_load() returned (like e.g. code depending on features).
105
106 Any extension of the state being migrated should be done in subsections
107 added to the core for compatibility reasons. If transport or device specific
108 state is added, core needs to invoke a callback from the new subsection.