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