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 23Note that at the moment running with LBR (`-j any,u` or `-b`) is 24a requirement. 25 26Once the run is complete, and `perf.data` is generated, run BOLT in 27a heatmap mode: 28 29```bash 30$ llvm-bolt heatmap -p perf.data <executable> 31``` 32 33By default the heatmap will be dumped to *stdout*. You can change it 34with `-o <heatmapfile>` option. Each character/block in the heatmap 35shows the execution data accumulated for corresponding 64 bytes of 36code. You can change this granularity with a `-block-size` option. 37E.g. set it to 4096 to see code usage grouped by 4K pages. 38Other useful options are: 39 40```bash 41-line-size=<uint> - number of entries per line (default 256) 42-max-address=<uint> - maximum address considered valid for heatmap (default 4GB) 43``` 44 45If you prefer to look at the data in a browser (or would like to share 46it that way), then you can use an HTML conversion tool. E.g.: 47 48```bash 49$ aha -b -f <heatmapfile> > <heatmapfile>.html 50``` 51
