.\" This document is based on the perf_event.h header file, the
.\" tools/perf/design.txt file, and a lot of bitter experience.
.\"
-.TH PERF_EVENT_OPEN 2 2013-02-04 "Linux" "Linux Programmer's Manual"
+.TH PERF_EVENT_OPEN 2 2013-07-02 "Linux" "Linux Programmer's Manual"
.SH NAME
perf_event_open \- set up performance monitoring
.SH SYNOPSIS
.IR group_fd " = \-1"
and is considered to be a group with only 1 member.)
An event group is scheduled onto the CPU as a unit: it will
-be put onto the CPU ionly if all of the events in the group can be put onto
+be put onto the CPU only if all of the events in the group can be put onto
the CPU.
This means that the values of the member events can be
meaningfully compared, added, divided (to get ratios), etc., with each
.P
The
.I flags
-argument takes one of the following values:
+argument is formed by ORing together zero or more of the following values:
.TP
.BR PERF_FLAG_FD_NO_GROUP
.\" FIXME The following sentence is unclear
See branch_sample_type.
.TP
.BR PERF_SAMPLE_REGS_USER " (Since Linux 3.7)"
-Records the current register state.
+Records the current user-level CPU register state
+(the values in the process before the kernel was called).
.TP
.BR PERF_SAMPLE_STACK_USER " (Since Linux 3.7)"
-[To be documented]
+Records the user level stack, allowing stack unwinding.
+.TP
+.BR PERF_SAMPLE_WEIGHT " (Since Linux 3.10)"
+Records a hardware provided weight value that expresses how
+costly the sampled event was.
+This allows the hardware to highlight expensive events in
+a profile.
+.TP
+.BR PERF_SAMPLE_DATA_SRC " (Since Linux 3.10)"
+Records the data source: where in the memory hierarchy
+the data associated with the sampled instruction came from.
+This is only available if the underlying hardware
+supports this feature.
.RE
.TP
.IR "read_format"
Which one is used is selected by the
.I watermark
bitflag.
+
+.I wakeup_events
+only counts
+.B PERF_RECORD_SAMPLE
+record types.
+To receive a signal for every incoming
+.B PERF_RECORD
+type set
+.I wakeup_watermark
+to 1.
.TP
.IR "bp_type" " (Since Linux 2.6.33)"
This chooses the breakpoint type.
.RE
.TP
.IR "sample_regs_user" " (Since Linux 3.7)"
-This defines the set of user registers to dump on samples.
-See
-.\" FIXME: The following reference seems to be not quite right:
-.IR asm/perf_regs.h .
+This bitmask defines the set of user CPU registers to dump on samples.
+The layout of the register mask is architecture specific and
+described in the kernel header
+.IR arch/ARCH/include/uapi/asm/perf_regs.h .
.TP
.IR "sample_stack_user" " (Since Linux 3.7)"
-This defines the size of the user stack to dump on samples.
+This defines the size of the user stack to dump if
+.B PERF_SAMPLE_STACK_USER
+is specified.
.SS Reading results
Once a
.BR perf_event_open ()
u64 size; /* if PERF_SAMPLE_STACK_USER */
char data[size]; /* if PERF_SAMPLE_STACK_USER */
u64 dyn_size; /* if PERF_SAMPLE_STACK_USER */
+ u64 weight; /* if PERF_SAMPLE_WEIGHT */
+ u64 data_src; /* if PERF_SAMPLE_DATA_SRC */
};
.fi
.RS
.IR abi ", " regs[weight(mask)]
If
.B PERF_SAMPLE_REGS_USER
-is enabled, then
-[to be documented].
+is enabled, then the user CPU registers are recorded.
The
.I abi
field is one of
.BR PERF_SAMPLE_REGS_ABI_NONE ", " PERF_SAMPLE_REGS_ABI_32 " or "
.BR PERF_SAMPLE_REGS_ABI_64 .
+
+The
+.I regs
+field is an array of the CPU registers that were specified by
+the
+.I sample_regs_user
+attr field.
+The number of values is the number of bits set in the
+.I sample_regs_user
+bitmask.
.TP
.IR size ", " data[size] ", " dyn_size
If
.B PERF_SAMPLE_STACK_USER
-is enabled, then
-[to be documented].
+is enabled, then record the user stack to enable backtracing.
+.I size
+is the size requested by the user in
+.I stack_user_size
+or else the maximum record size.
+.I data
+is the stack data.
+.I dyn_size
+is the amount of data actually dumped (can be less than
+.I size
+).
+.TP
+.I weight
+If
+.B PERF_SAMPLE_WEIGHT
+is enabled, then a 64 bit value provided by the hardwre
+is recorded that indicates how costly the event was.
+This allows expensive events to stand out more clearly
+in profiles.
+.TP
+.I data_src
+If
+.B PERF_SAMPLE_DATA_SRC
+is enabled, then a 64 bit value is recorded that is made up of
+the following fields:
+.RS
+.TP
+.I mem_op
+type of opcode, a bitwise combination of
+.B PERF_MEM_OP_NA
+(not available),
+.B PERF_MEM_OP_LOAD
+(load instruction),
+.B PERF_MEM_OP_STORE
+(store instruction),
+.B PERF_MEM_OP_PFETCH
+(prefetch), and
+.B PERF_MEM_OP_EXEC
+(executable code).
+.TP
+.I mem_lvl
+memory hierarchy level hit or miss, a bitwise combination of
+.B PERF_MEM_LVL_NA
+(not available),
+.B PERF_MEM_LVL_HIT
+(hit),
+.B PERF_MEM_LVL_MISS
+(miss),
+.B PERF_MEM_LVL_L1
+(level 1 cache),
+.B PERF_MEM_LVL_LFB
+(line fill buffer),
+.B PERF_MEM_LVL_L2
+(level 2 cache),
+.B PERF_MEM_LVL_L3
+(level 3 cache),
+.B PERF_MEM_LVL_LOC_RAM
+(local DRAM),
+.B PERF_MEM_LVL_REM_RAM1
+(remote DRAM 1 hop),
+.B PERF_MEM_LVL_REM_RAM2
+(remote DRAM 2 hops),
+.B PERF_MEM_LVL_REM_CCE1
+(remote cache 1 hop),
+.B PERF_MEM_LVL_REM_CCE2
+(remote Cache 2 hops),
+.B PERF_MEM_LVL_IO
+(I/O memory), and
+.B PERF_MEM_LVL_UNC
+(uncached memory).
+.TP
+.I mem_snoop
+snoop mode, a bitwise combination of
+.B PERF_MEM_SNOOP_NA
+(not available),
+.B PERF_MEM_SNOOP_NONE
+(no snoop),
+.B PERF_MEM_SNOOP_HIT
+(snoop hit),
+.B PERF_MEM_SNOOP_MISS
+(snoop miss), and
+.B PERF_MEM_SNOOP_HITM
+(snoop hit modified).
+.TP
+.I mem_lock
+lock instruction, a bitwise combination of
+.B PERF_MEM_LOCK_NA
+(not available) and
+.B PERF_MEM_LOCK_LOCKED
+(locked transaction).
+.TP
+.I mem_dtlb
+tlb access hit or miss, a bitwise combination of
+.B PERF_MEM_TLB_NA
+(not available),
+.B PERF_MEM_TLB_HIT
+(hit),
+.B PERF_MEM_TLB_MISS
+(miss),
+.B PERF_MEM_TLB_L1
+(level 1 TLB),
+.B PERF_MEM_TLB_L2
+(level 2 TLB),
+.B PERF_MEM_TLB_WK
+(hardware walker), and
+.B PERF_MEM_TLB_OS
+(OS fault handler).
+.RE
.RE
.RE
.TP
In addition, one of the following bits can be set:
.RS
.TP
+.B PERF_RECORD_MISC_MMAP_DATA
+This is set when the mapping is not executable;
+otherwise the mapping is executable.
+.TP
.B PERF_RECORD_MISC_EXACT_IP
This indicates that the content of
.B PERF_SAMPLE_IP
Enables the individual event or event group specified by the
file descriptor argument.
-The ioctl argument is ignored.
+If the
+.B PERF_IOC_FLAG_GROUP
+bit is set in the ioctl argument, then all events in a group are
+enabled, even if the event specified is not the group leader.
.TP
.B PERF_EVENT_IOC_DISABLE
Disables the individual counter or event group specified by the
affects only that counter; disabling a non-leader
stops that counter from counting but doesn't affect any other counter.
-The ioctl argument is ignored.
+If the
+.B PERF_IOC_FLAG_GROUP
+bit is set in the ioctl argument, then all events in a group are
+disabled, even if the event specified is not the group leader.
.TP
.B PERF_EVENT_IOC_REFRESH
Non-inherited overflow counters can use this
or
.I time_running
values.
-When sent to a group leader, only
-the leader is reset (child events are not).
-The ioctl argument is ignored.
+If the
+.B PERF_IOC_FLAG_GROUP
+bit is set in the ioctl argument, then all events in a group are
+reset, even if the event specified is not the group leader.
+
+If the
+.B PERF_IOC_FLAG_GROUP
+bit is not set, then the behavior is somwhat unexpected:
+when sent to a group leader only the leader is reset
+(children are left alone);
+when sent to a child all events in a group are reset.
.TP
.B PERF_EVENT_IOC_PERIOD
IOC_PERIOD is the command to update the period; it
OSDN Git Service
