@@ -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)
new file mode 100644
@@ -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
@@ -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
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