From 915d73995f518d7592dbbca8776ddbfcb3f205de Mon Sep 17 00:00:00 2001
From: "Richard W.M. Jones" <rjones@redhat.com>
Date: Tue, 3 May 2016 13:05:54 +0100
Subject: [PATCH] utils/boot-analysis, utils/boot-benchmark: Add manual pages.
(cherry picked from commit 98b28b15c61e871c3b3c5efdf4387e570133c4f9)
---
.gitignore | 2 +
docs/guestfs-performance.pod | 4 ++
utils/boot-analysis/Makefile.am | 13 +++++
utils/boot-analysis/boot-analysis.c | 39 +------------
utils/boot-analysis/boot-analysis.pod | 99 +++++++++++++++++++++++++++++++++
utils/boot-benchmark/Makefile.am | 13 ++++-
utils/boot-benchmark/boot-benchmark.c | 2 +-
utils/boot-benchmark/boot-benchmark.pod | 68 ++++++++++++++++++++++
8 files changed, 200 insertions(+), 40 deletions(-)
create mode 100644 utils/boot-analysis/boot-analysis.pod
create mode 100644 utils/boot-benchmark/boot-benchmark.pod
diff --git a/.gitignore b/.gitignore
index d79dc98..85b19d4 100644
--- a/.gitignore
+++ b/.gitignore
@@ -558,7 +558,9 @@ Makefile.in
/tools/stamp-virt-*.pod
/tools/virt-*.1
/utils/boot-analysis/boot-analysis
+/utils/boot-analysis/boot-analysis.1
/utils/boot-benchmark/boot-benchmark
+/utils/boot-benchmark/boot-benchmark.1
/utils/qemu-boot/qemu-boot
/utils/qemu-speed-test/qemu-speed-test
/v2v/.depend
diff --git a/docs/guestfs-performance.pod b/docs/guestfs-performance.pod
index 7304b63..b6c25e1 100644
--- a/docs/guestfs-performance.pod
+++ b/docs/guestfs-performance.pod
@@ -38,6 +38,8 @@ run it, do:
make
./run utils/boot-benchmark/boot-benchmark
+There is a manual page F<utils/boot-benchmark/boot-benchmark.1>
+
=head3 Explanation
The guestfish command above starts up the libguestfs appliance on a
@@ -453,6 +455,8 @@ To run this program, do:
make
./run utils/boot-analysis/boot-analysis
+There is a manual page F<utils/boot-benchmark/boot-analysis.1>
+
=head2 Detailed timings using ts
Use the L<ts(1)> command (from moreutils) to show detailed
diff --git a/utils/boot-analysis/Makefile.am b/utils/boot-analysis/Makefile.am
index ef9b2cb..d708de2 100644
--- a/utils/boot-analysis/Makefile.am
+++ b/utils/boot-analysis/Makefile.am
@@ -17,6 +17,8 @@
include $(top_srcdir)/subdir-rules.mk
+EXTRA_DIST = boot-analysis.pod
+
noinst_PROGRAMS = boot-analysis
boot_analysis_SOURCES = \
@@ -41,3 +43,14 @@ boot_analysis_LDADD = \
$(LTLIBINTL) \
$(top_builddir)/gnulib/lib/libgnu.la \
-lm
+
+# Manual page.
+# It should be noinst_MANS but that doesn't work.
+noinst_DATA = boot-analysis.1
+
+boot-analysis.1: boot-analysis.pod
+ $(PODWRAPPER) \
+ --man $@ \
+ --license GPLv2+ \
+ --warning safe \
+ $<
diff --git a/utils/boot-analysis/boot-analysis.c b/utils/boot-analysis/boot-analysis.c
index b90806b..461c69e 100644
--- a/utils/boot-analysis/boot-analysis.c
+++ b/utils/boot-analysis/boot-analysis.c
@@ -16,44 +16,7 @@
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
*/
-/* Trace and analyze the appliance boot process to find out which
- * steps are taking the most time. It is not part of the standard
- * tests.
- *
- * This needs to be run on a quiet machine, so that other processes
- * disturb the timing as little as possible. The program is
- * completely safe to run at any time. It doesn't read or write any
- * external files, and it doesn't require root.
- *
- * You can run it from the build directory like this:
- *
- * make
- * ./run utils/boot-analysis/boot-analysis
- *
- * The way it works is roughly like this:
- *
- * We create a libguestfs handle and register callback handlers so we
- * can see appliance messages, trace events and so on.
- *
- * We then launch the handle and shut it down as quickly as possible.
- *
- * While the handle is running, events (seen by the callback handlers)
- * are written verbatim into an in-memory buffer, with timestamps.
- *
- * Afterwards we analyze the result using regular expressions to try
- * to identify a "timeline" for the handle (eg. at what time did the
- * BIOS hand control to the kernel). This analysis is done in
- * 'boot-analysis-timeline.c'.
- *
- * The whole process is repeated across a few runs, and the final
- * timeline (including statistical analysis of the variation between
- * runs) gets printed.
- *
- * The program is very sensitive to the specific messages printed by
- * BIOS/kernel/supermin/userspace, so it won't work on non-x86, and it
- * will require periodic adjustment of the regular expressions in
- * order to keep things up to date.
- */
+/* See instructions in boot-analysis.1 */
#include <config.h>
diff --git a/utils/boot-analysis/boot-analysis.pod b/utils/boot-analysis/boot-analysis.pod
new file mode 100644
index 0000000..07cc801
--- /dev/null
+++ b/utils/boot-analysis/boot-analysis.pod
@@ -0,0 +1,99 @@
+=head1 NAME
+
+boot-analysis - Trace and analyze the appliance boot process
+
+=head1 SYNOPSIS
+
+ ./run utils/boot-analysis/boot-analysis
+
+=head1 DESCRIPTION
+
+Trace and analyze the appliance boot process to find out which steps
+are taking the most time. It is not part of the standard tests.
+
+This needs to be run on a quiet machine, so that other processes
+disturb the timing as little as possible. The program is completely
+safe to run at any time. It doesn't read or write any external files,
+and it doesn't require root.
+
+You can run it from the build directory on the built copy of
+libguestfs like this:
+
+ make
+ ./run utils/boot-analysis/boot-analysis
+
+If you omit C<./run> then it is run on the installed copy of libguestfs.
+
+=head2 How it works
+
+We create a libguestfs handle and register callback handlers so we
+can see appliance messages, trace events and so on.
+
+We then launch the handle and shut it down as quickly as possible.
+
+While the handle is running, events (seen by the callback handlers)
+are written verbatim into an in-memory buffer, with timestamps.
+
+Afterwards we analyze the result using regular expressions to try to
+identify a "timeline" for the handle (eg. at what time did the BIOS
+hand control to the kernel). This analysis is done in
+F<utils/boot-analysis/boot-analysis-timeline.c>.
+
+The whole process is repeated across a few runs, and the final
+timeline (including statistical analysis of the variation between
+runs) gets printed.
+
+The program is very sensitive to the specific messages printed by
+BIOS/kernel/supermin/userspace. It only works on x86-64 or aarch64.
+It will require periodic adjustment of the regular expressions in
+order to keep things up to date.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<--help>
+
+Display brief help.
+
+=item B<--append> "OPTIONS"
+
+Append C<OPTIONS> to the kernel command line.
+
+=item B<--color>
+
+=item B<--colour>
+
+Output colours (as ANSI escape sequences), even if the output is not a
+terminal.
+
+=item B<-m> MB
+
+=item B<--memsize> MB
+
+Set the appliance memory size in MB.
+
+=item B<--smp> N
+
+Enable C<N> virtual CPUs.
+
+=item B<-v>
+
+=item B<--verbose>
+
+More verbose output, useful for debugging problems.
+
+=back
+
+=head1 SEE ALSO
+
+L<guestfs-performance(1)>,
+L<http://libguestfs.org/>.
+
+=head1 AUTHOR
+
+Richard W.M. Jones L<http://people.redhat.com/~rjones/>
+
+=head1 COPYRIGHT
+
+Copyright (C) 2016 Red Hat Inc.
diff --git a/utils/boot-benchmark/Makefile.am b/utils/boot-benchmark/Makefile.am
index 429832a..fed2428 100644
--- a/utils/boot-benchmark/Makefile.am
+++ b/utils/boot-benchmark/Makefile.am
@@ -21,6 +21,8 @@
include $(top_srcdir)/subdir-rules.mk
+EXTRA_DIST = boot-benchmark.pod boot-benchmark-range.pl
+
noinst_PROGRAMS = boot-benchmark
boot_benchmark_SOURCES = \
@@ -41,4 +43,13 @@ boot_benchmark_LDADD = \
$(top_builddir)/gnulib/lib/libgnu.la \
-lm
-EXTRA_DIST = boot-benchmark-range.pl
+# Manual page.
+# It should be noinst_MANS but that doesn't work.
+noinst_DATA = boot-benchmark.1
+
+boot-benchmark.1: boot-benchmark.pod
+ $(PODWRAPPER) \
+ --man $@ \
+ --license GPLv2+ \
+ --warning safe \
+ $<
diff --git a/utils/boot-benchmark/boot-benchmark.c b/utils/boot-benchmark/boot-benchmark.c
index 0508ee9..05cab50 100644
--- a/utils/boot-benchmark/boot-benchmark.c
+++ b/utils/boot-benchmark/boot-benchmark.c
@@ -16,7 +16,7 @@
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
*/
-/* Benchmark the time taken to boot the libguestfs appliance. */
+/* See instructions in boot-benchmark.1 */
#include <config.h>
diff --git a/utils/boot-benchmark/boot-benchmark.pod b/utils/boot-benchmark/boot-benchmark.pod
new file mode 100644
index 0000000..b34546a
--- /dev/null
+++ b/utils/boot-benchmark/boot-benchmark.pod
@@ -0,0 +1,68 @@
+=head1 NAME
+
+boot-benchmark - Benchmark the time taken to boot the libguestfs appliance
+
+=head1 SYNOPSIS
+
+ ./run utils/boot-benchmark/boot-benchmark
+
+=head1 DESCRIPTION
+
+Benchmark the time taken to boot the libguestfs appliance.
+
+It is essentially the same as doing:
+
+ time guestfish -a /dev/null run
+
+except that it warms up the caches and repeats the test many times,
+printing out the mean time and standard deviation.
+
+This needs to be run on a quiet machine, so that other processes
+disturb the timing as little as possible. The program is completely
+safe to run at any time. It doesn't read or write any external files,
+and it doesn't require root.
+
+You can run it from the build directory on the built copy of
+libguestfs like this:
+
+ make
+ ./run utils/boot-benchmark/boot-benchmark
+
+If you omit C<./run> then it is run on the installed copy of libguestfs.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<--help>
+
+Display brief help.
+
+=item B<--append> "OPTIONS"
+
+Append C<OPTIONS> to the kernel command line.
+
+=item B<-m> MB
+
+=item B<--memsize> MB
+
+Set the appliance memory size in MB.
+
+=item B<--smp> N
+
+Enable C<N> virtual CPUs.
+
+=back
+
+=head1 SEE ALSO
+
+L<guestfs-performance(1)>,
+L<http://libguestfs.org/>.
+
+=head1 AUTHOR
+
+Richard W.M. Jones L<http://people.redhat.com/~rjones/>
+
+=head1 COPYRIGHT
+
+Copyright (C) 2016 Red Hat Inc.
--
1.8.3.1