1# Code Heatmaps 2 3BOLT has gained the ability to print code heatmaps based on 4sampling-based LBR profiles generated by `perf`. The output is produced 5in colored ASCII to be displayed in a color-capable terminal. It looks 6something like this: 7 8 9 10Heatmaps can be generated for BOLTed and non-BOLTed binaries. You can 11use them to compare the code layout before and after optimizations. 12 13To 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``` 18or 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 23Running with LBR (`-j any,u` or `-b`) is recommended. Heatmaps can be generated 24from basic events by using the llvm-bolt-heatmap option `-nl` (no LBR) but 25such heatmaps do not have the coverage provided by LBR and may only be useful 26for finding event hotspots at larger code block granularities. 27 28Once 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 34By default the heatmap will be dumped to *stdout*. You can change it 35with `-o <heatmapfile>` option. Each character/block in the heatmap 36shows the execution data accumulated for corresponding 64 bytes of 37code. You can change this granularity with a `-block-size` option. 38E.g. set it to 4096 to see code usage grouped by 4K pages. 39Other 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 46If you prefer to look at the data in a browser (or would like to share 47it that way), then you can use an HTML conversion tool. E.g.: 48 49```bash 50$ aha -b -f <heatmapfile> > <heatmapfile>.html 51``` 52
