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      *
  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