https://github.com/paschalis-mpeis created https://github.com/llvm/llvm-project/pull/98162
Suggesting a few more details for Heatmaps.md >From f209cca87cf7c53242a353a505e3bfe34688a1b2 Mon Sep 17 00:00:00 2001 From: Paschalis Mpeis <paschalis.mp...@arm.com> Date: Tue, 9 Jul 2024 08:52:51 +0100 Subject: [PATCH] [BOLT] Added more details on heatmap docs. --- bolt/docs/Heatmaps.md | 53 +++++++++++++++++++++++++++++++------------ 1 file changed, 39 insertions(+), 14 deletions(-) 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:  @@ -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) +``` _______________________________________________ llvm-branch-commits mailing list llvm-branch-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-branch-commits
