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 * Note that this handler can be called even if save_setup 74 * wasn't called earlier. 75 * 76 * @opaque: data pointer passed to register_savevm_live() 77 */ 78 void (*save_cleanup)(void *opaque); 79 80 /** 81 * @save_live_complete_postcopy 82 * 83 * Called at the end of postcopy for all postcopyable devices. 84 * 85 * @f: QEMUFile where to send the data 86 * @opaque: data pointer passed to register_savevm_live() 87 * 88 * Returns zero to indicate success and negative for error 89 */ 90 int (*save_live_complete_postcopy)(QEMUFile *f, void *opaque); 91 92 /** 93 * @save_live_complete_precopy 94 * 95 * Transmits the last section for the device containing any 96 * remaining data at the end of a precopy phase. When postcopy is 97 * enabled, devices that support postcopy will skip this step, 98 * where the final data will be flushed at the end of postcopy via 99 * @save_live_complete_postcopy instead. 100 * 101 * @f: QEMUFile where to send the data 102 * @opaque: data pointer passed to register_savevm_live() 103 * 104 * Returns zero to indicate success and negative for error 105 */ 106 int (*save_live_complete_precopy)(QEMUFile *f, void *opaque); 107 108 /** 109 * @save_live_complete_precopy_thread (invoked in a separate thread) 110 * 111 * Called at the end of a precopy phase from a separate worker thread 112 * in configurations where multifd device state transfer is supported 113 * in order to perform asynchronous transmission of the remaining data in 114 * parallel with @save_live_complete_precopy handlers. 115 * When postcopy is enabled, devices that support postcopy will skip this 116 * step. 117 * 118 * @d: a #SaveLiveCompletePrecopyThreadData containing parameters that the 119 * handler may need, including this device section idstr and instance_id, 120 * and opaque data pointer passed to register_savevm_live(). 121 * @errp: pointer to Error*, to store an error if it happens. 122 * 123 * Returns true to indicate success and false for errors. 124 */ 125 SaveLiveCompletePrecopyThreadHandler save_live_complete_precopy_thread; 126 127 /* This runs both outside and inside the BQL. */ 128 129 /** 130 * @is_active 131 * 132 * Will skip a state section if not active 133 * 134 * @opaque: data pointer passed to register_savevm_live() 135 * 136 * Returns true if state section is active else false 137 */ 138 bool (*is_active)(void *opaque); 139 140 /** 141 * @has_postcopy 142 * 143 * Checks if a device supports postcopy 144 * 145 * @opaque: data pointer passed to register_savevm_live() 146 * 147 * Returns true for postcopy support else false 148 */ 149 bool (*has_postcopy)(void *opaque); 150 151 /** 152 * @is_active_iterate 153 * 154 * As #SaveVMHandlers.is_active(), will skip an inactive state 155 * section in qemu_savevm_state_iterate. 156 * 157 * For example, it is needed for only-postcopy-states, which needs 158 * to be handled by qemu_savevm_state_setup() and 159 * qemu_savevm_state_pending(), but do not need iterations until 160 * not in postcopy stage. 161 * 162 * @opaque: data pointer passed to register_savevm_live() 163 * 164 * Returns true if state section is active else false 165 */ 166 bool (*is_active_iterate)(void *opaque); 167 168 /* This runs outside the BQL in the migration case, and 169 * within the lock in the savevm case. The callback had better only 170 * use data that is local to the migration thread or protected 171 * by other locks. 172 */ 173 174 /** 175 * @save_live_iterate 176 * 177 * Should send a chunk of data until the point that stream 178 * bandwidth limits tell it to stop. Each call generates one 179 * section. 180 * 181 * @f: QEMUFile where to send the data 182 * @opaque: data pointer passed to register_savevm_live() 183 * 184 * Returns 0 to indicate that there is still more data to send, 185 * 1 that there is no more data to send and 186 * negative to indicate an error. 187 */ 188 int (*save_live_iterate)(QEMUFile *f, void *opaque); 189 190 /* This runs outside the BQL! */ 191 192 /** 193 * @save_postcopy_prepare 194 * 195 * This hook will be invoked on the source side right before switching 196 * to postcopy (before VM stopped). 197 * 198 * @f: QEMUFile where to send the data 199 * @opaque: Data pointer passed to register_savevm_live() 200 * @errp: Error** used to report error message 201 * 202 * Returns: true if succeeded, false if error occured. When false is 203 * returned, @errp must be set. 204 */ 205 bool (*save_postcopy_prepare)(QEMUFile *f, void *opaque, Error **errp); 206 207 /** 208 * @state_pending_estimate 209 * 210 * This estimates the remaining data to transfer 211 * 212 * Sum of @can_postcopy and @must_postcopy is the whole amount of 213 * pending data. 214 * 215 * @opaque: data pointer passed to register_savevm_live() 216 * @must_precopy: amount of data that must be migrated in precopy 217 * or in stopped state, i.e. that must be migrated 218 * before target start. 219 * @can_postcopy: amount of data that can be migrated in postcopy 220 * or in stopped state, i.e. after target start. 221 * Some can also be migrated during precopy (RAM). 222 * Some must be migrated after source stops 223 * (block-dirty-bitmap) 224 */ 225 void (*state_pending_estimate)(void *opaque, uint64_t *must_precopy, 226 uint64_t *can_postcopy); 227 228 /** 229 * @state_pending_exact 230 * 231 * This calculates the exact remaining data to transfer 232 * 233 * Sum of @can_postcopy and @must_postcopy is the whole amount of 234 * pending data. 235 * 236 * @opaque: data pointer passed to register_savevm_live() 237 * @must_precopy: amount of data that must be migrated in precopy 238 * or in stopped state, i.e. that must be migrated 239 * before target start. 240 * @can_postcopy: amount of data that can be migrated in postcopy 241 * or in stopped state, i.e. after target start. 242 * Some can also be migrated during precopy (RAM). 243 * Some must be migrated after source stops 244 * (block-dirty-bitmap) 245 */ 246 void (*state_pending_exact)(void *opaque, uint64_t *must_precopy, 247 uint64_t *can_postcopy); 248 249 /** 250 * @load_state 251 * 252 * Load sections generated by any of the save functions that 253 * generate sections. 254 * 255 * Legacy method. Should be deprecated when all users are ported 256 * to VMStateDescription. 257 * 258 * @f: QEMUFile where to receive the data 259 * @opaque: data pointer passed to register_savevm_live() 260 * @version_id: the maximum version_id supported 261 * 262 * Returns zero to indicate success and negative for error 263 */ 264 int (*load_state)(QEMUFile *f, void *opaque, int version_id); 265 266 /** 267 * @load_state_buffer (invoked outside the BQL) 268 * 269 * Load device state buffer provided to qemu_loadvm_load_state_buffer(). 270 * 271 * @opaque: data pointer passed to register_savevm_live() 272 * @buf: the data buffer to load 273 * @len: the data length in buffer 274 * @errp: pointer to Error*, to store an error if it happens. 275 * 276 * Returns true to indicate success and false for errors. 277 */ 278 bool (*load_state_buffer)(void *opaque, char *buf, size_t len, 279 Error **errp); 280 281 /** 282 * @load_setup 283 * 284 * Initializes the data structures on the destination. 285 * 286 * @f: QEMUFile where to receive the data 287 * @opaque: data pointer passed to register_savevm_live() 288 * @errp: pointer to Error*, to store an error if it happens. 289 * 290 * Returns zero to indicate success and negative for error 291 */ 292 int (*load_setup)(QEMUFile *f, void *opaque, Error **errp); 293 294 /** 295 * @load_cleanup 296 * 297 * Uninitializes the data structures on the destination. 298 * Note that this handler can be called even if load_setup 299 * wasn't called earlier. 300 * 301 * @opaque: data pointer passed to register_savevm_live() 302 * 303 * Returns zero to indicate success and negative for error 304 */ 305 int (*load_cleanup)(void *opaque); 306 307 /** 308 * @resume_prepare 309 * 310 * Called when postcopy migration wants to resume from failure 311 * 312 * @s: Current migration state 313 * @opaque: data pointer passed to register_savevm_live() 314 * 315 * Returns zero to indicate success and negative for error 316 */ 317 int (*resume_prepare)(MigrationState *s, void *opaque); 318 319 /** 320 * @switchover_ack_needed 321 * 322 * Checks if switchover ack should be used. Called only on 323 * destination. 324 * 325 * @opaque: data pointer passed to register_savevm_live() 326 * 327 * Returns true if switchover ack should be used and false 328 * otherwise 329 */ 330 bool (*switchover_ack_needed)(void *opaque); 331 332 /** 333 * @switchover_start 334 * 335 * Notifies that the switchover has started. Called only on 336 * the destination. 337 * 338 * @opaque: data pointer passed to register_savevm_live() 339 * 340 * Returns zero to indicate success and negative for error 341 */ 342 int (*switchover_start)(void *opaque); 343 } SaveVMHandlers; 344 345 /** 346 * register_savevm_live: Register a set of custom migration handlers 347 * 348 * @idstr: state section identifier 349 * @instance_id: instance id 350 * @version_id: version id supported 351 * @ops: SaveVMHandlers structure 352 * @opaque: data pointer passed to SaveVMHandlers handlers 353 */ 354 int register_savevm_live(const char *idstr, 355 uint32_t instance_id, 356 int version_id, 357 const SaveVMHandlers *ops, 358 void *opaque); 359 360 /** 361 * unregister_savevm: Unregister custom migration handlers 362 * 363 * @obj: object associated with state section 364 * @idstr: state section identifier 365 * @opaque: data pointer passed to register_savevm_live() 366 */ 367 void unregister_savevm(VMStateIf *obj, const char *idstr, void *opaque); 368 369 #endif 370