From 3e78082c1b611ed0ccacce5c106c647ac875235f Mon Sep 17 00:00:00 2001
From: Rafael Auler <rafaelauler@fb.com>
Date: Fri, 30 Oct 2020 14:45:30 -0700
Subject: [PATCH] [DOCS] Add instrumentation instructions to README

Summary: Add basic instructions on how to instrument a binary.

(cherry picked from FBD24660183)
---
 bolt/src/Passes/Instrumentation.cpp | 49 ++++++++++++++---------------
 bolt/src/llvm-bolt.cpp              |  2 ++
 2 files changed, 26 insertions(+), 25 deletions(-)

diff --git a/bolt/src/Passes/Instrumentation.cpp b/bolt/src/Passes/Instrumentation.cpp
index e4c2e2855bd4..53f49dde052f 100644
--- a/bolt/src/Passes/Instrumentation.cpp
+++ b/bolt/src/Passes/Instrumentation.cpp
@@ -19,49 +19,48 @@
 using namespace llvm;
 
 namespace opts {
-extern cl::OptionCategory BoltCategory;
+extern cl::OptionCategory BoltInstrCategory;
 
 cl::opt<std::string> InstrumentationFilename(
     "instrumentation-file",
-    cl::desc("file name where instrumented profile will be saved"),
-    cl::init("/tmp/prof.fdata"),
-    cl::Optional,
-    cl::cat(BoltCategory));
+    cl::desc("file name where instrumented profile will be saved (default: "
+             "/tmp/prof.fdata)"),
+    cl::init("/tmp/prof.fdata"), cl::Optional, cl::cat(BoltInstrCategory));
 
 cl::opt<bool> InstrumentationFileAppendPID(
     "instrumentation-file-append-pid",
     cl::desc("append PID to saved profile file name (default: false)"),
     cl::init(false),
     cl::Optional,
-    cl::cat(BoltCategory));
+    cl::cat(BoltInstrCategory));
 
 cl::opt<bool> ConservativeInstrumentation(
     "conservative-instrumentation",
     cl::desc(
         "don't trust our CFG and disable spanning trees and any counter "
         "inference, put a counter everywhere (for debugging, default: false)"),
-    cl::init(false), cl::Optional, cl::cat(BoltCategory));
+    cl::init(false), cl::Optional, cl::cat(BoltInstrCategory));
 
-cl::opt<uint32_t>
-    InstrumentationSleepTime("instrumentation-sleep-time",
-                             cl::desc("interval between profile writes, "
-                                      "default: 0 = write only at program end"),
-                             cl::init(0), cl::Optional,
-                             cl::cat(BoltCategory));
+cl::opt<uint32_t> InstrumentationSleepTime(
+    "instrumentation-sleep-time",
+    cl::desc("interval between profile writes (default: 0 = write only at "
+             "program end).  This is useful for service workloads when you "
+             "want to dump profile every X minutes or if you are killing the "
+             "program and the profile is not being dumped at the end."),
+    cl::init(0), cl::Optional, cl::cat(BoltInstrCategory));
 
-cl::opt<bool> InstrumentHotOnly(
-    "instrument-hot-only",
-    cl::desc("only insert instrumentation on hot functions (need profile)"),
-    cl::init(false),
-    cl::Optional,
-    cl::cat(BoltCategory));
+cl::opt<bool>
+    InstrumentHotOnly("instrument-hot-only",
+                      cl::desc("only insert instrumentation on hot functions "
+                               "(needs profile, default: false)"),
+                      cl::init(false), cl::Optional,
+                      cl::cat(BoltInstrCategory));
 
-cl::opt<bool> InstrumentCalls(
-    "instrument-calls",
-    cl::desc("record profile for inter-function control flow activity"),
-    cl::init(true),
-    cl::Optional,
-    cl::cat(BoltCategory));
+cl::opt<bool> InstrumentCalls("instrument-calls",
+                              cl::desc("record profile for inter-function "
+                                       "control flow activity (default: true)"),
+                              cl::init(true), cl::Optional,
+                              cl::cat(BoltInstrCategory));
 }
 
 namespace llvm {
diff --git a/bolt/src/llvm-bolt.cpp b/bolt/src/llvm-bolt.cpp
index da59f8f67e89..0ea26b1fd592 100644
--- a/bolt/src/llvm-bolt.cpp
+++ b/bolt/src/llvm-bolt.cpp
@@ -45,10 +45,12 @@ cl::OptionCategory BoltOptCategory("BOLT optimization options");
 cl::OptionCategory BoltRelocCategory("BOLT options in relocation mode");
 cl::OptionCategory BoltOutputCategory("Output options");
 cl::OptionCategory AggregatorCategory("Data aggregation options");
+cl::OptionCategory BoltInstrCategory("BOLT instrumentation options");
 
 static cl::OptionCategory *BoltCategories[] = {&BoltCategory,
                                                &BoltOptCategory,
                                                &BoltRelocCategory,
+                                               &BoltInstrCategory,
                                                &BoltOutputCategory};
 
 static cl::OptionCategory *BoltDiffCategories[] = {&BoltDiffCategory};