doc update - added qemu-img manual page

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

5 files changed, 155 insertions, 173 deletions

diff --git a/.cvsignore b/.cvsignore
index bca4882388..42bc1c7544 100644
--- a/.cvsignore
+++ b/.cvsignore
@@ -10,6 +10,8 @@ qemu-doc.html
 qemu-tech.html
 qemu.1
 qemu.pod
+qemu-img.1
+qemu-img.pod
 sparc-user
 qemu-img
 sparc-softmmu
diff --git a/Makefile b/Makefile
index c9c7e9bc8a..e422228729 100644
--- a/Makefile
+++ b/Makefile
@@ -14,7 +14,7 @@ TOOLS=qemu-img
 ifdef CONFIG_STATIC
 LDFLAGS+=-static
 endif
-DOCS=qemu-doc.html qemu-tech.html qemu.1
+DOCS=qemu-doc.html qemu-tech.html qemu.1 qemu-img.1
 
 all: dyngen$(EXESUF) $(TOOLS) $(DOCS)
 	for d in $(TARGET_DIRS); do \
@@ -30,7 +30,7 @@ dyngen$(EXESUF): dyngen.c
 clean:
 # avoid old build problems by removing potentially incorrect old files
 	rm -f config.mak config.h op-i386.h opc-i386.h gen-op-i386.h op-arm.h opc-arm.h gen-op-arm.h 
-	rm -f *.o *.a $(TOOLS) dyngen$(EXESUF) TAGS qemu.pod *~ */*~
+	rm -f *.o *.a $(TOOLS) dyngen$(EXESUF) TAGS *.pod *~ */*~
 	$(MAKE) -C tests clean
 	for d in $(TARGET_DIRS); do \
 	$(MAKE) -C $$d $@ || exit 1 ; \
@@ -57,7 +57,7 @@ endif
 	install -m 644 qemu-doc.html  qemu-tech.html "$(docdir)"
 ifndef CONFIG_WIN32
 	mkdir -p "$(mandir)/man1"
-	install qemu.1 qemu-mkcow.1 "$(mandir)/man1"
+	install qemu.1 qemu-img.1 "$(mandir)/man1"
 endif
 	for d in $(TARGET_DIRS); do \
 	$(MAKE) -C $$d $@ || exit 1 ; \
@@ -78,6 +78,10 @@ qemu.1: qemu-doc.texi
 	./texi2pod.pl $< qemu.pod
 	pod2man --section=1 --center=" " --release=" " qemu.pod > $@
 
+qemu-img.1: qemu-img.texi
+	./texi2pod.pl $< qemu-img.pod
+	pod2man --section=1 --center=" " --release=" " qemu-img.pod > $@
+
 FILE=qemu-$(shell cat VERSION)
 
 # tar release (use 'make -k tar' on a checkouted tree)
@@ -92,6 +96,7 @@ tarbin:
 	( cd / ; tar zcvf ~/qemu-$(VERSION)-i386.tar.gz \
 	$(bindir)/qemu $(bindir)/qemu-fast \
 	$(bindir)/qemu-system-ppc \
+	$(bindir)/qemu-system-sparc \
 	$(bindir)/qemu-i386 \
         $(bindir)/qemu-arm \
         $(bindir)/qemu-sparc \
@@ -105,7 +110,7 @@ tarbin:
 	$(datadir)/linux_boot.bin \
 	$(docdir)/qemu-doc.html \
 	$(docdir)/qemu-tech.html \
-	$(mandir)/man1/qemu.1 $(mandir)/man1/qemu-mkcow.1 )
+	$(mandir)/man1/qemu.1 $(mandir)/man1/qemu-img.1 )
 
 ifneq ($(wildcard .depend),)
 include .depend
diff --git a/qemu-doc.texi b/qemu-doc.texi
index c262ee7e9c..732f40f367 100644
--- a/qemu-doc.texi
+++ b/qemu-doc.texi
@@ -584,81 +584,34 @@ CPU registers by prefixing them with @emph{$}.
 @node disk_images
 @section Disk Images
 
