Re: [PATCH v2 0/5] Improve KVM per VM monitoring

[Paolo Bonzini <pbonzini@redhat.com>]

On 24/05/2016 10:17, Janosch Frank wrote:
> The script already outputs a help text, which could be extended to the
> man's text. I.e. I left it out on purpose.
> 
> Anyway, creating the manpage from asciidoc sources is a matter of having
> the right packages and simply calling:
> a2x --doctype manpage --format manpage file.txt
> 
> Works flawlessly with your example and is much more readable than the
> texi source. I would give it a try and add it to the first patch if you
> do not have any concerns?

I will include the following as a separate patch:

---------------- 8< ---------------
>From ccceb628a51e52a4b6384e6ef1cc9d88daf00a62 Mon Sep 17 00:00:00 2001
From: Paolo Bonzini <pbonzini@redhat.com>
Date: Tue, 24 May 2016 10:41:15 +0200
Subject: [PATCH] tools: Add kvm_stat man page

Converted from the Texinfo source in QEMU to asciidoc.  The a2x
incantation was provided by Frank Janosch.

Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
---
 tools/kvm/kvm_stat/Makefile     | 40 ++++++++++++++++++++++++--
 tools/kvm/kvm_stat/kvm_stat.txt | 62 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 100 insertions(+), 2 deletions(-)
 create mode 100644 tools/kvm/kvm_stat/kvm_stat.txt

diff --git a/tools/kvm/kvm_stat/Makefile b/tools/kvm/kvm_stat/Makefile
index c639b8d30688..5b1cba57e3b3 100644
--- a/tools/kvm/kvm_stat/Makefile
+++ b/tools/kvm/kvm_stat/Makefile
@@ -1,5 +1,41 @@
+include ../../scripts/Makefile.include
+include ../../scripts/utilities.mak
 BINDIR=usr/bin
+MANDIR=usr/share/man
+MAN1DIR=$(MANDIR)/man1
 
-install:
-	mkdir -p $(INSTALL_ROOT)/$(BINDIR)
+MAN1=kvm_stat.1
+
+A2X=a2x
+a2x_path := $(call get-executable,$(A2X))
+
+all: man
+
+ifneq ($(findstring $(MAKEFLAGS),s),s)
+  ifneq ($(V),1)
+     QUIET_A2X = @echo '  A2X     '$@;
+  endif
+endif
+
+%.1: %.txt
+ifeq ($(a2x_path),)
+	$(error "You need to install asciidoc for man pages")
+else
+	$(QUIET_A2X)$(A2X) --doctype manpage --format manpage $<
+endif
+
+clean:
+	rm -f $(MAN1)
+
+man: $(MAN1)
+
+install-man: man
+	install -d -m 755 $(INSTALL_ROOT)/$(MAN1DIR)
+	install -m 644 kvm_stat.1 $(INSTALL_ROOT)/$(MAN1DIR)
+
+install-tools:
+	install -d -m 755 $(INSTALL_ROOT)/$(BINDIR)
 	install -m 755 -p "kvm_stat" "$(INSTALL_ROOT)/$(BINDIR)/$(TARGET)"
+
+install: install-tools install-man
+.PHONY: all clean man install-tools install-man install
diff --git a/tools/kvm/kvm_stat/kvm_stat.txt b/tools/kvm/kvm_stat/kvm_stat.txt
new file mode 100644
index 000000000000..039dee80ddcb
--- /dev/null
+++ b/tools/kvm/kvm_stat/kvm_stat.txt
@@ -0,0 +1,62 @@
+kvm_stat(1)
+===========
+
+NAME
+----
+kvm_stat - Report KVM kernel module event counters
+
+SYNOPSIS
+--------
+[verse]
+'kvm_stat' [OPTION]...
+
+DESCRIPTION
+-----------
+kvm_stat prints counts of KVM kernel module trace events.  These events signify
+state transitions such as guest mode entry and exit.
+
+This tool is useful for observing guest behavior from the host perspective.
+Often conclusions about performance or buggy behavior can be drawn from the
+output.
+
+The set of KVM kernel module trace events may be specific to the kernel version
+or architecture.  It is best to check the KVM kernel module source code for the
+meaning of events.
+
+Note that trace events are counted globally across all running guests.
+
+OPTIONS
+-------
+-1::
+--once::
+--batch::
+	run in batch mode for one second
+
+-l::
+--log::
+	run in logging mode (like vmstat)
+
+-t::
+--tracepoints::
+	retrieve statistics from tracepoints
+
+-d::
+--debugfs::
+	retrieve statistics from debugfs
+
+-f<fields>::
+--fields=<fields>::
+	fields to display (regex)
+
+-h::
+--help::
+
+  show help message
+
+SEE ALSO
+--------
+'perf'(1), 'trace-cmd'(1)
+
+AUTHOR
+------
+Stefan Hajnoczi <stefanha@redhat.com>
-- 
1.8.3.1