This patch updates the perf_event_open() documentation to include
new interfaces added in the 3.10 kernel.
It also documents a few [To be documented] instances left over
from the 3.7 kernel.
Signed-off-by: Vince Weaver <vincent.weaver@xxxxxxxxx>
--- man2/perf_event_open.2.orig 2013-07-01 12:31:46.602701124 -0400
+++ man2/perf_event_open.2 2013-07-01 13:53:03.410449052 -0400
@@ -139,7 +139,7 @@
.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
@@ -658,10 +658,23 @@
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"
@@ -977,13 +990,15 @@
.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 ()
@@ -1428,6 +1443,8 @@
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
@@ -1535,20 +1552,135 @@
.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
@@ -1585,6 +1717,10 @@
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
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
