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