[BOLT][docs] Expand Heatmaps.md (#98162)

Improve documentation on heatmaps.
Add example for X axis labels.

2 files changed, 56 insertions, 13 deletions

diff --git a/bolt/docs/HeatmapHeader.png b/bolt/docs/HeatmapHeader.png
new file mode 100644
index 0000000..a519dc6
--- /dev/null
+++ b/bolt/docs/HeatmapHeader.png
diff --git a/bolt/docs/Heatmaps.md b/bolt/docs/Heatmaps.md
index e1b59d4..bf68232 100644
--- a/bolt/docs/Heatmaps.md
+++ b/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,17 +32,8 @@ $ 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)
--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
 it that way), then you can use an HTML conversion tool. E.g.:
@@ -50,3 +41,55 @@ 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)
+```