4 * Copyright IBM, Corp. 2008
7 * Anthony Liguori <aliguori@us.ibm.com>
9 * This work is licensed under the terms of the GNU GPL, version 2. See
10 * the COPYING file in the top-level directory.
14 #ifndef QEMU_MIGRATION_H
15 #define QEMU_MIGRATION_H
17 #include "exec/cpu-common.h"
18 #include "hw/qdev-core.h"
19 #include "qapi/qapi-types-migration.h"
20 #include "qapi/qmp/json-writer.h"
21 #include "qemu/thread.h"
22 #include "qemu/coroutine_int.h"
23 #include "io/channel.h"
24 #include "io/channel-buffer.h"
25 #include "net/announce.h"
26 #include "qom/object.h"
27 #include "postcopy-ram.h"
28 #include "sysemu/runstate.h"
30 struct PostcopyBlocktimeContext
;
32 #define MIGRATION_RESUME_ACK_VALUE (1)
35 * 1<<6=64 pages -> 256K chunk when page size is 4K. This gives us
36 * the benefit that all the chunks are 64 pages aligned then the
37 * bitmaps are always aligned to LONG.
39 #define CLEAR_BITMAP_SHIFT_MIN 6
41 * 1<<18=256K pages -> 1G chunk when page size is 4K. This is the
42 * default value to use if no one specified.
44 #define CLEAR_BITMAP_SHIFT_DEFAULT 18
46 * 1<<31=2G pages -> 8T chunk when page size is 4K. This should be
47 * big enough and make sure we won't overflow easily.
49 #define CLEAR_BITMAP_SHIFT_MAX 31
51 /* This is an abstraction of a "temp huge page" for postcopy's purpose */
54 * This points to a temporary huge page as a buffer for UFFDIO_COPY. It's
55 * mmap()ed and needs to be freed when cleanup.
59 * This points to the host page we're going to install for this temp page.
60 * It tells us after we've received the whole page, where we should put it.
63 /* Number of small pages copied (in size of TARGET_PAGE_SIZE) */
64 unsigned int target_pages
;
65 /* Whether this page contains all zeros */
70 PREEMPT_THREAD_NONE
= 0,
71 PREEMPT_THREAD_CREATED
,
73 } PreemptThreadStatus
;
75 /* State for the incoming migration */
76 struct MigrationIncomingState
{
77 QEMUFile
*from_src_file
;
78 /* Previously received RAM's RAMBlock pointer */
79 RAMBlock
*last_recv_block
[RAM_CHANNEL_MAX
];
80 /* A hook to allow cleanup at the end of incoming migration */
82 void (*transport_cleanup
)(void *data
);
84 * Used to sync thread creations. Note that we can't create threads in
85 * parallel with this sem.
87 QemuSemaphore thread_sync_sem
;
89 * Free at the start of the main state load, set as the main thread finishes
92 QemuEvent main_thread_load_event
;
94 /* For network announces */
95 AnnounceTimer announce_timer
;
97 size_t largest_page_size
;
98 bool have_fault_thread
;
99 QemuThread fault_thread
;
100 /* Set this when we want the fault thread to quit */
101 bool fault_thread_quit
;
103 bool have_listen_thread
;
104 QemuThread listen_thread
;
106 /* For the kernel to send us notifications */
108 /* To notify the fault_thread to wake, e.g., when need to quit */
109 int userfault_event_fd
;
110 QEMUFile
*to_src_file
;
111 QemuMutex rp_mutex
; /* We send replies from multiple threads */
112 /* RAMBlock of last request sent to source */
115 * Number of postcopy channels including the default precopy channel, so
116 * vanilla postcopy will only contain one channel which contain both
117 * precopy and postcopy streams.
119 * This is calculated when the src requests to enable postcopy but before
120 * it starts. Its value can depend on e.g. whether postcopy preemption is
123 unsigned int postcopy_channels
;
124 /* QEMUFile for postcopy only; it'll be handled by a separate thread */
125 QEMUFile
*postcopy_qemufile_dst
;
127 * When postcopy_qemufile_dst is properly setup, this sem is posted.
128 * One can wait on this semaphore to wait until the preempt channel is
131 QemuSemaphore postcopy_qemufile_dst_done
;
132 /* Postcopy priority thread is used to receive postcopy requested pages */
133 QemuThread postcopy_prio_thread
;
135 * Always set by the main vm load thread only, but can be read by the
136 * postcopy preempt thread. "volatile" makes sure all reads will be
137 * up-to-date across cores.
139 volatile PreemptThreadStatus preempt_thread_status
;
141 * Used to sync between the ram load main thread and the fast ram load
142 * thread. It protects postcopy_qemufile_dst, which is the postcopy
145 * The ram fast load thread will take it mostly for the whole lifecycle
146 * because it needs to continuously read data from the channel, and
147 * it'll only release this mutex if postcopy is interrupted, so that
148 * the ram load main thread will take this mutex over and properly
149 * release the broken channel.
151 QemuMutex postcopy_prio_thread_mutex
;
153 * An array of temp host huge pages to be used, one for each postcopy
156 PostcopyTmpPage
*postcopy_tmp_pages
;
157 /* This is shared for all postcopy channels */
158 void *postcopy_tmp_zero_page
;
159 /* PostCopyFD's for external userfaultfds & handlers of shared memory */
160 GArray
*postcopy_remote_fds
;
165 * The incoming migration coroutine, non-NULL during qemu_loadvm_state().
166 * Used to wake the migration incoming coroutine from rdma code. How much is
167 * it safe - it's a question.
169 Coroutine
*loadvm_co
;
171 /* The coroutine we should enter (back) after failover */
172 Coroutine
*colo_incoming_co
;
173 QemuSemaphore colo_incoming_sem
;
176 * PostcopyBlocktimeContext to keep information for postcopy
177 * live migration, to calculate vCPU block time
179 struct PostcopyBlocktimeContext
*blocktime_ctx
;
181 /* notify PAUSED postcopy incoming migrations to try to continue */
182 QemuSemaphore postcopy_pause_sem_dst
;
183 QemuSemaphore postcopy_pause_sem_fault
;
185 * This semaphore is used to allow the ram fast load thread (only when
186 * postcopy preempt is enabled) fall into sleep when there's network
187 * interruption detected. When the recovery is done, the main load
188 * thread will kick the fast ram load thread using this semaphore.
190 QemuSemaphore postcopy_pause_sem_fast_load
;
192 /* List of listening socket addresses */
193 SocketAddressList
*socket_address_list
;
195 /* A tree of pages that we requested to the source VM */
196 GTree
*page_requested
;
198 * For postcopy only, count the number of requested page faults that
199 * still haven't been resolved.
201 int page_requested_count
;
203 * The mutex helps to maintain the requested pages that we sent to the
204 * source, IOW, to guarantee coherent between the page_requests tree and
205 * the per-ramblock receivedmap. Note! This does not guarantee consistency
206 * of the real page copy procedures (using UFFDIO_[ZERO]COPY). E.g., even
207 * if one bit in receivedmap is cleared, UFFDIO_COPY could have happened
208 * for that page already. This is intended so that the mutex won't
209 * serialize and blocked by slow operations like UFFDIO_* ioctls. However
210 * this should be enough to make sure the page_requested tree always
211 * contains valid information.
213 QemuMutex page_request_mutex
;
215 * If postcopy preempt is enabled, there is a chance that the main
216 * thread finished loading its data before the preempt channel has
217 * finished loading the urgent pages. If that happens, the two threads
218 * will use this condvar to synchronize, so the main thread will always
219 * wait until all pages received.
221 QemuCond page_request_cond
;
224 * Number of devices that have yet to approve switchover. When this reaches
225 * zero an ACK that it's OK to do switchover is sent to the source. No lock
226 * is needed as this field is updated serially.
228 unsigned int switchover_ack_pending_num
;
231 MigrationIncomingState
*migration_incoming_get_current(void);
232 void migration_incoming_state_destroy(void);
233 void migration_incoming_transport_cleanup(MigrationIncomingState
*mis
);
235 * Functions to work with blocktime context
237 void fill_destination_postcopy_migration_info(MigrationInfo
*info
);
239 #define TYPE_MIGRATION "migration"
241 typedef struct MigrationClass MigrationClass
;
242 DECLARE_OBJ_CHECKERS(MigrationState
, MigrationClass
,
243 MIGRATION_OBJ
, TYPE_MIGRATION
)
245 struct MigrationClass
{
247 DeviceClass parent_class
;
250 struct MigrationState
{
252 DeviceState parent_obj
;
256 /* Protected by qemu_file_lock */
257 QEMUFile
*to_dst_file
;
258 /* Postcopy specific transfer channel */
259 QEMUFile
*postcopy_qemufile_src
;
261 * It is posted when the preempt channel is established. Note: this is
262 * used for both the start or recover of a postcopy migration. We'll
263 * post to this sem every time a new preempt channel is created in the
264 * main thread, and we keep post() and wait() in pair.
266 QemuSemaphore postcopy_qemufile_src_sem
;
267 QIOChannelBuffer
*bioc
;
269 * Protects to_dst_file/from_dst_file pointers. We need to make sure we
270 * won't yield or hang during the critical section, since this lock will be
271 * used in OOB command handler.
273 QemuMutex qemu_file_lock
;
276 * Used to allow urgent requests to override rate limiting.
278 QemuSemaphore rate_limit_sem
;
280 /* pages already send at the beginning of current iteration */
281 uint64_t iteration_initial_pages
;
283 /* pages transferred per second */
284 double pages_per_second
;
286 /* bytes already send at the beginning of current iteration */
287 uint64_t iteration_initial_bytes
;
288 /* time at the start of current iteration */
289 int64_t iteration_start_time
;
291 * The final stage happens when the remaining data is smaller than
292 * this threshold; it's calculated from the requested downtime and
293 * measured bandwidth, or avail-switchover-bandwidth if specified.
295 uint64_t threshold_size
;
297 /* params from 'migrate-set-parameters' */
298 MigrationParameters parameters
;
302 /* State related to return path */
304 /* Protected by qemu_file_lock */
305 QEMUFile
*from_dst_file
;
306 QemuThread rp_thread
;
308 * We can also check non-zero of rp_thread, but there's no "official"
309 * way to do this, so this bool makes it slightly more elegant.
310 * Checking from_dst_file for this is racy because from_dst_file will
311 * be cleared in the rp_thread!
313 bool rp_thread_created
;
315 * Used to synchronize between migration main thread and return
316 * path thread. The migration thread can wait() on this sem, while
317 * other threads (e.g., return path thread) can kick it using a
320 QemuSemaphore rp_sem
;
322 * We post to this when we got one PONG from dest. So far it's an
323 * easy way to know the main channel has successfully established
326 QemuSemaphore rp_pong_acks
;
330 /* Timestamp when recent migration starts (ms) */
332 /* Total time used by latest migration (ms) */
334 /* Timestamp when VM is down (ms) to migrate the last stuff */
335 int64_t downtime_start
;
337 int64_t expected_downtime
;
338 bool capabilities
[MIGRATION_CAPABILITY__MAX
];
342 * State before stopping the vm by vm_stop_force_state().
343 * If migration is interrupted by any reason, we need to continue
344 * running the guest on source if it was running or restore its stopped
347 RunState vm_old_state
;
349 /* Flag set once the migration has been asked to enter postcopy */
352 /* Flag set once the migration thread is running (and needs joining) */
353 bool migration_thread_running
;
355 /* Flag set once the migration thread called bdrv_inactivate_all */
358 /* Migration is waiting for guest to unplug device */
359 QemuSemaphore wait_unplug_sem
;
361 /* Migration is paused due to pause-before-switchover */
362 QemuSemaphore pause_sem
;
364 /* The semaphore is used to notify COLO thread that failover is finished */
365 QemuSemaphore colo_exit_sem
;
367 /* The event is used to notify COLO thread to do checkpoint */
368 QemuEvent colo_checkpoint_event
;
369 int64_t colo_checkpoint_time
;
370 QEMUTimer
*colo_delay_timer
;
372 /* The first error that has occurred.
373 We used the mutex to be able to return the 1st error message */
375 /* mutex to protect errp */
376 QemuMutex error_mutex
;
378 /* Do we have to clean up -b/-i from old migrate parameters */
379 /* This feature is deprecated and will be removed */
380 bool must_remove_block_options
;
383 * Global switch on whether we need to store the global state
386 bool store_global_state
;
388 /* Whether we send QEMU_VM_CONFIGURATION during migration */
389 bool send_configuration
;
390 /* Whether we send section footer during migration */
391 bool send_section_footer
;
393 /* Needed by postcopy-pause state */
394 QemuSemaphore postcopy_pause_sem
;
396 * Whether we abort the migration if decompression errors are
397 * detected at the destination. It is left at false for qemu
398 * older than 3.0, since only newer qemu sends streams that
399 * do not trigger spurious decompression errors.
401 bool decompress_error_check
;
403 * This variable only affects behavior when postcopy preempt mode is
408 * - postcopy preempt src QEMU instance will generate an EOS message at
409 * the end of migration to shut the preempt channel on dest side.
411 * - postcopy preempt channel will be created at the setup phase on src
416 * - postcopy preempt src QEMU instance will _not_ generate an EOS
417 * message at the end of migration, the dest qemu will shutdown the
420 * - postcopy preempt channel will be created at the switching phase
421 * from precopy -> postcopy (to avoid race condition of misordered
422 * creation of channels).
424 * NOTE: See message-id <ZBoShWArKDPpX/D7@work-vm> on qemu-devel
425 * mailing list for more information on the possible race. Everyone
426 * should probably just keep this value untouched after set by the
427 * machine type (or the default).
429 bool preempt_pre_7_2
;
432 * flush every channel after each section sent.
434 * This assures that we can't mix pages from one iteration through
435 * ram pages with pages for the following iteration. We really
436 * only need to do this flush after we have go through all the
437 * dirty pages. For historical reasons, we do that after each
438 * section. This is suboptimal (we flush too many times).
439 * Default value is false. (since 8.1)
441 bool multifd_flush_after_each_section
;
443 * This decides the size of guest memory chunk that will be used
444 * to track dirty bitmap clearing. The size of memory chunk will
445 * be GUEST_PAGE_SIZE << N. Say, N=0 means we will clear dirty
446 * bitmap for each page to send (1<<0=1); N=10 means we will clear
447 * dirty bitmap only once for 1<<10=1K continuous guest pages
448 * (which is in 4M chunk).
450 uint8_t clear_bitmap_shift
;
453 * This save hostname when out-going migration starts
457 /* QEMU_VM_VMDESCRIPTION content filled for all non-iterable devices. */
461 * Indicates whether an ACK from the destination that it's OK to do
462 * switchover has been received.
464 bool switchover_acked
;
465 /* Is this a rdma migration */
469 void migrate_set_state(int *state
, int old_state
, int new_state
);
471 void migration_fd_process_incoming(QEMUFile
*f
);
472 void migration_ioc_process_incoming(QIOChannel
*ioc
, Error
**errp
);
473 void migration_incoming_process(void);
475 bool migration_has_all_channels(void);
477 void migrate_set_error(MigrationState
*s
, const Error
*error
);
478 bool migrate_has_error(MigrationState
*s
);
480 void migrate_fd_connect(MigrationState
*s
, Error
*error_in
);
482 bool migration_is_setup_or_active(int state
);
483 bool migration_is_running(int state
);
485 int migrate_init(MigrationState
*s
, Error
**errp
);
486 bool migration_is_blocked(Error
**errp
);
487 /* True if outgoing migration has entered postcopy phase */
488 bool migration_in_postcopy(void);
489 bool migration_postcopy_is_alive(int state
);
490 MigrationState
*migrate_get_current(void);
492 uint64_t ram_get_total_transferred_pages(void);
494 /* Sending on the return path - generic and then for each message type */
495 void migrate_send_rp_shut(MigrationIncomingState
*mis
,
497 void migrate_send_rp_pong(MigrationIncomingState
*mis
,
499 int migrate_send_rp_req_pages(MigrationIncomingState
*mis
, RAMBlock
*rb
,
500 ram_addr_t start
, uint64_t haddr
);
501 int migrate_send_rp_message_req_pages(MigrationIncomingState
*mis
,
502 RAMBlock
*rb
, ram_addr_t start
);
503 void migrate_send_rp_recv_bitmap(MigrationIncomingState
*mis
,
505 void migrate_send_rp_resume_ack(MigrationIncomingState
*mis
, uint32_t value
);
506 int migrate_send_rp_switchover_ack(MigrationIncomingState
*mis
);
508 void dirty_bitmap_mig_before_vm_start(void);
509 void dirty_bitmap_mig_cancel_outgoing(void);
510 void dirty_bitmap_mig_cancel_incoming(void);
511 bool check_dirty_bitmap_mig_alias_map(const BitmapMigrationNodeAliasList
*bbm
,
514 void migrate_add_address(SocketAddress
*address
);
515 bool migrate_uri_parse(const char *uri
, MigrationChannel
**channel
,
517 int foreach_not_ignored_block(RAMBlockIterFunc func
, void *opaque
);
519 #define qemu_ram_foreach_block \
520 #warning "Use foreach_not_ignored_block in migration code"
522 void migration_make_urgent_request(void);
523 void migration_consume_urgent_request(void);
524 bool migration_rate_limit(void);
525 void migration_bh_schedule(QEMUBHFunc
*cb
, void *opaque
);
526 void migration_cancel(const Error
*error
);
528 void migration_populate_vfio_info(MigrationInfo
*info
);
529 void migration_reset_vfio_bytes_transferred(void);
530 void postcopy_temp_page_reset(PostcopyTmpPage
*tmp_page
);
533 * Migration thread waiting for return path thread. Return non-zero if an
536 int migration_rp_wait(MigrationState
*s
);
538 * Kick the migration thread waiting for return path messages. NOTE: the
539 * name can be slightly confusing (when read as "kick the rp thread"), just
540 * to remember the target is always the migration thread.
542 void migration_rp_kick(MigrationState
*s
);