info about VM snapshots
git-svn-id: svn://svn.savannah.nongnu.org/qemu/trunk@2096 c046a42c-6fe2-441c-8c8c-71466251a162
diff --git a/qemu-doc.texi b/qemu-doc.texi
index 1e49ccf..9f0b4f6 100644
--- a/qemu-doc.texi
+++ b/qemu-doc.texi
@@ -743,6 +743,8 @@
show all USB host devices
@item info capture
show information about active capturing
+@item info snapshots
+show list of VM snapshots
@end table
@item q or quit
@@ -777,11 +779,18 @@
@item log item1[,...]
Activate logging of the specified items to @file{/tmp/qemu.log}.
-@item savevm filename
-Save the whole virtual machine state to @var{filename}.
+@item savevm [tag|id]
+Create a snapshot of the whole virtual machine. If @var{tag} is
+provided, it is used as human readable identifier. If there is already
+a snapshot with the same tag or ID, it is replaced. More info at
+@ref{vm_snapshots}.
-@item loadvm filename
-Restore the whole virtual machine state from @var{filename}.
+@item loadvm tag|id
+Set the whole virtual machine to the snapshot identified by the tag
+@var{tag} or the unique snapshot ID @var{id}.
+
+@item delvm tag|id
+Delete the snapshot identified by @var{tag} or @var{id}.
@item stop
Stop emulation.
@@ -895,11 +904,14 @@
Since version 0.6.1, QEMU supports many disk image formats, including
growable disk images (their size increase as non empty sectors are
-written), compressed and encrypted disk images.
+written), compressed and encrypted disk images. Version 0.8.3 added
+the new qcow2 disk image format which is essential to support VM
+snapshots.
@menu
* disk_images_quickstart:: Quick start for disk image creation
* disk_images_snapshot_mode:: Snapshot mode
+* vm_snapshots:: VM snapshots
* qemu_img_invocation:: qemu-img Invocation
* disk_images_fat_images:: Virtual FAT disk images
@end menu
@@ -926,6 +938,57 @@
write back to the raw disk images by using the @code{commit} monitor
command (or @key{C-a s} in the serial console).
+@node vm_snapshots
+@subsection VM snapshots
+
+VM snapshots are snapshots of the complete virtual machine including
+CPU state, RAM, device state and the content of all the writable
+disks. In order to use VM snapshots, you must have at least one non
+removable and writable block device using the @code{qcow2} disk image
+format. Normally this device is the first virtual hard drive.
+
+Use the monitor command @code{savevm} to create a new VM snapshot or
+replace an existing one. A human readable name can be assigned to each
+snapshots in addition to its numerical ID.
+
+Use @code{loadvm} to restore a VM snapshot and @code{delvm} to remove
+a VM snapshot. @code{info snapshots} lists the available snapshots
+with their associated information:
+
+@example
+(qemu) info snapshots
+Snapshot devices: hda
+Snapshot list (from hda):
+ID TAG VM SIZE DATE VM CLOCK
+1 start 41M 2006-08-06 12:38:02 00:00:14.954
+2 40M 2006-08-06 12:43:29 00:00:18.633
+3 msys 40M 2006-08-06 12:44:04 00:00:23.514
+@end example
+
+A VM snapshot is made of a VM state info (its size is shown in
+@code{info snapshots}) and a snapshot of every writable disk image.
+The VM state info is stored in the first @code{qcow2} non removable
+and writable block device. The disk image snapshots are stored in
+every disk image. The size of a snapshot in a disk image is difficult
+to evaluate and is not shown by @code{info snapshots} because the
+associated disk sectors are shared among all the snapshots to save
+disk space (otherwise each snapshot would have to copy the full disk
+images).
+
+When using the (unrelated) @code{-snapshot} option
+(@ref{disk_images_snapshot_mode}), you can always make VM snapshots,
+but they are deleted as soon as you exit QEMU.
+
+VM snapshots currently have the following known limitations:
+@itemize
+@item
+They cannot cope with removable devices if they are removed or
+inserted after a snapshot is done.
+@item
+A few device drivers still have incomplete snapshot support so their
+state is not saved or restored properly (in particular USB).
+@end itemize
+
@node qemu_img_invocation
@subsection @code{qemu-img} Invocation
