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