[BOLT] Add -print-mappings option to heatmaps

[paschalis-mpeis]

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

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
..

[llvmbot]

@llvm/pr-subscribers-bolt

Author: Paschalis Mpeis (paschalis-mpeis)

Changes

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

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
..

---

Full diff: https://github.com/llvm/llvm-project/pull/97567.diff

5 Files Affected:

• (modified) bolt/docs/CommandLineArgumentReference.md (+7-1)
• (modified) bolt/docs/Heatmaps.md (+1)
• (modified) bolt/include/bolt/Utils/CommandLineOpts.h (+1)
• (modified) bolt/lib/Profile/Heatmap.cpp (+18)
• (modified) bolt/lib/Utils/CommandLineOpts.cpp (+6)

diff --git a/bolt/docs/CommandLineArgumentReference.md b/bolt/docs/CommandLineArgumentReference.md
index 00d472c578916..9441a627a7bda 100644
--- a/bolt/docs/CommandLineArgumentReference.md
+++ b/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
@@ -1236,4 +1242,4 @@
 
 - `--print-options`
 
-  Print non-default options after command line parsing
\ No newline at end of file
+  Print non-default options after command line parsing
diff --git a/bolt/docs/Heatmaps.md b/bolt/docs/Heatmaps.md
index 4bae8ed5410df..e1b59d49ad102 100644
--- a/bolt/docs/Heatmaps.md
+++ b/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
diff --git a/bolt/include/bolt/Utils/CommandLineOpts.h b/bolt/include/bolt/Utils/CommandLineOpts.h
index 30e8bd777b3ca..baabeab577fb5 100644
--- a/bolt/include/bolt/Utils/CommandLineOpts.h
+++ b/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;
diff --git a/bolt/lib/Profile/Heatmap.cpp b/bolt/lib/Profile/Heatmap.cpp
index 210a5cc98c104..d2ac1e62146d8 100644
--- a/bolt/lib/Profile/Heatmap.cpp
+++ b/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 << "\nRegions:\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) {
diff --git a/bolt/lib/Utils/CommandLineOpts.cpp b/bolt/lib/Utils/CommandLineOpts.cpp
index b9bc79f408a6b..47375abb2ad3b 100644
--- a/bolt/lib/Utils/CommandLineOpts.cpp
+++ b/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));