From a02a1737affb117aab585672fcf2c207a74e27a7 Mon Sep 17 00:00:00 2001 From: Vince Weaver Date: Thu, 14 Nov 2013 17:08:52 -0500 Subject: [PATCH] perf_event_open.2: cpu/pid argument cleanup This patch attempts to clarify the pid and cpu options to perf_event_open(). It does two things: 1. Tries to make clear that the "pid" argument can mean process *or* thread. This is made confusing by how Linux uses the terms mostly interchangeably. 2. The cpu/pid documentation was confusing because of how the parameters are interdependent. Since there are only 6 possible combinations I broke out the possibilities into a table. Reported-by: Manuel Selva Signed-off-by: Vince Weaver Signed-off-by: Michael Kerrisk --- man2/perf_event_open.2 | 66 +++++++++++++++--------------------------- 1 file changed, 24 insertions(+), 42 deletions(-) diff --git a/man2/perf_event_open.2 b/man2/perf_event_open.2 index d2237e2e7..87764ba12 100644 --- a/man2/perf_event_open.2 +++ b/man2/perf_event_open.2 @@ -75,54 +75,36 @@ be accessed via .BR mmap (2) . .SS Arguments .P -The argument -.I pid -allows events to be attached to processes in various ways. -If -.I pid -is 0, measurements happen on the current thread, if -.I pid -is greater than 0, the process indicated by -.I pid -is measured, and if -.I pid -is \-1, all processes are counted. - The -.I cpu -argument allows measurements to be specific to a CPU. -If -.I cpu -is greater than or equal to 0, -measurements are restricted to the specified CPU; -if -.I cpu -is \-1, the events are measured on all CPUs. -.P -Note that the combination of -.IR pid " == \-1" +.I pid and -.IR cpu " == \-1" -is not valid. -.P -A -.IR pid " > 0" -and -.IR cpu " == \-1" -setting measures per-process and follows that process to whatever CPU the -process gets scheduled to. -Per-process events can be created by any user. -.P -A -.IR pid " == \-1" -and -.IR cpu " >= 0" -setting is per-CPU and measures all processes on the specified CPU. -Per-CPU events need the +.I cpu +arguments allow specifying which process and CPU to monitor: +.TP +.BR pid==0 " and " cpu==\-1 +This measures the current process/thread on any CPU. +.TP +.BR pid==0 " and " cpu>=0 +This measures the current process/thread only +when running on the specified CPU. +.TP +.BR pid>0 " and " cpu==\-1 +This measures the specified process/thread on any CPU. +.TP +.BR pid>0 " and " cpu>=0 +This measures the specified process/thread only +when running on the specified CPU. +.TP +.BR pid==\-1 " and " cpu>=0 +This measures all processes/threads on the specified CPU. +Measurements such as this require the .B CAP_SYS_ADMIN capability or a .I /proc/sys/kernel/perf_event_paranoid value of less than 1. +.TP +.BR pid==\-1 " and " cpu==\-1 +This setting is invalid and will return an error. .P The .I group_fd