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 * 64 * Returns zero to indicate success and negative for error 65 */ 66 int (*save_setup)(QEMUFile *f, void *opaque); 67 68 /** 69 * @save_cleanup 70 * 71 * Uninitializes the data structures on the source 72 * 73 * @opaque: data pointer passed to register_savevm_live() 74 */ 75 void (*save_cleanup)(void *opaque); 76 77 /** 78 * @save_live_complete_postcopy 79 * 80 * Called at the end of postcopy for all postcopyable devices. 81 * 82 * @f: QEMUFile where to send the data 83 * @opaque: data pointer passed to register_savevm_live() 84 * 85 * Returns zero to indicate success and negative for error 86 */ 87 int (*save_live_complete_postcopy)(QEMUFile *f, void *opaque); 88 89 /** 90 * @save_live_complete_precopy 91 * 92 * Transmits the last section for the device containing any 93 * remaining data at the end of a precopy phase. When postcopy is 94 * enabled, devices that support postcopy will skip this step, 95 * where the final data will be flushed at the end of postcopy via 96 * @save_live_complete_postcopy instead. 97 * 98 * @f: QEMUFile where to send the data 99 * @opaque: data pointer passed to register_savevm_live() 100 * 101 * Returns zero to indicate success and negative for error 102 */ 103 int (*save_live_complete_precopy)(QEMUFile *f, void *opaque); 104 105 /* This runs both outside and inside the BQL. */ 106 107 /** 108 * @is_active 109 * 110 * Will skip a state section if not active 111 * 112 * @opaque: data pointer passed to register_savevm_live() 113 * 114 * Returns true if state section is active else false 115 */ 116 bool (*is_active)(void *opaque); 117 118 /** 119 * @has_postcopy 120 * 121 * Checks if a device supports postcopy 122 * 123 * @opaque: data pointer passed to register_savevm_live() 124 * 125 * Returns true for postcopy support else false 126 */ 127 bool (*has_postcopy)(void *opaque); 128 129 /** 130 * @is_active_iterate 131 * 132 * As #SaveVMHandlers.is_active(), will skip an inactive state 133 * section in qemu_savevm_state_iterate. 134 * 135 * For example, it is needed for only-postcopy-states, which needs 136 * to be handled by qemu_savevm_state_setup() and 137 * qemu_savevm_state_pending(), but do not need iterations until 138 * not in postcopy stage. 139 * 140 * @opaque: data pointer passed to register_savevm_live() 141 * 142 * Returns true if state section is active else false 143 */ 144 bool (*is_active_iterate)(void *opaque); 145 146 /* This runs outside the BQL in the migration case, and 147 * within the lock in the savevm case. The callback had better only 148 * use data that is local to the migration thread or protected 149 * by other locks. 150 */ 151 152 /** 153 * @save_live_iterate 154 * 155 * Should send a chunk of data until the point that stream 156 * bandwidth limits tell it to stop. Each call generates one 157 * section. 158 * 159 * @f: QEMUFile where to send the data 160 * @opaque: data pointer passed to register_savevm_live() 161 * 162 * Returns 0 to indicate that there is still more data to send, 163 * 1 that there is no more data to send and 164 * negative to indicate an error. 165 */ 166 int (*save_live_iterate)(QEMUFile *f, void *opaque); 167 168 /* This runs outside the BQL! */ 169 170 /** 171 * @state_pending_estimate 172 * 173 * This estimates the remaining data to transfer 174 * 175 * Sum of @can_postcopy and @must_postcopy is the whole amount of 176 * pending data. 177 * 178 * @opaque: data pointer passed to register_savevm_live() 179 * @must_precopy: amount of data that must be migrated in precopy 180 * or in stopped state, i.e. that must be migrated 181 * before target start. 182 * @can_postcopy: amount of data that can be migrated in postcopy 183 * or in stopped state, i.e. after target start. 184 * Some can also be migrated during precopy (RAM). 185 * Some must be migrated after source stops 186 * (block-dirty-bitmap) 187 */ 188 void (*state_pending_estimate)(void *opaque, uint64_t *must_precopy, 189 uint64_t *can_postcopy); 190 191 /** 192 * @state_pending_exact 193 * 194 * This calculates the exact remaining data to transfer 195 * 196 * Sum of @can_postcopy and @must_postcopy is the whole amount of 197 * pending data. 198 * 199 * @opaque: data pointer passed to register_savevm_live() 200 * @must_precopy: amount of data that must be migrated in precopy 201 * or in stopped state, i.e. that must be migrated 202 * before target start. 203 * @can_postcopy: amount of data that can be migrated in postcopy 204 * or in stopped state, i.e. after target start. 205 * Some can also be migrated during precopy (RAM). 206 * Some must be migrated after source stops 207 * (block-dirty-bitmap) 208 */ 209 void (*state_pending_exact)(void *opaque, uint64_t *must_precopy, 210 uint64_t *can_postcopy); 211 212 /** 213 * @load_state 214 * 215 * Load sections generated by any of the save functions that 216 * generate sections. 217 * 218 * Legacy method. Should be deprecated when all users are ported 219 * to VMStateDescription. 220 * 221 * @f: QEMUFile where to receive the data 222 * @opaque: data pointer passed to register_savevm_live() 223 * @version_id: the maximum version_id supported 224 * 225 * Returns zero to indicate success and negative for error 226 */ 227 int (*load_state)(QEMUFile *f, void *opaque, int version_id); 228 229 /** 230 * @load_setup 231 * 232 * Initializes the data structures on the destination. 233 * 234 * @f: QEMUFile where to receive the data 235 * @opaque: data pointer passed to register_savevm_live() 236 * 237 * Returns zero to indicate success and negative for error 238 */ 239 int (*load_setup)(QEMUFile *f, void *opaque); 240 241 /** 242 * @load_cleanup 243 * 244 * Uninitializes the data structures on the destination. 245 * 246 * @opaque: data pointer passed to register_savevm_live() 247 * 248 * Returns zero to indicate success and negative for error 249 */ 250 int (*load_cleanup)(void *opaque); 251 252 /** 253 * @resume_prepare 254 * 255 * Called when postcopy migration wants to resume from failure 256 * 257 * @s: Current migration state 258 * @opaque: data pointer passed to register_savevm_live() 259 * 260 * Returns zero to indicate success and negative for error 261 */ 262 int (*resume_prepare)(MigrationState *s, void *opaque); 263 264 /** 265 * @switchover_ack_needed 266 * 267 * Checks if switchover ack should be used. Called only on 268 * destination. 269 * 270 * @opaque: data pointer passed to register_savevm_live() 271 * 272 * Returns true if switchover ack should be used and false 273 * otherwise 274 */ 275 bool (*switchover_ack_needed)(void *opaque); 276 } SaveVMHandlers; 277 278 /** 279 * register_savevm_live: Register a set of custom migration handlers 280 * 281 * @idstr: state section identifier 282 * @instance_id: instance id 283 * @version_id: version id supported 284 * @ops: SaveVMHandlers structure 285 * @opaque: data pointer passed to SaveVMHandlers handlers 286 */ 287 int register_savevm_live(const char *idstr, 288 uint32_t instance_id, 289 int version_id, 290 const SaveVMHandlers *ops, 291 void *opaque); 292 293 /** 294 * unregister_savevm: Unregister custom migration handlers 295 * 296 * @obj: object associated with state section 297 * @idstr: state section identifier 298 * @opaque: data pointer passed to register_savevm_live() 299 */ 300 void unregister_savevm(VMStateIf *obj, const char *idstr, void *opaque); 301 302 #endif 303