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