[BOLT] Add -print-mappings option to heatmaps (#97567)

Emit a mapping in the legend between the characters/buckets and the text
sections, using:

```sh
llvm-heatmap-bolt -print-mappings ..
```

Example:
```
Legend:
..
Sections:
  a/A : .init      0x00000100-0x00000200
  b/B : .plt       0x00000200-0x00000500
  c/C : .text      0x00010000-0x000a0000
  d/D : .fini      0x000a0000-0x000f0000
..
```

bolt/docs/CommandLineArgumentReference.md

@@ -283,6 +283,12 @@
 
   List of functions to pad with amount of bytes
 
+- `--print-mappings`
+
+  Print mappings in the legend, between characters/blocks and text sections
+  (default false).
+
+
 - `--profile-format=<value>`
 
   Format to dump profile output in aggregation mode, default is fdata
@@ -1240,4 +1246,4 @@
 
 - `--print-options`
 
-  Print non-default options after command line parsing
+  Print non-default options after command line parsing

bolt/docs/Heatmaps.md

@@ -41,6 +41,7 @@ Other useful options are:
 ```bash
 -line-size=<uint>   - number of entries per line (default 256)
 -max-address=<uint> - maximum address considered valid for heatmap (default 4GB)
+-print-mappings=<bool> - print mappings in legend, between characters/blocks and text sections (default false)
 ```
 
 If you prefer to look at the data in a browser (or would like to share

bolt/include/bolt/Utils/CommandLineOpts.h

@@ -40,6 +40,7 @@ extern llvm::cl::opt<unsigned> ExecutionCountThreshold;
 extern llvm::cl::opt<unsigned> HeatmapBlock;
 extern llvm::cl::opt<unsigned long long> HeatmapMaxAddress;
 extern llvm::cl::opt<unsigned long long> HeatmapMinAddress;
+extern llvm::cl::opt<bool> HeatmapPrintMappings;
 extern llvm::cl::opt<bool> HotData;
 extern llvm::cl::opt<bool> HotFunctionsAtEnd;
 extern llvm::cl::opt<bool> HotText;

bolt/lib/Profile/Heatmap.cpp

@@ -13,6 +13,7 @@
 #include "llvm/Support/Debug.h"
 #include "llvm/Support/FileSystem.h"
 #include "llvm/Support/Format.h"
+#include "llvm/Support/FormatVariadic.h"
 #include "llvm/Support/MathExtras.h"
 #include "llvm/Support/raw_ostream.h"
 #include <algorithm>
@@ -164,6 +165,7 @@ void Heatmap::print(raw_ostream &OS) const {
 
   // Print map legend
   OS << "Legend:\n";
+  OS << "\nRanges:\n";
   uint64_t PrevValue = 0;
   for (unsigned I = 0; I < sizeof(Range) / sizeof(Range[0]); ++I) {
     const uint64_t Value = Range[I];
@@ -172,6 +174,22 @@ void Heatmap::print(raw_ostream &OS) const {
     OS << " : (" << PrevValue << ", " << Value << "]\n";
     PrevValue = Value;
   }
+  if (opts::HeatmapPrintMappings) {
+    OS << "\nSections:\n";
+    unsigned SectionIdx = 0;
+    for (auto TxtSeg : TextSections) {
+      const char Upper = static_cast<char>('A' + ((SectionIdx++) % 26));
+      const char Lower = static_cast<char>(std::tolower(Upper));
+      OS << formatv("  {0}/{1} : {2,-10} ", Lower, Upper, TxtSeg.Name);
+      if (MaxAddress > 0xffffffff)
+        OS << format("0x%016" PRIx64, TxtSeg.BeginAddress) << "-"
+           << format("0x%016" PRIx64, TxtSeg.EndAddress) << "\n";
+      else
+        OS << format("0x%08" PRIx64, TxtSeg.BeginAddress) << "-"
+           << format("0x%08" PRIx64, TxtSeg.EndAddress) << "\n";
+    }
+    OS << "\n";
+  }
 
   // Pos - character position from right in hex form.
   auto printHeader = [&](unsigned Pos) {

bolt/lib/Utils/CommandLineOpts.cpp

@@ -105,6 +105,12 @@ cl::opt<unsigned long long> HeatmapMinAddress(
     cl::desc("minimum address considered valid for heatmap (default 0)"),
     cl::Optional, cl::cat(HeatmapCategory));
 
+cl::opt<bool> HeatmapPrintMappings(
+    "print-mappings", cl::init(false),
+    cl::desc("print mappings in the legend, between characters/blocks and text "
+             "sections (default false)"),
+    cl::Optional, cl::cat(HeatmapCategory));
+
 cl::opt<bool> HotData("hot-data",
                       cl::desc("hot data symbols support (relocation mode)"),
                       cl::cat(BoltCategory));