ppc: Remove MMU_MODEn_SUFFIX definitions
[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 register_savevm()
32 virtio_save()                                       <----------
33              ------>      save_config()
34                           - save proxy device
35                           - save transport-specific
36                             device fields
37 - save common device
38   fields
39 - save common virtqueue
40   fields
41              ------>      save_queue()
42                           - save transport-specific
43                             virtqueue fields
44              ------>                               save_device()
45                                                    - save device-specific
46                                                      fields
47 - save subsections
48   - device endianness,
49     if changed from
50     default endianness
51   - 64 bit features, if
52     any high feature bit
53     is set
54   - virtio-1 virtqueue
55     fields, if VERSION_1
56     is set
57
58
59 Load state procedure
60 ====================
61
62 virtio core               virtio transport          virtio device
63 -----------               ----------------          -------------
64
65                                                     load() function registered
66                                                     via register_savevm()
67 virtio_load()                                       <----------
68              ------>      load_config()
69                           - load proxy device
70                           - load transport-specific
71                             device fields
72 - load common device
73   fields
74 - load common virtqueue
75   fields
76              ------>      load_queue()
77                           - load transport-specific
78                             virtqueue fields
79 - notify guest
80              ------>                               load_device()
81                                                    - load device-specific
82                                                      fields
83 - load subsections
84   - device endianness
85   - 64 bit features
86   - virtio-1 virtqueue
87     fields
88 - sanitize endianness
89 - sanitize features
90 - virtqueue index sanity
91   check
92                                                    - feature-dependent setup
93
94
95 Implications of this setup
96 ==========================
97
98 Devices need to be careful in their state processing during load: The
99 load_device() procedure is invoked by the core before subsections have
100 been loaded. Any code that depends on information transmitted in subsections
101 therefore has to be invoked in the device's load() function _after_
102 virtio_load() returned (like e.g. code depending on features).
103
104 Any extension of the state being migrated should be done in subsections
105 added to the core for compatibility reasons. If transport or device specific
106 state is added, core needs to invoke a callback from the new subsection.