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 <mah...@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
