save/restore state devices. This infrastructure is shared with the
savevm/loadvm functionality.
-=== State Live Migration ==
+=== State Live Migration ===
This is used for RAM and block devices. It is not yet ported to vmstate.
<Fill more information here>
QEMUFile *qemu_fopen_ops(void *opaque,
QEMUFilePutBufferFunc *put_buffer,
QEMUFileGetBufferFunc *get_buffer,
- QEMUFileCloseFunc *close,
- QEMUFileRateLimit *rate_limit,
- QEMUFileSetRateLimit *set_rate_limit,
- QEMUFileGetRateLimit *get_rate_limit);
+ QEMUFileCloseFunc *close);
The functions have the following functionality:
typedef int (QEMUFileCloseFunc)(void *opaque);
-Called to determine if the file has exceeded its bandwidth allocation. The
-bandwidth capping is a soft limit, not a hard limit.
-
-typedef int (QEMUFileRateLimit)(void *opaque);
-
-Called to change the current bandwidth allocation. This function must return
-the new actual bandwidth. It should be new_rate if everything goes OK, and
-the old rate otherwise.
-
-typedef size_t (QEMUFileSetRateLimit)(void *opaque, size_t new_rate);
-typedef size_t (QEMUFileGetRateLimit)(void *opaque);
-
You can use any internal state that you need using the opaque void *
pointer that is passed to all functions.
-The rate limiting functions are used to limit the bandwidth used by
-QEMU migration.
-
The important functions for us are put_buffer()/get_buffer() that
allow to write/read a buffer into the QEMUFile.
-=== How to save the state of one device ==
+=== How to save the state of one device ===
The state of a device is saved using intermediate buffers. There are
some helper functions to assist this saving.
the state as the newer version. But load_state sometimes is able to
load state from an older version.
- === Legacy way ===
+=== Legacy way ===
This way is going to disappear as soon as all current users are ported to VMSTATE.
the state is declared only once, it can't go out of sync in the
save/load functions.
-An example (from hw/pckbd.c)
+An example (from hw/input/pckbd.c)
static const VMStateDescription vmstate_kbd = {
.name = "pckbd",
Note: talk about how vmstate <-> qdev interact, and what the instance ids mean.
You can search for VMSTATE_* macros for lots of types used in QEMU in
-hw/hw.h.
+include/hw/hw.h.
-=== More about versions ==
+=== More about versions ===
You can see that there are several version fields:
Example: You can look at hpet.c, that uses the three function to
massage the state that is transferred.
+If you use memory API functions that update memory layout outside
+initialization (i.e., in response to a guest action), this is a strong
+indication that you need to call these functions in a post_load callback.
+Examples of such memory API functions are:
+
+ - memory_region_add_subregion()
+ - memory_region_del_subregion()
+ - memory_region_set_readonly()
+ - memory_region_set_enabled()
+ - memory_region_set_address()
+ - memory_region_set_alias_offset()
+
=== Subsections ===
The use of version_id allows to be able to migrate from older versions
It is impossible to create a way to make migration from any version to
any other version to work. But we can do better than only allowing
-migration from older versions no newer ones. For that fields that are
+migration from older versions to newer ones. For that fields that are
only needed sometimes, we add the idea of subsections. A subsection
is "like" a device vmstate, but with a particularity, it has a Boolean
function that tells if that values are needed to be sent or not. If
{
IDEState *s = opaque;
- return (s->status & DRQ_STAT) != 0;
+ return ((s->status & DRQ_STAT) != 0)
+ || (s->bus->error_status & BM_STATUS_PIO_RETRY);
}
const VMStateDescription vmstate_ide_drive_pio_state = {