From 1f10f1663e53474038b9111c4264a250cffe7501 Mon Sep 17 00:00:00 2001
From: Martin Ankerl <martin.ankerl@gmail.com>
Date: Sat, 18 Sep 2021 09:38:58 +0200
Subject: [PATCH] bench: add usage description and documentation

This adds some usage description with tips to `bench_bitcoin -h`.
---
 src/bench/bench_bitcoin.cpp | 47 ++++++++++++++++++++++++++++++++++++-
 1 file changed, 46 insertions(+), 1 deletion(-)

diff --git a/src/bench/bench_bitcoin.cpp b/src/bench/bench_bitcoin.cpp
index ae1e930bb7..6503e38728 100644
--- a/src/bench/bench_bitcoin.cpp
+++ b/src/bench/bench_bitcoin.cpp
@@ -4,6 +4,7 @@
 
 #include <bench/bench.h>
 
+#include <clientversion.h>
 #include <crypto/sha256.h>
 #include <util/strencodings.h>
 #include <util/system.h>
@@ -50,7 +51,51 @@ int main(int argc, char** argv)
     }
 
     if (HelpRequested(argsman)) {
-        std::cout << argsman.GetHelpMessage();
+        std::cout << "Usage:  bench_bitcoin [options]\n"
+                     "\n"
+                  << argsman.GetHelpMessage()
+                  << "Description:\n"
+                     "\n"
+                     "  bench_bitcoin executes microbenchmarks. The quality of the benchmark results\n"
+                     "  highly depend on the stability of the machine. It can sometimes be difficult\n"
+                     "  to get stable, repeatable results, so here are a few tips:\n"
+                     "\n"
+                     "  * Use pyperf [1] to disable frequency scaling, turbo boost etc. For best\n"
+                     "    results, use CPU pinning and CPU isolation (see [2]).\n"
+                     "\n"
+                     "  * Each call of run() should do exactly the same work. E.g. inserting into\n"
+                     "    a std::vector doesn't do that as it will reallocate on certain calls. Make\n"
+                     "    sure each run has exactly the same preconditions.\n"
+                     "\n"
+                     "  * If results are still not reliable, increase runtime with e.g.\n"
+                     "    -min_time=5000 to let a benchmark run for at least 5 seconds.\n"
+                     "\n"
+                     "  * bench_bitcoin uses nanobench [3] for which there is extensive\n"
+                     "    documentation available online.\n"
+                     "\n"
+                     "Environment Variables:\n"
+                     "\n"
+                     "  To attach a profiler you can run a benchmark in endless mode. This can be\n"
+                     "  done with the environment variable NANOBENCH_ENDLESS. E.g. like so:\n"
+                     "\n"
+                     "    NANOBENCH_ENDLESS=MuHash ./bench_bitcoin -filter=MuHash\n"
+                     "\n"
+                     "  In rare cases it can be useful to suppress stability warnings. This can be\n"
+                     "  done with the environment variable NANOBENCH_SUPPRESS_WARNINGS, e.g:\n"
+                     "\n"
+                     "    NANOBENCH_SUPPRESS_WARNINGS=1 ./bench_bitcoin\n"
+                     "\n"
+                     "Notes:\n"
+                     "\n"
+                     "  1. pyperf\n"
+                     "     https://github.com/psf/pyperf\n"
+                     "\n"
+                     "  2. CPU pinning & isolation\n"
+                     "     https://pyperf.readthedocs.io/en/latest/system.html\n"
+                     "\n"
+                     "  3. nanobench\n"
+                     "     https://github.com/martinus/nanobench\n"
+                     "\n";
 
         return EXIT_SUCCESS;
     }