-@subsection Raw disk images
+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.
 
-The disk images can simply be raw images of the hard disk. You can
-create them with the command:
+@subsection Quick start for disk image creation
+
+You can create a disk image with the command:
 @example
-dd of=myimage bs=1024 seek=mysize count=0
+qemu-img create myimage.img mysize
 @end example
-where @var{myimage} is the image filename and @var{mysize} is its size
-in kilobytes.
+where @var{myimage.img} is the disk image filename and @var{mysize} is its
+size in kilobytes. You can add an @code{M} suffix to give the size in
+megabytes and a @code{G} suffix for gigabytes.
+
+@xref{qemu_img_invocation} for more information.
 
 @subsection Snapshot mode
 
 If you use the option @option{-snapshot}, all disk images are
 considered as read only. When sectors in written, they are written in
 a temporary file created in @file{/tmp}. You can however force the
-write back to the raw disk images by pressing @key{C-a s}.
-
-NOTE: The snapshot mode only works with raw disk images.
-
-@subsection Copy On Write disk images
-
-QEMU also supports user mode Linux
-(@url{http://user-mode-linux.sourceforge.net/}) Copy On Write (COW)
-disk images. The COW disk images are much smaller than normal images
-as they store only modified sectors. They also permit the use of the
-same disk image template for many users.
-
-To create a COW disk images, use the command:
-
-@example
-qemu-mkcow -f myrawimage.bin mycowimage.cow
-@end example
-
-@file{myrawimage.bin} is a raw image you want to use as original disk
-image. It will never be written to.
-
-@file{mycowimage.cow} is the COW disk image which is created by
-@code{qemu-mkcow}. You can use it directly with the @option{-hdx}
-options. You must not modify the original raw disk image if you use
-COW images, as COW images only store the modified sectors from the raw
-disk image. QEMU stores the original raw disk image name and its
-modified time in the COW disk image so that chances of mistakes are
-reduced.
-
-If the raw disk image is not read-only, by pressing @key{C-a s} you
-can flush the COW disk image back into the raw disk image, as in
-snapshot mode.
+write back to the raw disk images by using the @code{commit} monitor
+command (or @key{C-a s} in the serial console).
 
-COW disk images can also be created without a corresponding raw disk
-image. It is useful to have a big initial virtual disk image without
-using much disk space. Use:
+@node qemu_img_invocation
+@subsection @code{qemu-img} Invocation
 
-@example
-qemu-mkcow mycowimage.cow 1024
-@end example
-
-to create a 1 gigabyte empty COW disk image.
-
-NOTES: 
-@enumerate
-@item
-COW disk images must be created on file systems supporting
-@emph{holes} such as ext2 or ext3.
-@item 
-Since holes are used, the displayed size of the COW disk image is not
-the real one. To know it, use the @code{ls -ls} command.
-@end enumerate
-
-@subsection Convert VMware disk images to raw disk images
-
-You can use the tool @file{vmdk2raw} to convert VMware disk images to
-raw disk images directly usable by QEMU. The syntax is:
-@example
-vmdk2raw vmware_image output_image
-@end example
+@include qemu-img.texi
 
 @section Network emulation
 
diff --git a/qemu-img.texi b/qemu-img.texi
new file mode 100644
index 0000000000..3afd320851
--- /dev/null
+++ b/qemu-img.texi
@@ -0,0 +1,127 @@
+@example
+@c man begin SYNOPSIS
+usage: qemu-img command [command options]
+@c man end
+@end example
+
+@c man begin OPTIONS
+
+The following commands are supported:
+@table @option
+@item create [-e] [-b @var{base_image}] [-f @var{fmt}] @var{filename} [@var{size}]
+@item commit [-f @var{fmt}] @var{filename}
+@item convert [-c] [-e] [-f @var{fmt}] @var{filename} [-O @var{output_fmt}] @var{output_filename}
+@item info [-f @var{fmt}] @var{filename}
+@end table
+
+Command parameters:
+@table @var
+@item filename
+ is a disk image filename
+@item base_image 
+is the read-only disk image which is used as base for a copy on
+    write image; the copy on write image only stores the modified data
+
+@item fmt 
+is the disk image format. It is guessed automatically in most cases. The following formats are supported:
+
+@table @code
+@item raw
+
+Raw disk image format (default). This format has the advantage of
+being simple and easily exportable to all other emulators. If your file
+system supports @emph{holes} (for example in ext2 or ext3 on Linux),
+then only the written sectors will reserve space. Use @code{qemu-img
+info} to know the real size used by the image or @code{ls -ls} on
+Unix/Linux.
+
+@item qcow
+QEMU image format, the most versatile format. Use it to have smaller
+images (useful if your filesystem does not supports holes, for example
+on Windows), optional AES encryption and zlib based compression.
+@item cow
+User Mode Linux Copy On Write image format. Used to be the only growable
+image format in QEMU. It is supported only for compatibility with
+previous versions. It does not work on win32.
+@item vmdk
+VMware 3 and 4 compatible image format. Currently only supported as
+read-only.
+@item cloop
+Linux Compressed Loop image, useful only to reuse directly compressed
+CD-ROM images present for example in the Knoppix CD-ROMs.
+@end table
+
+@item size 
+is the disk image size in kilobytes. Optional suffixes @code{M}
+(megabyte) and @code{G} (gigabyte) are supported 
+
+@item output_filename
+is the destination disk image filename 
+
+@item output_fmt
+ is the destination format
+
+@item -c
+indicates that target image must be compressed (qcow format only)
+@item -e 
+indicates that the target image must be encrypted (qcow format only)
+@end table
+
+Command description:
+
+@table @option
+@item create [-e] [-b @var{base_image}] [-f @var{fmt}] @var{filename} [@var{size}]
+
+Create the new disk image @var{filename} of size @var{size} and format
+@var{fmt}. 
+
+If @var{base_image} is specified, then the image will record only the
+differences from @var{base_image}. No size needs to be specified in
+this case. @var{base_image} will never be modified unless you use the
+@code{commit} monitor command.
+
+@item commit [-f @var{fmt}] @var{filename}
+
+Commit the changes recorded in @var{filename} in its base image.
+
+@item convert [-c] [-e] [-f @var{fmt}] @var{filename} [-O @var{output_fmt}] @var{output_filename}
+
+Convert the disk image @var{filename} to disk image @var{output_filename}
+using format @var{output_fmt}. It can be optionnaly encrypted
+(@code{-e} option) or compressed (@code{-c} option).
+
+Only the format @code{qcow} supports encryption or compression. The
+compression is read-only. It means that if a compressed sector is
+rewritten, then it is rewritten as uncompressed data.
+
+Encryption uses the AES format which is very secure (128 bit keys). Use
+a long password (16 characters) to get maximum protection.
+
+Image conversion is also useful to get smaller image when using a
+growable format such as @code{qcow} or @code{cow}: the empty sectors
+are detected and suppressed from the destination image.
+
+@item info [-f @var{fmt}] @var{filename}
+
+Give information about the disk image @var{filename}. Use it in
+particular to know the size reserved on disk which can be different
+from the displayed size.
+@end table
+
+@c man end
+
+@ignore
+
+@setfilename qemu-img
+@settitle QEMU disk image utility
+
+@c man begin SEEALSO
+The HTML documentation of QEMU for more precise information and Linux
+user mode emulator invocation.
+@c man end
+
+@c man begin AUTHOR
+Fabrice Bellard
+@c man end
+
+@end ignore
diff --git a/qemu-mkcow.1 b/qemu-mkcow.1
deleted file mode 100644
index 5e1a6812be..0000000000
--- a/qemu-mkcow.1
+++ /dev/null
@@ -1,105 +0,0 @@
-.\" $Header: /home/paul/qemu/svnmerge/qemu-cvs/qemu/qemu-mkcow.1,v 1.1 2004-03-26 22:42:54 bellard Exp $
-.\"
-.\"	transcript compatibility for postscript use.
-.\"
-.\"	synopsis:  .P! <file.ps>
-.\"
-.de P!
-.fl
-\!!1 setgray
-.fl
-\\&.\"
-.fl
-\!!0 setgray
-.fl			\" force out current output buffer
-\!!save /psv exch def currentpoint translate 0 0 moveto
-\!!/showpage{}def
-.fl			\" prolog
-.sy sed -e 's/^/!/' \\$1\" bring in postscript file
-\!!psv restore
-.
-.de pF
-.ie     \\*(f1 .ds f1 \\n(.f
-.el .ie \\*(f2 .ds f2 \\n(.f
-.el .ie \\*(f3 .ds f3 \\n(.f
-.el .ie \\*(f4 .ds f4 \\n(.f
-.el .tm ? font overflow
-.ft \\$1
-..
-.de fP
-.ie     !\\*(f4 \{\
-.	ft \\*(f4
-.	ds f4\"
-'	br \}
-.el .ie !\\*(f3 \{\
-.	ft \\*(f3
-.	ds f3\"
-'	br \}
-.el .ie !\\*(f2 \{\
-.	ft \\*(f2
-.	ds f2\"
-'	br \}
-.el .ie !\\*(f1 \{\
-.	ft \\*(f1
-.	ds f1\"
-'	br \}
-.el .tm ? font underflow
-..
-.ds f1\"
-.ds f2\"
-.ds f3\"
-.ds f4\"
-'\" t 
-.ta 8n 16n 24n 32n 40n 48n 56n 64n 72n  
-.TH "QEMU" "8" 
-.SH "NAME" 
-qemu-mkcow \(em create a copy-on-write file for qemu 
-.SH "SYNOPSIS" 
-.PP 
-\fBqemu-mkcow\fR [\fB-h\fP]  [\fB-f \fImaster_disk_image\fR\fP]  [\fIcow_image\fR]  [\fB\fIcow_size\fR\fP]  
-.SH "DESCRIPTION" 
-.PP 
-The \fBqemu-mkcow\fR command creates a 
-persistent copy-on-write file for \fBqemu\fR. 
- 
-.PP 
-\fBqemu\fR can be used in a "copy-on-write" mode, 
-where changes made by \fBqemu\fR do not actually 
-change the disk image file.  One way is to invoke 
-\fBqemu\fR with -snapshot: these changes 
-are stored in a temporary file, which is discarded when  
-\fBqemu\fR exits. 
- 
-.PP 
-\fBqemu-mkcow\fR creates an explicit copy-on-write 
-file where changes are to be stored: this way, changes made 
-inside \fBqemu\fR will still be there next time you 
-run it, although the master disk image isn't ever changed. 
- 
-.PP 
-The usual method is to create the master image, then create a 
-copy-on-write file using \fBqemu-mkcow\fR with 
-\fB-f\fP.  The filename of the master image is stored 
-inside the generated copy-on-write file: it must not be modified 
-after this is run! 
- 
-.PP 
-If no master file is specified, the effect is that of a 
-blank master of size \fIcow_size\fR. 
- 
-.SH "SEE ALSO" 
-.PP 
-qemu(1), qemu-fast(1). 
-.SH "AUTHOR" 
-.PP 
-This manual page was written by Paul Russell prussell@debian.org for 
-the \fBDebian\fP system (but may be used by others).  Permission is 
-granted to copy, distribute and/or modify this document under 
-the terms of the GNU General Public License, Version 2 any  
-later version published by the Free Software Foundation. 
- 
-.PP 
-On Debian systems, the complete text of the GNU General Public 
-License can be found in /usr/share/common-licenses/GPL. 
- 
-.\" created by instant / docbook-to-man, Fri 12 Mar 2004, 05:58