fix typo

Created using spr 1.3.5-bogner

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

@@ -1,9 +1,9 @@
 # Code Heatmaps
 
 BOLT has gained the ability to print code heatmaps based on
-sampling-based LBR profiles generated by `perf`. The output is produced
-in colored ASCII to be displayed in a color-capable terminal. It looks
-something like this:
+sampling-based profiles generated by `perf`, either with `LBR` data or not.
+The output is produced in colored ASCII to be displayed in a color-capable
+terminal. It looks something like this:
 
 ![](./Heatmap.png)
 
@@ -32,20 +32,64 @@ $ llvm-bolt-heatmap -p perf.data <executable>
 ```
 
 By default the heatmap will be dumped to *stdout*. You can change it
-with `-o <heatmapfile>` option. Each character/block in the heatmap
-shows the execution data accumulated for corresponding 64 bytes of
-code. You can change this granularity with a `-block-size` option.
-E.g. set it to 4096 to see code usage grouped by 4K pages.
-Other useful options are:
+with `-o <heatmapfile>` option.
 
-```bash
--line-size=<uint>   - number of entries per line (default 256)
--max-address=<uint> - maximum address considered valid for heatmap (default 4GB)
-```
 
 If you prefer to look at the data in a browser (or would like to share
 it that way), then you can use an HTML conversion tool. E.g.:
 
 ```bash
 $ aha -b -f <heatmapfile> > <heatmapfile>.html
 ```
+
+---
+
+## Background on heatmaps:
+A heatmap is effectively a histogram that is rendered into a grid for better
+visualization.
+In theory we can generate a heatmap using any binary and a perf profile.
+
+Each block/character in the heatmap shows the execution data accumulated for
+corresponding 64 bytes of code. You can change this granularity with a
+`-block-size` option.
+E.g. set it to 4096 to see code usage grouped by 4K pages.
+
+
+When a block is shown as a dot, it means that no samples were found for that
+address.
+When it is shown as a letter, it indicates a captured sample on a particular
+text section of the binary.
+To show a mapping between letters and text sections in the legend, use
+`-print-mappings`.
+When a sampled address does not belong to any of the text sections, the
+characters 'o' or 'O' will be shown.
+
+The legend shows by default the ranges in the heatmap according to the number
+of samples per block.
+A color is assigned per range, except the first two ranges that distinguished by
+lower and upper case letters.
+
+On the Y axis, each row/line starts with an actual address of the binary.
+Consecutive lines in the heatmap advance by the same amount, with the binary
+size covered by a line dependent on the block size and the line size.
+An empty new line is inserted for larger gaps between samples.
+
+On the X axis, the horizontally emitted hex numbers can help *estimate* where
+in the line the samples lie, but they cannot be combined to provide a full
+address, as they are relative to both the bucket and line sizes.
+
+In the example below, the highlighted `0x100` column is not an offset to each
+row's address, but instead, it points to the middle of the line.
+For the generation, the default bucket size was used with a line size of 128.
+
+
+![](./HeatmapHeader.png)
+
+
+Some useful options are:
+
+```
+-line-size=<uint>   - number of entries per line (default 256)
+-max-address=<uint> - maximum address considered valid for heatmap (default 4GB)
+-print-mappings     - print mappings in the legend, between characters/blocks and text sections (default false)
+```

bolt/include/bolt/Core/MCPlusBuilder.h

@@ -2041,9 +2041,14 @@ class MCPlusBuilder {
     return InstructionListType();
   }
 
-  virtual InstructionListType createDummyReturnFunction(MCContext *Ctx) const {
-    llvm_unreachable("not implemented");
-    return InstructionListType();
+  /// Returns a function body that contains only a return instruction. An
+  /// example usage is a workaround for the '__bolt_fini_trampoline' of
+  // Instrumentation.
+  virtual InstructionListType
+  createReturnInstructionList(MCContext *Ctx) const {
+    InstructionListType Insts(1);
+    createReturn(Insts[0]);
+    return Insts;
   }
 
   /// This method takes an indirect call instruction and splits it up into an

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/Passes/Instrumentation.cpp

@@ -754,7 +754,7 @@ void Instrumentation::createAuxiliaryFunctions(BinaryContext &BC) {
       // with unknown symbol in runtime library. E.g. for static PIE
       // executable
       createSimpleFunction("__bolt_fini_trampoline",
-                           BC.MIB->createDummyReturnFunction(BC.Ctx.get()));
+                           BC.MIB->createReturnInstructionList(BC.Ctx.get()));
     }
   }
 }

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/Target/X86/X86MCPlusBuilder.cpp

@@ -3241,12 +3241,6 @@ class X86MCPlusBuilder : public MCPlusBuilder {
     return Insts;
   }
 
-  InstructionListType createDummyReturnFunction(MCContext *Ctx) const override {
-    InstructionListType Insts(1);
-    createReturn(Insts[0]);
-    return Insts;
-  }
-
   BlocksVectorTy indirectCallPromotion(
       const MCInst &CallInst,
       const std::vector<std::pair<MCSymbol *, uint64_t>> &Targets,

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));

bolt/test/AArch64/dummy-return.s

@@ -0,0 +1,28 @@
+# REQUIRES: system-linux,target=aarch64{{.*}}
+
+# RUN: llvm-mc -filetype=obj -triple aarch64-unknown-unknown %s -o %t.o
+# RUN: %clang %cflags %t.o -o %t.exe -Wl,-q -static
+# RUN: llvm-bolt -instrument -instrumentation-sleep-time=1 %t.exe \
+# RUN:  -o %t.instr 2>&1 | FileCheck %s
+# RUN: llvm-objdump --disassemble-symbols=__bolt_fini_trampoline %t.instr -D \
+# RUN:  | FileCheck %s -check-prefix=CHECK-ASM
+
+# CHECK: BOLT-INFO: output linked against instrumentation runtime library
+# CHECK-ASM: <__bolt_fini_trampoline>:
+# CHECK-ASM-NEXT: ret
+
+  .text
+  .align 4
+  .global _start
+  .type _start, %function
+_start:
+   bl foo
+   ret
+  .size _start, .-_start
+
+  .global foo
+  .type foo, %function
+foo:
+  mov	w0, wzr
+  ret
+  .size foo, .-foo