LDP
/
man-pages
mirror of https://github.com/mkerrisk/man-pages
0
1
Fork 0
Code Releases Activity

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 <selva.manuel@gmail.com>
Signed-off-by: Vince Weaver <vincent.weaver@maine.edu>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
Vince Weaver 2013-11-14 17:08:52 -05:00 committed by Michael Kerrisk
parent 9d5acc264b
commit a02a1737af
1 changed files with 24 additions and 42 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

66
man2/perf_event_open.2
View File

@ -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