xref: /openbmc/qemu/include/migration/register.h (revision e4fa064d)
1 /*
2  * QEMU migration vmstate registration
3  *
4  * Copyright IBM, Corp. 2008
5  *
6  * Authors:
7  *  Anthony Liguori   <aliguori@us.ibm.com>
8  *
9  * This work is licensed under the terms of the GNU GPL, version 2.  See
10  * the COPYING file in the top-level directory.
11  *
12  */
13 
14 #ifndef MIGRATION_REGISTER_H
15 #define MIGRATION_REGISTER_H
16 
17 #include "hw/vmstate-if.h"
18 
19 /**
20  * struct SaveVMHandlers: handler structure to finely control
21  * migration of complex subsystems and devices, such as RAM, block and
22  * VFIO.
23  */
24 typedef struct SaveVMHandlers {
25 
26     /* The following handlers run inside the BQL. */
27 
28     /**
29      * @save_state
30      *
31      * Saves state section on the source using the latest state format
32      * version.
33      *
34      * Legacy method. Should be deprecated when all users are ported
35      * to VMStateDescription.
36      *
37      * @f: QEMUFile where to send the data
38      * @opaque: data pointer passed to register_savevm_live()
39      */
40     void (*save_state)(QEMUFile *f, void *opaque);
41 
42     /**
43      * @save_prepare
44      *
45      * Called early, even before migration starts, and can be used to
46      * perform early checks.
47      *
48      * @opaque: data pointer passed to register_savevm_live()
49      * @errp: pointer to Error*, to store an error if it happens.
50      *
51      * Returns zero to indicate success and negative for error
52      */
53     int (*save_prepare)(void *opaque, Error **errp);
54 
55     /**
56      * @save_setup
57      *
58      * Initializes the data structures on the source and transmits
59      * first section containing information on the device
60      *
61      * @f: QEMUFile where to send the data
62      * @opaque: data pointer passed to register_savevm_live()
63      * @errp: pointer to Error*, to store an error if it happens.
64      *
65      * Returns zero to indicate success and negative for error
66      */
67     int (*save_setup)(QEMUFile *f, void *opaque, Error **errp);
68 
69     /**
70      * @save_cleanup
71      *
72      * Uninitializes the data structures on the source
73      *
74      * @opaque: data pointer passed to register_savevm_live()
75      */
76     void (*save_cleanup)(void *opaque);
77 
78     /**
79      * @save_live_complete_postcopy
80      *
81      * Called at the end of postcopy for all postcopyable devices.
82      *
83      * @f: QEMUFile where to send the data
84      * @opaque: data pointer passed to register_savevm_live()
85      *
86      * Returns zero to indicate success and negative for error
87      */
88     int (*save_live_complete_postcopy)(QEMUFile *f, void *opaque);
89 
90     /**
91      * @save_live_complete_precopy
92      *
93      * Transmits the last section for the device containing any
94      * remaining data at the end of a precopy phase. When postcopy is
95      * enabled, devices that support postcopy will skip this step,
96      * where the final data will be flushed at the end of postcopy via
97      * @save_live_complete_postcopy instead.
98      *
99      * @f: QEMUFile where to send the data
100      * @opaque: data pointer passed to register_savevm_live()
101      *
102      * Returns zero to indicate success and negative for error
103      */
104     int (*save_live_complete_precopy)(QEMUFile *f, void *opaque);
105 
106     /* This runs both outside and inside the BQL.  */
107 
108     /**
109      * @is_active
110      *
111      * Will skip a state section if not active
112      *
113      * @opaque: data pointer passed to register_savevm_live()
114      *
115      * Returns true if state section is active else false
116      */
117     bool (*is_active)(void *opaque);
118 
119     /**
120      * @has_postcopy
121      *
122      * Checks if a device supports postcopy
123      *
124      * @opaque: data pointer passed to register_savevm_live()
125      *
126      * Returns true for postcopy support else false
127      */
128     bool (*has_postcopy)(void *opaque);
129 
130     /**
131      * @is_active_iterate
132      *
133      * As #SaveVMHandlers.is_active(), will skip an inactive state
134      * section in qemu_savevm_state_iterate.
135      *
136      * For example, it is needed for only-postcopy-states, which needs
137      * to be handled by qemu_savevm_state_setup() and
138      * qemu_savevm_state_pending(), but do not need iterations until
139      * not in postcopy stage.
140      *
141      * @opaque: data pointer passed to register_savevm_live()
142      *
143      * Returns true if state section is active else false
144      */
145     bool (*is_active_iterate)(void *opaque);
146 
147     /* This runs outside the BQL in the migration case, and
148      * within the lock in the savevm case.  The callback had better only
149      * use data that is local to the migration thread or protected
150      * by other locks.
151      */
152 
153     /**
154      * @save_live_iterate
155      *
156      * Should send a chunk of data until the point that stream
157      * bandwidth limits tell it to stop. Each call generates one
158      * section.
159      *
160      * @f: QEMUFile where to send the data
161      * @opaque: data pointer passed to register_savevm_live()
162      *
163      * Returns 0 to indicate that there is still more data to send,
164      *         1 that there is no more data to send and
165      *         negative to indicate an error.
166      */
167     int (*save_live_iterate)(QEMUFile *f, void *opaque);
168 
169     /* This runs outside the BQL!  */
170 
171     /**
172      * @state_pending_estimate
173      *
174      * This estimates the remaining data to transfer
175      *
176      * Sum of @can_postcopy and @must_postcopy is the whole amount of
177      * pending data.
178      *
179      * @opaque: data pointer passed to register_savevm_live()
180      * @must_precopy: amount of data that must be migrated in precopy
181      *                or in stopped state, i.e. that must be migrated
182      *                before target start.
183      * @can_postcopy: amount of data that can be migrated in postcopy
184      *                or in stopped state, i.e. after target start.
185      *                Some can also be migrated during precopy (RAM).
186      *                Some must be migrated after source stops
187      *                (block-dirty-bitmap)
188      */
189     void (*state_pending_estimate)(void *opaque, uint64_t *must_precopy,
190                                    uint64_t *can_postcopy);
191 
192     /**
193      * @state_pending_exact
194      *
195      * This calculates the exact remaining data to transfer
196      *
197      * Sum of @can_postcopy and @must_postcopy is the whole amount of
198      * pending data.
199      *
200      * @opaque: data pointer passed to register_savevm_live()
201      * @must_precopy: amount of data that must be migrated in precopy
202      *                or in stopped state, i.e. that must be migrated
203      *                before target start.
204      * @can_postcopy: amount of data that can be migrated in postcopy
205      *                or in stopped state, i.e. after target start.
206      *                Some can also be migrated during precopy (RAM).
207      *                Some must be migrated after source stops
208      *                (block-dirty-bitmap)
209      */
210     void (*state_pending_exact)(void *opaque, uint64_t *must_precopy,
211                                 uint64_t *can_postcopy);
212 
213     /**
214      * @load_state
215      *
216      * Load sections generated by any of the save functions that
217      * generate sections.
218      *
219      * Legacy method. Should be deprecated when all users are ported
220      * to VMStateDescription.
221      *
222      * @f: QEMUFile where to receive the data
223      * @opaque: data pointer passed to register_savevm_live()
224      * @version_id: the maximum version_id supported
225      *
226      * Returns zero to indicate success and negative for error
227      */
228     int (*load_state)(QEMUFile *f, void *opaque, int version_id);
229 
230     /**
231      * @load_setup
232      *
233      * Initializes the data structures on the destination.
234      *
235      * @f: QEMUFile where to receive the data
236      * @opaque: data pointer passed to register_savevm_live()
237      * @errp: pointer to Error*, to store an error if it happens.
238      *
239      * Returns zero to indicate success and negative for error
240      */
241     int (*load_setup)(QEMUFile *f, void *opaque, Error **errp);
242 
243     /**
244      * @load_cleanup
245      *
246      * Uninitializes the data structures on the destination.
247      *
248      * @opaque: data pointer passed to register_savevm_live()
249      *
250      * Returns zero to indicate success and negative for error
251      */
252     int (*load_cleanup)(void *opaque);
253 
254     /**
255      * @resume_prepare
256      *
257      * Called when postcopy migration wants to resume from failure
258      *
259      * @s: Current migration state
260      * @opaque: data pointer passed to register_savevm_live()
261      *
262      * Returns zero to indicate success and negative for error
263      */
264     int (*resume_prepare)(MigrationState *s, void *opaque);
265 
266     /**
267      * @switchover_ack_needed
268      *
269      * Checks if switchover ack should be used. Called only on
270      * destination.
271      *
272      * @opaque: data pointer passed to register_savevm_live()
273      *
274      * Returns true if switchover ack should be used and false
275      * otherwise
276      */
277     bool (*switchover_ack_needed)(void *opaque);
278 } SaveVMHandlers;
279 
280 /**
281  * register_savevm_live: Register a set of custom migration handlers
282  *
283  * @idstr: state section identifier
284  * @instance_id: instance id
285  * @version_id: version id supported
286  * @ops: SaveVMHandlers structure
287  * @opaque: data pointer passed to SaveVMHandlers handlers
288  */
289 int register_savevm_live(const char *idstr,
290                          uint32_t instance_id,
291                          int version_id,
292                          const SaveVMHandlers *ops,
293                          void *opaque);
294 
295 /**
296  * unregister_savevm: Unregister custom migration handlers
297  *
298  * @obj: object associated with state section
299  * @idstr:  state section identifier
300  * @opaque: data pointer passed to register_savevm_live()
301  */
302 void unregister_savevm(VMStateIf *obj, const char *idstr, void *opaque);
303 
304 #endif
305