[NFC][BOLT] Refactor ForcePatch option (#127812)

Move force-patch flag to CommandLineOpts and add details on
PatchEntries.

bolt/include/bolt/Utils/CommandLineOpts.h

@@ -37,6 +37,7 @@ extern llvm::cl::opt<unsigned> BucketsPerLine;
 extern llvm::cl::opt<bool> DiffOnly;
 extern llvm::cl::opt<bool> EnableBAT;
 extern llvm::cl::opt<bool> EqualizeBBCounts;
+extern llvm::cl::opt<bool> ForcePatch;
 extern llvm::cl::opt<bool> RemoveSymtab;
 extern llvm::cl::opt<unsigned> ExecutionCountThreshold;
 extern llvm::cl::opt<unsigned> HeatmapBlock;

bolt/lib/Passes/PatchEntries.cpp

@@ -6,27 +6,28 @@
 //
 //===----------------------------------------------------------------------===//
 //
-// This file implements the PatchEntries class that is used for patching
-// the original function entry points.
+// This file implements the PatchEntries class that is used for patching the
+// original function entry points. This ensures that only the new/optimized code
+// executes and that the old code is never used. This is necessary due to
+// current BOLT limitations of not being able to duplicate all function's
+// associated metadata (e.g., .eh_frame, exception ranges, debug info,
+// jump-tables).
+//
+// NOTE: A successful run of 'scanExternalRefs' can relax this requirement as
+// it also ensures that old code is never executed.
 //
 //===----------------------------------------------------------------------===//
 
 #include "bolt/Passes/PatchEntries.h"
+#include "bolt/Utils/CommandLineOpts.h"
 #include "bolt/Utils/NameResolver.h"
 #include "llvm/ADT/STLExtras.h"
 #include "llvm/Support/CommandLine.h"
 
 namespace opts {
-
 extern llvm::cl::OptionCategory BoltCategory;
-
 extern llvm::cl::opt<unsigned> Verbosity;
-
-llvm::cl::opt<bool>
-    ForcePatch("force-patch",
-               llvm::cl::desc("force patching of original entry points"),
-               llvm::cl::Hidden, llvm::cl::cat(BoltCategory));
-}
+} // namespace opts
 
 namespace llvm {
 namespace bolt {

bolt/lib/Rewrite/MachORewriteInstance.cpp

@@ -20,6 +20,7 @@
 #include "bolt/Rewrite/JITLinkLinker.h"
 #include "bolt/Rewrite/RewriteInstance.h"
 #include "bolt/RuntimeLibs/InstrumentationRuntimeLibrary.h"
+#include "bolt/Utils/CommandLineOpts.h"
 #include "bolt/Utils/Utils.h"
 #include "llvm/MC/MCObjectStreamer.h"
 #include "llvm/Support/Errc.h"
@@ -32,9 +33,8 @@ namespace opts {
 
 using namespace llvm;
 extern cl::opt<unsigned> AlignText;
-//FIXME! Upstream change
-//extern cl::opt<bool> CheckOverlappingElements;
-extern cl::opt<bool> ForcePatch;
+// FIXME! Upstream change
+// extern cl::opt<bool> CheckOverlappingElements;
 extern cl::opt<bool> Instrument;
 extern cl::opt<bool> InstrumentCalls;
 extern cl::opt<bolt::JumpTableSupportLevel> JumpTables;

bolt/lib/Utils/CommandLineOpts.cpp

@@ -80,6 +80,12 @@ cl::opt<bool> EqualizeBBCounts(
              "in non-LBR and shrink wrapping)"),
     cl::ZeroOrMore, cl::init(false), cl::Hidden, cl::cat(BoltOptCategory));
 
+llvm::cl::opt<bool> ForcePatch(
+    "force-patch",
+    llvm::cl::desc("force patching of original entry points to ensure "
+                   "execution follows only the new/optimized code."),
+    llvm::cl::Hidden, llvm::cl::cat(BoltCategory));
+
 cl::opt<bool> RemoveSymtab("remove-symtab", cl::desc("Remove .symtab section"),
                            cl::cat(BoltCategory));