[Qemu-devel] [patch 3/3] QEMU-C-F: qemu-core-filter documentation

[Mahesh Salgaonkar <mahesh@linux.vnet.ibm.com>]

[-- Attachment #1: core-filter-docs.patch --]
[-- Type: text/plain, Size: 5310 bytes --]

Introduce documentation for qemu-core-filter in .texi format and update
Makefile to generate man page. Modified qemu-doc.texi to include documentation
for qemu-core-filter tool as a new chapter.

Signed-off-by: Mahesh Salgaonkar <mahesh@linux.vnet.ibm.com>
---

 Makefile              |   14 ++++++--
 qemu-core-filter.texi |   84 +++++++++++++++++++++++++++++++++++++++++++++++++
 qemu-doc.texi         |    6 ++++
 3 files changed, 101 insertions(+), 3 deletions(-)
 create mode 100644 qemu-core-filter.texi


diff --git a/Makefile b/Makefile
index 1174628..46f2873 100644
--- a/Makefile
+++ b/Makefile
@@ -29,7 +29,7 @@ $(call set-vpath, $(SRC_PATH):$(SRC_PATH)/hw)
 LIBS+=-lz $(LIBS_TOOLS)
 
 ifdef BUILD_DOCS
-DOCS=qemu-doc.html qemu-tech.html qemu.1 qemu-img.1 qemu-nbd.8 QMP/qmp-commands.txt
+DOCS=qemu-doc.html qemu-tech.html qemu.1 qemu-img.1 qemu-nbd.8 QMP/qmp-commands.txt qemu-core-filter.8
 else
 DOCS=
 endif
@@ -205,6 +205,7 @@ ifdef CONFIG_POSIX
 	$(INSTALL_DATA) qemu.1 qemu-img.1 "$(DESTDIR)$(mandir)/man1"
 	$(INSTALL_DIR) "$(DESTDIR)$(mandir)/man8"
 	$(INSTALL_DATA) qemu-nbd.8 "$(DESTDIR)$(mandir)/man8"
+	$(INSTALL_DATA) qemu-core-filter.8 "$(DESTDIR)$(mandir)/man8"
 endif
 
 install-sysconfig:
@@ -290,6 +291,12 @@ qemu-nbd.8: qemu-nbd.texi
 	  pod2man --section=8 --center=" " --release=" " qemu-nbd.pod > $@, \
 	  "  GEN   $@")
 
+qemu-core-filter.8: qemu-core-filter.texi
+	$(call quiet-command, \
+	  perl -Ww -- $(SRC_PATH)/texi2pod.pl $< qemu-core-filter.pod && \
+	  pod2man --section=8 --center=" " --release=" \
+	  " qemu-core-filter.pod > $@, "  GEN   $@")
+
 dvi: qemu-doc.dvi qemu-tech.dvi
 html: qemu-doc.html qemu-tech.html
 info: qemu-doc.info qemu-tech.info
@@ -297,7 +304,7 @@ pdf: qemu-doc.pdf qemu-tech.pdf
 
 qemu-doc.dvi qemu-doc.html qemu-doc.info qemu-doc.pdf: \
 	qemu-img.texi qemu-nbd.texi qemu-options.texi \
-	qemu-monitor.texi qemu-img-cmds.texi
+	qemu-monitor.texi qemu-img-cmds.texi qemu-core-filter.texi
 
 VERSION ?= $(shell cat VERSION)
 FILE = qemu-$(VERSION)
@@ -344,7 +351,8 @@ tarbin:
 	$(docdir)/qemu-tech.html \
 	$(mandir)/man1/qemu.1 \
 	$(mandir)/man1/qemu-img.1 \
-	$(mandir)/man8/qemu-nbd.8
+	$(mandir)/man8/qemu-nbd.8 \
+	$(mandir)/man8/qemu-core-filter.8
 
 # Include automatically generated dependency files
 -include $(wildcard *.d audio/*.d slirp/*.d block/*.d net/*.d)
diff --git a/qemu-core-filter.texi b/qemu-core-filter.texi
new file mode 100644
index 0000000..4253933
--- /dev/null
+++ b/qemu-core-filter.texi
@@ -0,0 +1,84 @@
+@example
+@c man begin SYNOPSIS
+usage: qemu-core-filter	[OPTION] @var{CORE} @var{DUMPFILE}
+@c man end
+@end example
+
+@c man begin DESCRIPTION
+When qemu[-kvm] application crashes it creats a huge coredump file that
+contains guest OS memory. qemu-core-filter creates a small @var{DUMPFILE} by
+excluding Guest OS memory pages using symbol information from qemu debuginfo.
+qemu-core-filter needs qemu[-kvm] debug information to locate guest OS memory.
+By default qemu-core-filter searches qemu[-kvm] debuginfo file in global debug
+directory named @b{/usr/lib/debug} with the help of unique build-id from
+coredump file. The debug information can be taken from
+@b{/usr/lib/debug/usr/bin/qemu[-kvm].debug} file.
+
+@b{Example:}
+
+# qemu-core-filter core core.out
+
+@c man end
+
+@c man begin OPTIONS
+@table @option
+@item -s|--symbol @var{FILENAME}
+
+Specify a qemu debuginfo file that contains symbol table. By default
+(without @b{-s} option) qemu-core-filter looks for debuginfo file under
+@b{/usr/lib/debug} directory. Use this option if qemu-core-filter is unable to
+find debuginfo file or it is located in different directory other than global
+debug directory.
+
+@b{Example:}
+
+# qemu-core-filter -s /usr/lib/debug/usr/bin/qemu-kvm.debug core
+core.out
+
+@b{NOTE:}  For qemu-core-filter built with elfutils <= 0.137 (or without
+build-id support), it is user's resposiblity to provide matching/correct
+debuginfo file otherwise the tool will not produce expected results.
+
+@item -d
+Print debugging message.
+
+@item -f|--force
+Force overwrite of o/p @var{DUMPFILE} if already exists.
+
+@item @var{CORE}
+This is a pathname to the qemu coredump file.
+
+@item @var{DUMPFILE}
+This is a pathname to a file to be created by this command.
+
+@item -h
+Show help message.
+
+@end table
+
+@c man end
+
+@c man begin RETURN CODES
+
+qemu-core-filter returns 0 on success and no-zero value on failure.
+
+@c man end
+
+@ignore
+
+@setfilename qemu-core-filter
+@settitle filter out Guest OS memory from qemu coredump file.
+
+@c man begin AUTHOR
+IBM Corporation          http://www.ibm.com
+@c man end
+
+@node Copyright
+
+@section Copyright
+Licensed Materials  -    Property of IBM
+
+(C) Copyright IBM Corp.2010 All Rights Reserved
+@bye
+
+@end ignore
diff --git a/qemu-doc.texi b/qemu-doc.texi
index e2c8e56..0b228a0 100644
--- a/qemu-doc.texi
+++ b/qemu-doc.texi
@@ -37,6 +37,7 @@
 * QEMU System emulator for non PC targets::
 * QEMU User space emulator::
 * compilation:: Compilation from the sources
+* QEMU User space core filter tool::
 * License::
 * Index::
 @end menu
@@ -2536,6 +2537,11 @@ TODO
 
 @end table
 
+@node QEMU User space core filter tool
+@chapter QEMU User space core filter tool
+
+@include qemu-core-filter.texi
+
 @node License
 @appendix License