From 915d73995f518d7592dbbca8776ddbfcb3f205de Mon Sep 17 00:00:00 2001 From: "Richard W.M. Jones" 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 + =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 + =head2 Detailed timings using ts Use the L 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 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. + +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 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 virtual CPUs. + +=item B<-v> + +=item B<--verbose> + +More verbose output, useful for debugging problems. + +=back + +=head1 SEE ALSO + +L, +L. + +=head1 AUTHOR + +Richard W.M. Jones L + +=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 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 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 virtual CPUs. + +=back + +=head1 SEE ALSO + +L, +L. + +=head1 AUTHOR + +Richard W.M. Jones L + +=head1 COPYRIGHT + +Copyright (C) 2016 Red Hat Inc. -- 1.8.3.1