perf_event Programming Guide
The perf_event kernel API is poorly documented. The developers
themselves do not always seem inclined to update the documentation.
Since I have to muck around in the low-level interface, I've been
putting what I've learned into this document.
This is based on the files "tools/perf/design.txt" and
"include/linux/perf_event.h" in the Linux kernel tree, as well
as the perf code and libpfm4 code.
Man Pages with Documentation
I wrote the Linux manpage for perf_event_open. It was included
Linux manpage project as of version 3.47.
More documentation not yet in the manpage (my TODO as it were):
- Mention that raw events are filtered by the kernel so you can't
do things like change the interrupt setting on x86.
- Causes for the various ERROR returns:
- Extra bits in config1
- Cache generalized event parameter is out of range
- Generalized event setting in kernel is -1
- Scheduling the events failed (conflict)
- Too many events
- Invalid flags setting
- Invalid parameters in attr
- frequency setting higher than value set by sysctl
- specified CPU does not exist
- non-group leader marked as exclusive or pinned
- Requires root permissions (CAP_SYS_?) or paranoid CPU setting
- Generalized event set to 0 in kernel
- Invalid attr.type setting
- PERF_SOUREC_STACK_TRACE not supported
- attr structure bigger than expected and non-zero
- PMU interrupt not available and requested sampling
- Request branch tracing and not available
- Request low-skid events and not available
- Kernel failed while allocating memory
About this Documentation
If you find any bugs or have any comments or improvements, send
me an e-mail at vincent.weaver _at_ maine.edu
Back to Unofficial Perf-Events homepage
by Vince Weaver -- Last updated 7 March 2013