From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from [140.186.70.92] (port=36366 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1OQugh-0003Dj-5v for qemu-devel@nongnu.org; Tue, 22 Jun 2010 00:02:16 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1OQugf-0000ss-Cx for qemu-devel@nongnu.org; Tue, 22 Jun 2010 00:02:14 -0400 Received: from e23smtp06.au.ibm.com ([202.81.31.148]:56759) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1OQuge-0000so-R1 for qemu-devel@nongnu.org; Tue, 22 Jun 2010 00:02:13 -0400 Received: from d23relay03.au.ibm.com (d23relay03.au.ibm.com [202.81.31.245]) by e23smtp06.au.ibm.com (8.14.4/8.13.1) with ESMTP id o5M424tt009615 for ; Tue, 22 Jun 2010 14:02:04 +1000 Received: from d23av01.au.ibm.com (d23av01.au.ibm.com [9.190.234.96]) by d23relay03.au.ibm.com (8.13.8/8.13.8/NCO v10.0) with ESMTP id o5M42BwS1220806 for ; Tue, 22 Jun 2010 14:02:11 +1000 Received: from d23av01.au.ibm.com (loopback [127.0.0.1]) by d23av01.au.ibm.com (8.14.4/8.13.1/NCO v10.0 AVout) with ESMTP id o5M42AF3003373 for ; Tue, 22 Jun 2010 14:02:11 +1000 Date: Tue, 22 Jun 2010 09:32:06 +0530 From: Mahesh Salgaonkar Message-ID: <20100622040206.GD27051@in.ibm.com> References: <20100622040018.044362998@mars.in.ibm.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline; filename="core-filter-docs.patch" Subject: [Qemu-devel] [patch 3/3] QEMU-C-F: qemu-core-filter documentation List-Id: qemu-devel.nongnu.org List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: qemu-devel@nongnu.org Cc: Ananth N Mavinakayanahalli , Mahesh Salgaonkar , Maneesh Soni , Michael Mueller , Reinhard Buendgen 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 --- 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