[BOLT][docs] Expand Heatmaps.md

[paschalis-mpeis]

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

[llvmbot]

@llvm/pr-subscribers-bolt

Author: Paschalis Mpeis (paschalis-mpeis)

Changes

Suggesting a few more details for Heatmaps.md

---

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

1 Files Affected:

• (modified) bolt/docs/Heatmaps.md (+39-14)

diff --git a/bolt/docs/Heatmaps.md b/bolt/docs/Heatmaps.md
index e1b59d49ad102..c1a01839d6682 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,7 @@ $ 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:
-
-```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)
-```
+with `-o <heatmapfile>` option.
 
 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 +40,38 @@ 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 TextSegments, 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.
+
+Each consecutive line in the heatmap advances by the same amount,
+with the binary size covered by a line being dependent on the block size and the
+line size.
+An empty new line is inserted for bigger gaps between samples.
+
+
+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)
+```

[aaupov]

Awesome, thanks for updating the documentation

[aaupov]

Please retitle as imperative statement and drop trailing dot, e.g. [BOLT][docs] Expand Heatmaps.md

[paschalis-mpeis]

Thanks for your review @aaupov .
This is a stacked pull request as the updated docs refer to the -print-mappings option.
So it will be merged after:

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