[PATCH 2/2] 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

[Keno Fischer]

---
 man2/perf_event_open.2 | 37 +++++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)

diff --git a/man2/perf_event_open.2 b/man2/perf_event_open.2
index 65239e6..ad2c596 100644
--- a/man2/perf_event_open.2
+++ b/man2/perf_event_open.2
@@ -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 ()
-- 
2.8.1

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 2/2] perf_event_open.2: Document the interaction of perf counters and execve

[Vince Weaver]

On Tue, 27 Dec 2016, Keno Fischer wrote:

> +.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.

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.

> +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?

> +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.

> +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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html