From 7480dabbeb90198dbb90924735b48328f3998cef Mon Sep 17 00:00:00 2001 From: Vince Weaver Date: Wed, 6 Nov 2013 13:30:41 -0500 Subject: [PATCH] perf_event_open.2: Linux 3.12 adds PERF_SAMPLE_IDENTIFIER A new PERF_SAMPLE_IDENTIFIER sample type was added in Linux 3.12. Signed-off-by: Vince Weaver Signed-off-by: Michael Kerrisk --- man2/perf_event_open.2 | 62 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 61 insertions(+), 1 deletion(-) diff --git a/man2/perf_event_open.2 b/man2/perf_event_open.2 index 14f5d3c83..578dae0f0 100644 --- a/man2/perf_event_open.2 +++ b/man2/perf_event_open.2 @@ -687,6 +687,27 @@ 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. +.TP +.BR PERF_SAMPLE_IDENTIFIER " (Since Linux 3.12)" +Places the SAMPLE_ID value in a fixed position in the record, +either at the beginning (for sample events) or at the end +(if a non-sample event). + +This was necessary because a sample stream may have +records from various different event sources with different +.I sample_type +settings. +Parsing the event stream properly was not possible because the +format of the record was needed to find SAMPLE_ID, but +the the format could not be found without knowing what +event the sample belonged to (causing a circular +dependency). + +This new +.B PERF_SAMPLE_IDENTIFIER +setting makes the event stream always parsable +by putting SAMPLE_ID in a fixed location, even though +it means having duplicate SAMPLE_ID values in records. .RE .TP .IR "read_format" @@ -867,12 +888,33 @@ field, but enables including data mmap events in the ring-buffer. .TP .IR "sample_id_all" " (Since Linux 2.6.38)" -If set, then TID, TIME, ID, CPU, and STREAM_ID can +If set, then TID, TIME, ID, STREAM_ID, and CPU can additionally be included in .RB non- PERF_RECORD_SAMPLE s if the corresponding .I sample_type is selected. + +If +.B PERF_SAMPLE_IDENTIFIER +is specified than an additional ID value is included +as the last value to ease parsing the record stream. +This may lead to the +.I id +value appearing twice. + +The layout is described by this pseudo-structure: +.in +4n +.nf +struct sample_id { + { u32 pid, tid; } /* if PERF_SAMPLE_TID set */ + { u64 time; } /* if PERF_SAMPLE_TIME set */ + { u64 id; } /* if PERF_SAMPLE_ID set */ + { u64 stream_id;} /* if PERF_SAMPLE_STREAM_ID set */ + { u32 cpu, res; } /* if PERF_SAMPLE_CPU set */ + { u64 id; } /* if PERF_SAMPLE_IDENTIFIER set */ +}; +.fi .TP .IR "exclude_host" " (Since Linux 3.2)" Do not measure time spent in VM host. @@ -1392,6 +1434,7 @@ The values in the corresponding record (that follows the header) depend on the .I type selected as shown. + .RS .TP 4 .B PERF_RECORD_MMAP @@ -1423,6 +1466,7 @@ struct { struct perf_event_header header; u64 id; u64 lost; + struct sample_id sample_id; }; .fi .in @@ -1444,6 +1488,7 @@ struct { struct perf_event_header header; u32 pid, tid; char comm[]; + struct sample_id sample_id; }; .fi .in @@ -1458,6 +1503,7 @@ struct { u32 pid, ppid; u32 tid, ptid; u64 time; + struct sample_id sample_id; }; .fi .in @@ -1472,6 +1518,7 @@ struct { u64 time; u64 id; u64 stream_id; + struct sample_id sample_id; }; .fi .in @@ -1486,6 +1533,7 @@ struct { u32 pid, ppid; u32 tid, ptid; u64 time; + struct sample_id sample_id; }; .fi .in @@ -1499,6 +1547,7 @@ struct { struct perf_event_header header; u32 pid, tid; struct read_format values; + struct sample_id sample_id; }; .fi .in @@ -1510,6 +1559,7 @@ This record indicates a sample. .nf struct { struct perf_event_header header; + u64 sample_id; /* if PERF_SAMPLE_IDENTIFIER */ u64 ip; /* if PERF_SAMPLE_IP */ u32 pid, tid; /* if PERF_SAMPLE_TID */ u64 time; /* if PERF_SAMPLE_TIME */ @@ -1538,6 +1588,16 @@ struct { .fi .RS 4 .TP 4 +.I sample_id +If +.B PERF_SAMPLE_IDENTIFIER +is enabled, a 64-bit unique ID is included. +This is a duplication of the +.B PERF_SAMPLE_ID +.I id +value, but included at the beginning of the sample +so parsers can easily obtain the value. +.TP .I ip If .B PERF_SAMPLE_IP