1*dbb99499SAndroid Build Coastguard Worker<a name="perf-counters" /> 2*dbb99499SAndroid Build Coastguard Worker 3*dbb99499SAndroid Build Coastguard Worker# User-Requested Performance Counters 4*dbb99499SAndroid Build Coastguard Worker 5*dbb99499SAndroid Build Coastguard WorkerWhen running benchmarks, the user may choose to request collection of 6*dbb99499SAndroid Build Coastguard Workerperformance counters. This may be useful in investigation scenarios - narrowing 7*dbb99499SAndroid Build Coastguard Workerdown the cause of a regression; or verifying that the underlying cause of a 8*dbb99499SAndroid Build Coastguard Workerperformance improvement matches expectations. 9*dbb99499SAndroid Build Coastguard Worker 10*dbb99499SAndroid Build Coastguard WorkerThis feature is available if: 11*dbb99499SAndroid Build Coastguard Worker 12*dbb99499SAndroid Build Coastguard Worker* The benchmark is run on an architecture featuring a Performance Monitoring 13*dbb99499SAndroid Build Coastguard Worker Unit (PMU), 14*dbb99499SAndroid Build Coastguard Worker* The benchmark is compiled with support for collecting counters. Currently, 15*dbb99499SAndroid Build Coastguard Worker this requires [libpfm](http://perfmon2.sourceforge.net/), which is built as a 16*dbb99499SAndroid Build Coastguard Worker dependency via Bazel. 17*dbb99499SAndroid Build Coastguard Worker 18*dbb99499SAndroid Build Coastguard WorkerThe feature does not require modifying benchmark code. Counter collection is 19*dbb99499SAndroid Build Coastguard Workerhandled at the boundaries where timer collection is also handled. 20*dbb99499SAndroid Build Coastguard Worker 21*dbb99499SAndroid Build Coastguard WorkerTo opt-in: 22*dbb99499SAndroid Build Coastguard Worker* If using a Bazel build, add `--define pfm=1` to your build flags 23*dbb99499SAndroid Build Coastguard Worker* If using CMake: 24*dbb99499SAndroid Build Coastguard Worker * Install `libpfm4-dev`, e.g. `apt-get install libpfm4-dev`. 25*dbb99499SAndroid Build Coastguard Worker * Enable the CMake flag `BENCHMARK_ENABLE_LIBPFM` in `CMakeLists.txt`. 26*dbb99499SAndroid Build Coastguard Worker 27*dbb99499SAndroid Build Coastguard WorkerTo use, pass a comma-separated list of counter names through the 28*dbb99499SAndroid Build Coastguard Worker`--benchmark_perf_counters` flag. The names are decoded through libpfm - meaning, 29*dbb99499SAndroid Build Coastguard Workerthey are platform specific, but some (e.g. `CYCLES` or `INSTRUCTIONS`) are 30*dbb99499SAndroid Build Coastguard Workermapped by libpfm to platform-specifics - see libpfm 31*dbb99499SAndroid Build Coastguard Worker[documentation](http://perfmon2.sourceforge.net/docs.html) for more details. 32*dbb99499SAndroid Build Coastguard Worker 33*dbb99499SAndroid Build Coastguard WorkerThe counter values are reported back through the [User Counters](../README.md#custom-counters) 34*dbb99499SAndroid Build Coastguard Workermechanism, meaning, they are available in all the formats (e.g. JSON) supported 35*dbb99499SAndroid Build Coastguard Workerby User Counters. 36