include/migration/register.h

   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