bolt/docs/Heatmaps.md

   1 # Code Heatmaps
   2
   3 BOLT has gained the ability to print code heatmaps based on
   4 sampling-based LBR profiles generated by `perf`. The output is produced
   5 in colored ASCII to be displayed in a color-capable terminal. It looks
   6 something like this:
   7
   8 ![](./Heatmap.png)
   9
  10 Heatmaps can be generated for BOLTed and non-BOLTed binaries. You can
  11 use them to compare the code layout before and after optimizations.
  12
  13 To generate a heatmap, start with running your app under `perf`:
  14
  15 ```bash
  16 $ perf record -e cycles:u -j any,u -- <executable with args>
  17 ```
  18 or if you want to monitor the existing process(es):
  19 ```bash
  20 $ perf record -e cycles:u -j any,u [-p PID|-a] -- sleep <interval>
  21 ```
  22
  23 Running with LBR (`-j any,u` or `-b`) is recommended. Heatmaps can be generated
  24 from basic events by using the llvm-bolt-heatmap option `-nl` (no LBR) but
  25 such heatmaps do not have the coverage provided by LBR and may only be useful
  26 for finding event hotspots at larger code block granularities.
  27
  28 Once the run is complete, and `perf.data` is generated, run llvm-bolt-heatmap:
  29
  30 ```bash
  31 $ llvm-bolt-heatmap -p perf.data <executable>
  32 ```
  33
  34 By default the heatmap will be dumped to *stdout*. You can change it
  35 with `-o <heatmapfile>` option. Each character/block in the heatmap
  36 shows the execution data accumulated for corresponding 64 bytes of
  37 code. You can change this granularity with a `-block-size` option.
  38 E.g. set it to 4096 to see code usage grouped by 4K pages.
  39 Other useful options are:
  40
  41 ```bash
  42 -line-size=<uint>   - number of entries per line (default 256)
  43 -max-address=<uint> - maximum address considered valid for heatmap (default 4GB)
  44 ```
  45
  46 If you prefer to look at the data in a browser (or would like to share
  47 it that way), then you can use an HTML conversion tool. E.g.:
  48
  49 ```bash
  50 $ aha -b -f <heatmapfile> > <heatmapfile>.html
  51 ```