perf_event_open.2: Document the interaction of perf counters and execve
PATCH 2/2 perf_event_open.2: Document the interaction of perf counters and execve
--- man2/perf_event_open.2 | 37 +++++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+)
man2/perf_event_open.2 +37 -0
@@ -1338,6 +1338,43 @@ includes .BR PERF_SAMPLE_CALLCHAIN , this field specifies how many stack frames to report when generating the callchain. +.SS Interaction with execve(2) +It is important to separate the consideration of a file descriptor obtained +from +.BR perf_event_open +and that of the underlying performance counters. The two may be, but often +aren't, associated with the same task. With the exception of the +.BR PERF_FLAG_FD_CLOEXEC +flag (see above) there is nothing special about the file descriptors, so this +section will discuss the underlying performance counters. + +When +.BR perf_event_open +is called, in addition to the file descriptor, the underlying performance counters +are created and associated with each thread in the specified process's thread group. +This association ends whenever the task exits, but generally persists across +.BR execve(2) +(unless of course, the execve causes the last file descriptor referencing these counters +to close). However, for security reasons, the association is broken if the +.BR execve(2) +causes the task's "dumpable", flag to be reset (see +.BR prctl(2) +). + +If the +.IR inherit +option is specified, new children of any task already associated with these performance counters, +will inherit this association. + +Once all associations are broken, no further events are counted. However, the file descriptor +will not indicate this condition through an error return +(i.e. +.BR read(2) +and +.BR mmap(2) +will still succeed +). + .SS Reading results Once a .BR perf_event_open ()
Signature · 6 lines
2.8.1 -- To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html
A message that is not in the archive (sent off-list or not yet received): 20161227215241.GA1214-9DCaDmOhoh+8M3too/[email protected]
man2/perf_event_open.2 includes · line 1349
Quoted 9 lines · Keno Fischer
+.SS Interaction with execve(2)
man2/perf_event_open.2 +8
-0+It is important to separate the consideration of a file descriptor obtained +from +.BR perf_event_open +and that of the underlying performance counters. The two may be, but often +aren't, associated with the same task. With the exception of the +.BR PERF_FLAG_FD_CLOEXEC +flag (see above) there is nothing special about the file descriptors, so this +section will discuss the underlying performance counters.
The termonology gets to be a bit complicated here.
Often (at least in academic works) there is the distinction:
+ performance counter = the underlying hardware counter (at the silicon level)
+ performance event = the particular architectural event being measured on a performance counter
I'm not sure what the most clear terminology is for a perf_event_open derived file descriptor which encapsulates a series of process-specific counter/event mappings.
man2/perf_event_open.2 includes · line 1362
Quoted 12 lines
man2/perf_event_open.2 +12
-0+When +.BR perf_event_open +is called, in addition to the file descriptor, the underlying performance counters +are created and associated with each thread in the specified process's thread group. +This association ends whenever the task exits, but generally persists across +.BR execve(2) +(unless of course, the execve causes the last file descriptor referencing these counters +to close). However, for security reasons, the association is broken if the +.BR execve(2) +causes the task's "dumpable", flag to be reset (see +.BR prctl(2) +).
I guess this part is the inspiration for adding this section?
man2/perf_event_open.2 includes · line 1367
Quoted 4 lines
man2/perf_event_open.2 +4
-0+If the +.IR inherit +option is specified, new children of any task already associated with these performance counters, +will inherit this association.
This is a complex area that could use more discussion.
man2/perf_event_open.2 includes · line 1375
Quoted 7 lines
man2/perf_event_open.2 +7
-0+Once all associations are broken, no further events are counted. However, the file descriptor +will not indicate this condition through an error return +(i.e. +.BR read(2) +and +.BR mmap(2) +will still succeed
It gets even messier with respect to signal handling and such too.
So anyway as a summary, this is probably a needed section to add to the manpage but it will be a challenge to document is properly. I've spent a lot of time writing tests in this area and I'm not 100% sure I could entirely explain the interactions of fork/exec/inherit/inherit_stat especially when arbitrary children start messing with the file descriptor.
Vince
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html