info about VM snapshots

git-svn-id: svn://svn.savannah.nongnu.org/qemu/trunk@2096 c046a42c-6fe2-441c-8c8c-71466251a162

1 files changed, 68 insertions, 5 deletions

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 USB devices plugged on the virtual USB hub
 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 @@ info capture
 @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 @@ CPU registers by prefixing them with @emph{$}.
 
 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 @@ a temporary file created in @file{/tmp}. You can however force the
 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