1 perf.data format 1 perf.data format
2 2
3 Uptodate as of v4.7 3 Uptodate as of v4.7
4 4
5 This document describes the on-disk perf.data 5 This document describes the on-disk perf.data format, generated by perf record
6 or perf inject and consumed by the other perf 6 or perf inject and consumed by the other perf tools.
7 7
8 On a high level perf.data contains the events 8 On a high level perf.data contains the events generated by the PMUs, plus metadata.
9 9
10 All fields are in native-endian of the machine 10 All fields are in native-endian of the machine that generated the perf.data.
11 11
12 When perf is writing to a pipe it uses a speci 12 When perf is writing to a pipe it uses a special version of the file
13 format that does not rely on seeking to adjust 13 format that does not rely on seeking to adjust data offsets. This
14 format is described in "Pipe-mode data" sectio 14 format is described in "Pipe-mode data" section. The pipe data version can be
15 augmented with additional events using perf in 15 augmented with additional events using perf inject.
16 16
17 The file starts with a perf_header: 17 The file starts with a perf_header:
18 18
19 struct perf_header { 19 struct perf_header {
20 char magic[8]; /* PERFILE2 */ 20 char magic[8]; /* PERFILE2 */
21 uint64_t size; /* size of the 21 uint64_t size; /* size of the header */
22 uint64_t attr_size; /* size of an 22 uint64_t attr_size; /* size of an attribute in attrs */
23 struct perf_file_section attrs; 23 struct perf_file_section attrs;
24 struct perf_file_section data; 24 struct perf_file_section data;
25 struct perf_file_section event_types; 25 struct perf_file_section event_types;
26 uint64_t flags; 26 uint64_t flags;
27 uint64_t flags1[3]; 27 uint64_t flags1[3];
28 }; 28 };
29 29
30 The magic number identifies the perf file and 30 The magic number identifies the perf file and the version. Current perf versions
31 use PERFILE2. Old perf versions generated a ve 31 use PERFILE2. Old perf versions generated a version 1 format (PERFFILE). Version 1
32 is not described here. The magic number also i 32 is not described here. The magic number also identifies the endian. When the
33 magic value is 64bit byte swapped compared the 33 magic value is 64bit byte swapped compared the file is in non-native
34 endian. 34 endian.
35 35
36 A perf_file_section contains a pointer to anot 36 A perf_file_section contains a pointer to another section of the perf file.
37 The header contains three such pointers: for a 37 The header contains three such pointers: for attributes, data and event types.
38 38
39 struct perf_file_section { 39 struct perf_file_section {
40 uint64_t offset; /* offset from 40 uint64_t offset; /* offset from start of file */
41 uint64_t size; /* size of the 41 uint64_t size; /* size of the section */
42 }; 42 };
43 43
44 Flags section: 44 Flags section:
45 45
46 For each of the optional features a perf_file_ !! 46 For each of the optional features a perf_file_section it placed after the data
47 section if the feature bit is set in the perf_ 47 section if the feature bit is set in the perf_header flags bitset. The
48 respective perf_file_section points to the dat 48 respective perf_file_section points to the data of the additional header and
49 defines its size. 49 defines its size.
50 50
51 Some headers consist of strings, which are def 51 Some headers consist of strings, which are defined like this:
52 52
53 struct perf_header_string { 53 struct perf_header_string {
54 uint32_t len; 54 uint32_t len;
55 char string[len]; /* zero terminated */ 55 char string[len]; /* zero terminated */
56 }; 56 };
57 57
58 Some headers consist of a sequence of strings, 58 Some headers consist of a sequence of strings, which start with a
59 59
60 struct perf_header_string_list { 60 struct perf_header_string_list {
61 uint32_t nr; 61 uint32_t nr;
62 struct perf_header_string strings[nr]; /* 62 struct perf_header_string strings[nr]; /* variable length records */
63 }; 63 };
64 64
65 The bits are the flags bits in a 256 bit bitma 65 The bits are the flags bits in a 256 bit bitmap starting with
66 flags. These define the valid bits: 66 flags. These define the valid bits:
67 67
68 HEADER_RESERVED = 0, /* alw 68 HEADER_RESERVED = 0, /* always cleared */
69 HEADER_FIRST_FEATURE = 1, 69 HEADER_FIRST_FEATURE = 1,
70 HEADER_TRACING_DATA = 1, 70 HEADER_TRACING_DATA = 1,
71 71
72 Describe me. 72 Describe me.
73 73
74 HEADER_BUILD_ID = 2, 74 HEADER_BUILD_ID = 2,
75 75
76 The header consists of an sequence of build_id 76 The header consists of an sequence of build_id_event. The size of each record
77 is defined by header.size (see perf_event.h). 77 is defined by header.size (see perf_event.h). Each event defines a ELF build id
78 for a executable file name for a pid. An ELF b 78 for a executable file name for a pid. An ELF build id is a unique identifier
79 assigned by the linker to an executable. 79 assigned by the linker to an executable.
80 80
81 struct build_id_event { 81 struct build_id_event {
82 struct perf_event_header header; 82 struct perf_event_header header;
83 pid_t pid; 83 pid_t pid;
84 uint8_t build_id[24]; 84 uint8_t build_id[24];
85 char filename[head 85 char filename[header.size - offsetof(struct build_id_event, filename)];
86 }; 86 };
87 87
88 HEADER_HOSTNAME = 3, 88 HEADER_HOSTNAME = 3,
89 89
90 A perf_header_string with the hostname where t 90 A perf_header_string with the hostname where the data was collected
91 (uname -n) 91 (uname -n)
92 92
93 HEADER_OSRELEASE = 4, 93 HEADER_OSRELEASE = 4,
94 94
95 A perf_header_string with the os release where 95 A perf_header_string with the os release where the data was collected
96 (uname -r) 96 (uname -r)
97 97
98 HEADER_VERSION = 5, 98 HEADER_VERSION = 5,
99 99
100 A perf_header_string with the perf user tool v 100 A perf_header_string with the perf user tool version where the
101 data was collected. This is the same as the ve 101 data was collected. This is the same as the version of the source tree
102 the perf tool was built from. 102 the perf tool was built from.
103 103
104 HEADER_ARCH = 6, 104 HEADER_ARCH = 6,
105 105
106 A perf_header_string with the CPU architecture 106 A perf_header_string with the CPU architecture (uname -m)
107 107
108 HEADER_NRCPUS = 7, 108 HEADER_NRCPUS = 7,
109 109
110 A structure defining the number of CPUs. 110 A structure defining the number of CPUs.
111 111
112 struct nr_cpus { 112 struct nr_cpus {
113 uint32_t nr_cpus_available; /* CPUs not 113 uint32_t nr_cpus_available; /* CPUs not yet onlined */
114 uint32_t nr_cpus_online; 114 uint32_t nr_cpus_online;
115 }; 115 };
116 116
117 HEADER_CPUDESC = 8, 117 HEADER_CPUDESC = 8,
118 118
119 A perf_header_string with description of the C 119 A perf_header_string with description of the CPU. On x86 this is the model name
120 in /proc/cpuinfo 120 in /proc/cpuinfo
121 121
122 HEADER_CPUID = 9, 122 HEADER_CPUID = 9,
123 123
124 A perf_header_string with the exact CPU type. 124 A perf_header_string with the exact CPU type. On x86 this is
125 vendor,family,model,stepping. For example: Gen 125 vendor,family,model,stepping. For example: GenuineIntel,6,69,1
126 126
127 HEADER_TOTAL_MEM = 10, 127 HEADER_TOTAL_MEM = 10,
128 128
129 An uint64_t with the total memory in kilobytes 129 An uint64_t with the total memory in kilobytes.
130 130
131 HEADER_CMDLINE = 11, 131 HEADER_CMDLINE = 11,
132 132
133 A perf_header_string_list with the perf arg-ve 133 A perf_header_string_list with the perf arg-vector used to collect the data.
134 134
135 HEADER_EVENT_DESC = 12, 135 HEADER_EVENT_DESC = 12,
136 136
137 Another description of the perf_event_attrs, m 137 Another description of the perf_event_attrs, more detailed than header.attrs
138 including IDs and names. See perf_event.h or t 138 including IDs and names. See perf_event.h or the man page for a description
139 of a struct perf_event_attr. 139 of a struct perf_event_attr.
140 140
141 struct { 141 struct {
142 uint32_t nr; /* number of events */ 142 uint32_t nr; /* number of events */
143 uint32_t attr_size; /* size of each per 143 uint32_t attr_size; /* size of each perf_event_attr */
144 struct { 144 struct {
145 struct perf_event_attr attr; /* 145 struct perf_event_attr attr; /* size of attr_size */
146 uint32_t nr_ids; 146 uint32_t nr_ids;
147 struct perf_header_string event_ 147 struct perf_header_string event_string;
148 uint64_t ids[nr_ids]; 148 uint64_t ids[nr_ids];
149 } events[nr]; /* Variable length record 149 } events[nr]; /* Variable length records */
150 }; 150 };
151 151
152 HEADER_CPU_TOPOLOGY = 13, 152 HEADER_CPU_TOPOLOGY = 13,
153 153
154 struct { 154 struct {
155 /* 155 /*
156 * First revision of HEADER_CPU_TOPOLO 156 * First revision of HEADER_CPU_TOPOLOGY
157 * 157 *
158 * See 'struct perf_header_string_list 158 * See 'struct perf_header_string_list' definition earlier
159 * in this file. 159 * in this file.
160 */ 160 */
161 161
162 struct perf_header_string_list cores; / 162 struct perf_header_string_list cores; /* Variable length */
163 struct perf_header_string_list threads; 163 struct perf_header_string_list threads; /* Variable length */
164 164
165 /* 165 /*
166 * Second revision of HEADER_CPU_TOPOLO 166 * Second revision of HEADER_CPU_TOPOLOGY, older tools
167 * will not consider what comes next 167 * will not consider what comes next
168 */ 168 */
169 169
170 struct { 170 struct {
171 uint32_t core_id; 171 uint32_t core_id;
172 uint32_t socket_id; 172 uint32_t socket_id;
173 } cpus[nr]; /* Variable length records 173 } cpus[nr]; /* Variable length records */
174 /* 'nr' comes from previously processed 174 /* 'nr' comes from previously processed HEADER_NRCPUS's nr_cpu_avail */
175 175
176 /* 176 /*
177 * Third revision of HEADER_CPU_TOPOLO 177 * Third revision of HEADER_CPU_TOPOLOGY, older tools
178 * will not consider what comes next 178 * will not consider what comes next
179 */ 179 */
180 180
181 struct perf_header_string_list dies; / 181 struct perf_header_string_list dies; /* Variable length */
182 uint32_t die_id[nr_cpus_avail]; /* fro 182 uint32_t die_id[nr_cpus_avail]; /* from previously processed HEADER_NR_CPUS, VLA */
183 }; 183 };
184 184
185 Example: 185 Example:
186 sibling sockets : 0-8 186 sibling sockets : 0-8
187 sibling dies : 0-3 187 sibling dies : 0-3
188 sibling dies : 4-7 188 sibling dies : 4-7
189 sibling threads : 0-1 189 sibling threads : 0-1
190 sibling threads : 2-3 190 sibling threads : 2-3
191 sibling threads : 4-5 191 sibling threads : 4-5
192 sibling threads : 6-7 192 sibling threads : 6-7
193 193
194 HEADER_NUMA_TOPOLOGY = 14, 194 HEADER_NUMA_TOPOLOGY = 14,
195 195
196 A list of NUMA node descriptions 196 A list of NUMA node descriptions
197 197
198 struct { 198 struct {
199 uint32_t nr; 199 uint32_t nr;
200 struct { 200 struct {
201 uint32_t nodenr; 201 uint32_t nodenr;
202 uint64_t mem_total; 202 uint64_t mem_total;
203 uint64_t mem_free; 203 uint64_t mem_free;
204 struct perf_header_string cpus; 204 struct perf_header_string cpus;
205 } nodes[nr]; /* Variable length records 205 } nodes[nr]; /* Variable length records */
206 }; 206 };
207 207
208 HEADER_BRANCH_STACK = 15, 208 HEADER_BRANCH_STACK = 15,
209 209
210 Not implemented in perf. 210 Not implemented in perf.
211 211
212 HEADER_PMU_MAPPINGS = 16, 212 HEADER_PMU_MAPPINGS = 16,
213 213
214 A list of PMU structures, defining the 214 A list of PMU structures, defining the different PMUs supported by perf.
215 215
216 struct { 216 struct {
217 uint32_t nr; 217 uint32_t nr;
218 struct pmu { 218 struct pmu {
219 uint32_t pmu_type; 219 uint32_t pmu_type;
220 struct perf_header_string pmu_na 220 struct perf_header_string pmu_name;
221 } [nr]; /* Variable length records */ 221 } [nr]; /* Variable length records */
222 }; 222 };
223 223
224 HEADER_GROUP_DESC = 17, 224 HEADER_GROUP_DESC = 17,
225 225
226 Description of counter groups ({...} i 226 Description of counter groups ({...} in perf syntax)
227 227
228 struct { 228 struct {
229 uint32_t nr; 229 uint32_t nr;
230 struct { 230 struct {
231 struct perf_header_string stri 231 struct perf_header_string string;
232 uint32_t leader_idx; 232 uint32_t leader_idx;
233 uint32_t nr_members; 233 uint32_t nr_members;
234 } [nr]; /* Variable length records */ 234 } [nr]; /* Variable length records */
235 }; 235 };
236 236
237 HEADER_AUXTRACE = 18, 237 HEADER_AUXTRACE = 18,
238 238
239 Define additional auxtrace areas in the perf.d 239 Define additional auxtrace areas in the perf.data. auxtrace is used to store
240 undecoded hardware tracing information, such a 240 undecoded hardware tracing information, such as Intel Processor Trace data.
241 241
242 /** 242 /**
243 * struct auxtrace_index_entry - indexes a AUX 243 * struct auxtrace_index_entry - indexes a AUX area tracing event within a
244 * perf.data fil 244 * perf.data file.
245 * @file_offset: offset within the perf.data f 245 * @file_offset: offset within the perf.data file
246 * @sz: size of the event 246 * @sz: size of the event
247 */ 247 */
248 struct auxtrace_index_entry { 248 struct auxtrace_index_entry {
249 u64 file_offset; 249 u64 file_offset;
250 u64 sz; 250 u64 sz;
251 }; 251 };
252 252
253 #define PERF_AUXTRACE_INDEX_ENTRY_COUNT 256 253 #define PERF_AUXTRACE_INDEX_ENTRY_COUNT 256
254 254
255 /** 255 /**
256 * struct auxtrace_index - index of AUX area t 256 * struct auxtrace_index - index of AUX area tracing events within a perf.data
257 * file. 257 * file.
258 * @list: linking a number of arrays of entrie 258 * @list: linking a number of arrays of entries
259 * @nr: number of entries 259 * @nr: number of entries
260 * @entries: array of entries 260 * @entries: array of entries
261 */ 261 */
262 struct auxtrace_index { 262 struct auxtrace_index {
263 struct list_head list; 263 struct list_head list;
264 size_t nr; 264 size_t nr;
265 struct auxtrace_index_entry entries[PE 265 struct auxtrace_index_entry entries[PERF_AUXTRACE_INDEX_ENTRY_COUNT];
266 }; 266 };
267 267
268 HEADER_STAT = 19, 268 HEADER_STAT = 19,
269 269
270 This is merely a flag signifying that the data 270 This is merely a flag signifying that the data section contains data
271 recorded from perf stat record. 271 recorded from perf stat record.
272 272
273 HEADER_CACHE = 20, 273 HEADER_CACHE = 20,
274 274
275 Description of the cache hierarchy. Based on t 275 Description of the cache hierarchy. Based on the Linux sysfs format
276 in /sys/devices/system/cpu/cpu*/cache/ 276 in /sys/devices/system/cpu/cpu*/cache/
277 277
278 u32 version Currently always 1 278 u32 version Currently always 1
279 u32 number_of_cache_levels 279 u32 number_of_cache_levels
280 280
281 struct { 281 struct {
282 u32 level; 282 u32 level;
283 u32 line_size; 283 u32 line_size;
284 u32 sets; 284 u32 sets;
285 u32 ways; 285 u32 ways;
286 struct perf_header_string type; 286 struct perf_header_string type;
287 struct perf_header_string size; 287 struct perf_header_string size;
288 struct perf_header_string map; 288 struct perf_header_string map;
289 }[number_of_cache_levels]; 289 }[number_of_cache_levels];
290 290
291 HEADER_SAMPLE_TIME = 21, 291 HEADER_SAMPLE_TIME = 21,
292 292
293 Two uint64_t for the time of first sample and 293 Two uint64_t for the time of first sample and the time of last sample.
294 294
295 HEADER_SAMPLE_TOPOLOGY = 22, 295 HEADER_SAMPLE_TOPOLOGY = 22,
296 296
297 Physical memory map and its node assignments. 297 Physical memory map and its node assignments.
298 298
299 The format of data in MEM_TOPOLOGY is as follo 299 The format of data in MEM_TOPOLOGY is as follows:
300 300
301 u64 version; // Currently 1 301 u64 version; // Currently 1
302 u64 block_size_bytes; // /sys/device 302 u64 block_size_bytes; // /sys/devices/system/memory/block_size_bytes
303 u64 count; // number of n 303 u64 count; // number of nodes
304 304
305 struct memory_node { 305 struct memory_node {
306 u64 node_id; // node index 306 u64 node_id; // node index
307 u64 size; // size of bit 307 u64 size; // size of bitmap
308 struct bitmap { 308 struct bitmap {
309 /* size of bitmap again */ 309 /* size of bitmap again */
310 u64 bitmapsize; 310 u64 bitmapsize;
311 /* bitmap of memory indexes th 311 /* bitmap of memory indexes that belongs to node */
312 /* /sys/devices/system/node/no 312 /* /sys/devices/system/node/node<NODE>/memory<INDEX> */
313 u64 entries[(bitmapsize/64)+1] 313 u64 entries[(bitmapsize/64)+1];
314 } 314 }
315 }[count]; 315 }[count];
316 316
317 The MEM_TOPOLOGY can be displayed with followi 317 The MEM_TOPOLOGY can be displayed with following command:
318 318
319 $ perf report --header-only -I 319 $ perf report --header-only -I
320 ... 320 ...
321 # memory nodes (nr 1, block size 0x8000000): 321 # memory nodes (nr 1, block size 0x8000000):
322 # 0 [7G]: 0-23,32-69 322 # 0 [7G]: 0-23,32-69
323 323
324 HEADER_CLOCKID = 23, 324 HEADER_CLOCKID = 23,
325 325
326 One uint64_t for the clockid frequency, specif 326 One uint64_t for the clockid frequency, specified, for instance, via 'perf
327 record -k' (see clock_gettime()), to enable ti 327 record -k' (see clock_gettime()), to enable timestamps derived metrics
328 conversion into wall clock time on the reporti 328 conversion into wall clock time on the reporting stage.
329 329
330 HEADER_DIR_FORMAT = 24, 330 HEADER_DIR_FORMAT = 24,
331 331
332 The data files layout is described by HEADER_D 332 The data files layout is described by HEADER_DIR_FORMAT feature. Currently it
333 holds only version number (1): 333 holds only version number (1):
334 334
335 uint64_t version; 335 uint64_t version;
336 336
337 The current version holds only version value ( 337 The current version holds only version value (1) means that data files:
338 338
339 - Follow the 'data.*' name format. 339 - Follow the 'data.*' name format.
340 340
341 - Contain raw events data in standard perf for 341 - Contain raw events data in standard perf format as read from kernel (and need
342 to be sorted) 342 to be sorted)
343 343
344 Future versions are expected to describe diffe 344 Future versions are expected to describe different data files layout according
345 to special needs. 345 to special needs.
346 346
347 HEADER_BPF_PROG_INFO = 25, 347 HEADER_BPF_PROG_INFO = 25,
348 348
349 struct perf_bpil, which contains detailed info 349 struct perf_bpil, which contains detailed information about
350 a BPF program, including type, id, tag, jited/ 350 a BPF program, including type, id, tag, jited/xlated instructions, etc.
351 351
352 HEADER_BPF_BTF = 26, 352 HEADER_BPF_BTF = 26,
353 353
354 Contains BPF Type Format (BTF). For more infor 354 Contains BPF Type Format (BTF). For more information about BTF, please
355 refer to Documentation/bpf/btf.rst. 355 refer to Documentation/bpf/btf.rst.
356 356
357 struct { 357 struct {
358 u32 id; 358 u32 id;
359 u32 data_size; 359 u32 data_size;
360 char data[]; 360 char data[];
361 }; 361 };
362 362
363 HEADER_COMPRESSED = 27, 363 HEADER_COMPRESSED = 27,
364 364
365 struct { 365 struct {
366 u32 version; 366 u32 version;
367 u32 type; 367 u32 type;
368 u32 level; 368 u32 level;
369 u32 ratio; 369 u32 ratio;
370 u32 mmap_len; 370 u32 mmap_len;
371 }; 371 };
372 372
373 Indicates that trace contains records of PERF_ 373 Indicates that trace contains records of PERF_RECORD_COMPRESSED type
374 that have perf_events records in compressed fo 374 that have perf_events records in compressed form.
375 375
376 HEADER_CPU_PMU_CAPS = 28, 376 HEADER_CPU_PMU_CAPS = 28,
377 377
378 A list of cpu PMU capabilities. The fo 378 A list of cpu PMU capabilities. The format of data is as below.
379 379
380 struct { 380 struct {
381 u32 nr_cpu_pmu_caps; 381 u32 nr_cpu_pmu_caps;
382 { 382 {
383 char name[]; 383 char name[];
384 char value[]; 384 char value[];
385 } [nr_cpu_pmu_caps] 385 } [nr_cpu_pmu_caps]
386 }; 386 };
387 387
388 388
389 Example: 389 Example:
390 cpu pmu capabilities: branches=32, max_precis 390 cpu pmu capabilities: branches=32, max_precise=3, pmu_name=icelake
391 391
392 HEADER_CLOCK_DATA = 29, 392 HEADER_CLOCK_DATA = 29,
393 393
394 Contains clock id and its reference ti 394 Contains clock id and its reference time together with wall clock
395 time taken at the 'same time', both va 395 time taken at the 'same time', both values are in nanoseconds.
396 The format of data is as below. 396 The format of data is as below.
397 397
398 struct { 398 struct {
399 u32 version; /* version = 1 */ 399 u32 version; /* version = 1 */
400 u32 clockid; 400 u32 clockid;
401 u64 wall_clock_ns; 401 u64 wall_clock_ns;
402 u64 clockid_time_ns; 402 u64 clockid_time_ns;
403 }; 403 };
404 404
405 HEADER_HYBRID_TOPOLOGY = 30, 405 HEADER_HYBRID_TOPOLOGY = 30,
406 406
407 Indicate the hybrid CPUs. The format of data i 407 Indicate the hybrid CPUs. The format of data is as below.
408 408
409 struct { 409 struct {
410 u32 nr; 410 u32 nr;
411 struct { 411 struct {
412 char pmu_name[]; 412 char pmu_name[];
413 char cpus[]; 413 char cpus[];
414 } [nr]; /* Variable length records */ 414 } [nr]; /* Variable length records */
415 }; 415 };
416 416
417 Example: 417 Example:
418 hybrid cpu system: 418 hybrid cpu system:
419 cpu_core cpu list : 0-15 419 cpu_core cpu list : 0-15
420 cpu_atom cpu list : 16-23 420 cpu_atom cpu list : 16-23
421 421
422 HEADER_PMU_CAPS = 31, 422 HEADER_PMU_CAPS = 31,
423 423
424 List of pmu capabilities (except cpu p 424 List of pmu capabilities (except cpu pmu which is already
425 covered by HEADER_CPU_PMU_CAPS). Note 425 covered by HEADER_CPU_PMU_CAPS). Note that hybrid cpu pmu
426 capabilities are also stored here. 426 capabilities are also stored here.
427 427
428 struct { 428 struct {
429 u32 nr_pmu; 429 u32 nr_pmu;
430 struct { 430 struct {
431 u32 nr_caps; 431 u32 nr_caps;
432 { 432 {
433 char name[]; 433 char name[];
434 char value[]; 434 char value[];
435 } [nr_caps]; 435 } [nr_caps];
436 char pmu_name[]; 436 char pmu_name[];
437 } [nr_pmu]; 437 } [nr_pmu];
438 }; 438 };
439 439
440 other bits are reserved and should ign 440 other bits are reserved and should ignored for now
441 HEADER_FEAT_BITS = 256, 441 HEADER_FEAT_BITS = 256,
442 442
443 Attributes 443 Attributes
444 444
445 This is an array of perf_event_attrs, each att 445 This is an array of perf_event_attrs, each attr_size bytes long, which defines
446 each event collected. See perf_event.h or the 446 each event collected. See perf_event.h or the man page for a detailed
447 description. 447 description.
448 448
449 Data 449 Data
450 450
451 This section is the bulk of the file. It consi 451 This section is the bulk of the file. It consist of a stream of perf_events
452 describing events. This matches the format gen 452 describing events. This matches the format generated by the kernel.
453 See perf_event.h or the manpage for a detailed 453 See perf_event.h or the manpage for a detailed description.
454 454
455 Some notes on parsing: 455 Some notes on parsing:
456 456
457 Ordering 457 Ordering
458 458
459 The events are not necessarily in time stamp o 459 The events are not necessarily in time stamp order, as they can be
460 collected in parallel on different CPUs. If th 460 collected in parallel on different CPUs. If the events should be
461 processed in time order they need to be sorted 461 processed in time order they need to be sorted first. It is possible
462 to only do a partial sort using the FINISHED_R 462 to only do a partial sort using the FINISHED_ROUND event header (see
463 below). perf record guarantees that there is n 463 below). perf record guarantees that there is no reordering over a
464 FINISHED_ROUND. 464 FINISHED_ROUND.
465 465
466 ID vs IDENTIFIER 466 ID vs IDENTIFIER
467 467
468 When the event stream contains multiple events 468 When the event stream contains multiple events each event is identified
469 by an ID. This can be either through the PERF_ 469 by an ID. This can be either through the PERF_SAMPLE_ID or the
470 PERF_SAMPLE_IDENTIFIER header. The PERF_SAMPLE 470 PERF_SAMPLE_IDENTIFIER header. The PERF_SAMPLE_IDENTIFIER header is
471 at a fixed offset from the event header, which 471 at a fixed offset from the event header, which allows reliable
472 parsing of the header. Relying on ID may be am 472 parsing of the header. Relying on ID may be ambiguous.
473 IDENTIFIER is only supported by newer Linux ke 473 IDENTIFIER is only supported by newer Linux kernels.
474 474
475 Perf record specific events: 475 Perf record specific events:
476 476
477 In addition to the kernel generated event type 477 In addition to the kernel generated event types perf record adds its
478 own event types (in addition it also synthesiz 478 own event types (in addition it also synthesizes some kernel events,
479 for example MMAP events) 479 for example MMAP events)
480 480
481 PERF_RECORD_USER_TYPE_START 481 PERF_RECORD_USER_TYPE_START = 64,
482 PERF_RECORD_HEADER_ATTR 482 PERF_RECORD_HEADER_ATTR = 64,
483 483
484 struct attr_event { 484 struct attr_event {
485 struct perf_event_header header; 485 struct perf_event_header header;
486 struct perf_event_attr attr; 486 struct perf_event_attr attr;
487 uint64_t id[]; 487 uint64_t id[];
488 }; 488 };
489 489
490 PERF_RECORD_HEADER_EVENT_TYPE 490 PERF_RECORD_HEADER_EVENT_TYPE = 65, /* deprecated */
491 491
492 #define MAX_EVENT_NAME 64 492 #define MAX_EVENT_NAME 64
493 493
494 struct perf_trace_event_type { 494 struct perf_trace_event_type {
495 uint64_t event_id; 495 uint64_t event_id;
496 char name[MAX_EVENT_NAME]; 496 char name[MAX_EVENT_NAME];
497 }; 497 };
498 498
499 struct event_type_event { 499 struct event_type_event {
500 struct perf_event_header header; 500 struct perf_event_header header;
501 struct perf_trace_event_type event_typ 501 struct perf_trace_event_type event_type;
502 }; 502 };
503 503
504 504
505 PERF_RECORD_HEADER_TRACING_DATA 505 PERF_RECORD_HEADER_TRACING_DATA = 66,
506 506
507 Describe me 507 Describe me
508 508
509 struct tracing_data_event { 509 struct tracing_data_event {
510 struct perf_event_header header; 510 struct perf_event_header header;
511 uint32_t size; 511 uint32_t size;
512 }; 512 };
513 513
514 PERF_RECORD_HEADER_BUILD_ID 514 PERF_RECORD_HEADER_BUILD_ID = 67,
515 515
516 Define a ELF build ID for a referenced executa 516 Define a ELF build ID for a referenced executable.
517 517
518 struct build_id_event; /* See above * 518 struct build_id_event; /* See above */
519 519
520 PERF_RECORD_FINISHED_ROUND 520 PERF_RECORD_FINISHED_ROUND = 68,
521 521
522 No event reordering over this header. No paylo 522 No event reordering over this header. No payload.
523 523
524 PERF_RECORD_ID_INDEX 524 PERF_RECORD_ID_INDEX = 69,
525 525
526 Map event ids to CPUs and TIDs. 526 Map event ids to CPUs and TIDs.
527 527
528 struct id_index_entry { 528 struct id_index_entry {
529 uint64_t id; 529 uint64_t id;
530 uint64_t idx; 530 uint64_t idx;
531 uint64_t cpu; 531 uint64_t cpu;
532 uint64_t tid; 532 uint64_t tid;
533 }; 533 };
534 534
535 struct id_index_event { 535 struct id_index_event {
536 struct perf_event_header header; 536 struct perf_event_header header;
537 uint64_t nr; 537 uint64_t nr;
538 struct id_index_entry entries[nr]; 538 struct id_index_entry entries[nr];
539 }; 539 };
540 540
541 PERF_RECORD_AUXTRACE_INFO 541 PERF_RECORD_AUXTRACE_INFO = 70,
542 542
543 Auxtrace type specific information. Describe m 543 Auxtrace type specific information. Describe me
544 544
545 struct auxtrace_info_event { 545 struct auxtrace_info_event {
546 struct perf_event_header header; 546 struct perf_event_header header;
547 uint32_t type; 547 uint32_t type;
548 uint32_t reserved__; /* For alignment 548 uint32_t reserved__; /* For alignment */
549 uint64_t priv[]; 549 uint64_t priv[];
550 }; 550 };
551 551
552 PERF_RECORD_AUXTRACE 552 PERF_RECORD_AUXTRACE = 71,
553 553
554 Defines auxtrace data. Followed by the actual 554 Defines auxtrace data. Followed by the actual data. The contents of
555 the auxtrace data is dependent on the event an 555 the auxtrace data is dependent on the event and the CPU. For example
556 for Intel Processor Trace it contains Processo 556 for Intel Processor Trace it contains Processor Trace data generated
557 by the CPU. 557 by the CPU.
558 558
559 struct auxtrace_event { 559 struct auxtrace_event {
560 struct perf_event_header header; 560 struct perf_event_header header;
561 uint64_t size; 561 uint64_t size;
562 uint64_t offset; 562 uint64_t offset;
563 uint64_t reference; 563 uint64_t reference;
564 uint32_t idx; 564 uint32_t idx;
565 uint32_t tid; 565 uint32_t tid;
566 uint32_t cpu; 566 uint32_t cpu;
567 uint32_t reserved__; /* For alignment 567 uint32_t reserved__; /* For alignment */
568 }; 568 };
569 569
570 struct aux_event { 570 struct aux_event {
571 struct perf_event_header header; 571 struct perf_event_header header;
572 uint64_t aux_offset; 572 uint64_t aux_offset;
573 uint64_t aux_size; 573 uint64_t aux_size;
574 uint64_t flags; 574 uint64_t flags;
575 }; 575 };
576 576
577 PERF_RECORD_AUXTRACE_ERROR 577 PERF_RECORD_AUXTRACE_ERROR = 72,
578 578
579 Describes an error in hardware tracing 579 Describes an error in hardware tracing
580 580
581 enum auxtrace_error_type { 581 enum auxtrace_error_type {
582 PERF_AUXTRACE_ERROR_ITRACE = 1, 582 PERF_AUXTRACE_ERROR_ITRACE = 1,
583 PERF_AUXTRACE_ERROR_MAX 583 PERF_AUXTRACE_ERROR_MAX
584 }; 584 };
585 585
586 #define MAX_AUXTRACE_ERROR_MSG 64 586 #define MAX_AUXTRACE_ERROR_MSG 64
587 587
588 struct auxtrace_error_event { 588 struct auxtrace_error_event {
589 struct perf_event_header header; 589 struct perf_event_header header;
590 uint32_t type; 590 uint32_t type;
591 uint32_t code; 591 uint32_t code;
592 uint32_t cpu; 592 uint32_t cpu;
593 uint32_t pid; 593 uint32_t pid;
594 uint32_t tid; 594 uint32_t tid;
595 uint32_t reserved__; /* For alignment 595 uint32_t reserved__; /* For alignment */
596 uint64_t ip; 596 uint64_t ip;
597 char msg[MAX_AUXTRACE_ERROR_MSG]; 597 char msg[MAX_AUXTRACE_ERROR_MSG];
598 }; 598 };
599 599
600 PERF_RECORD_HEADER_FEATURE 600 PERF_RECORD_HEADER_FEATURE = 80,
601 601
602 Describes a header feature. These are records 602 Describes a header feature. These are records used in pipe-mode that
603 contain information that otherwise would be in 603 contain information that otherwise would be in perf.data file's header.
604 604
605 PERF_RECORD_COMPRESSED 605 PERF_RECORD_COMPRESSED = 81,
606 606
607 struct compressed_event { 607 struct compressed_event {
608 struct perf_event_header header 608 struct perf_event_header header;
609 char data[] 609 char data[];
610 }; 610 };
611 611
612 PERF_RECORD_FINISHED_INIT 612 PERF_RECORD_FINISHED_INIT = 82,
613 613
614 Marks the end of records for the system, pre-e 614 Marks the end of records for the system, pre-existing threads in system wide
615 sessions, etc. Those are the ones prefixed PER 615 sessions, etc. Those are the ones prefixed PERF_RECORD_USER_*.
616 616
617 This is used, for instance, to 'perf inject' e 617 This is used, for instance, to 'perf inject' events after init and before
618 regular events, those emitted by the kernel, t 618 regular events, those emitted by the kernel, to support combining guest and
619 host records. 619 host records.
620 620
621 621
622 The header is followed by compressed data fram 622 The header is followed by compressed data frame that can be decompressed
623 into array of perf trace records. The size of 623 into array of perf trace records. The size of the entire compressed event
624 record including the header is limited by the 624 record including the header is limited by the max value of header.size.
625 625
626 Event types 626 Event types
627 627
628 Define the event attributes with their IDs. 628 Define the event attributes with their IDs.
629 629
630 An array bound by the perf_file_section size. 630 An array bound by the perf_file_section size.
631 631
632 struct { 632 struct {
633 struct perf_event_attr attr; 633 struct perf_event_attr attr; /* Size defined by header.attr_size */
634 struct perf_file_section ids; 634 struct perf_file_section ids;
635 } 635 }
636 636
637 ids points to a array of uint64_t defining the 637 ids points to a array of uint64_t defining the ids for event attr attr.
638 638
639 Pipe-mode data 639 Pipe-mode data
640 640
641 Pipe-mode avoid seeks in the file by removing 641 Pipe-mode avoid seeks in the file by removing the perf_file_section and flags
642 from the struct perf_header. The trimmed heade 642 from the struct perf_header. The trimmed header is:
643 643
644 struct perf_pipe_file_header { 644 struct perf_pipe_file_header {
645 u64 magic; 645 u64 magic;
646 u64 size; 646 u64 size;
647 }; 647 };
648 648
649 The information about attrs, data, and event_t 649 The information about attrs, data, and event_types is instead in the
650 synthesized events PERF_RECORD_ATTR, PERF_RECO 650 synthesized events PERF_RECORD_ATTR, PERF_RECORD_HEADER_TRACING_DATA,
651 PERF_RECORD_HEADER_EVENT_TYPE, and PERF_RECORD 651 PERF_RECORD_HEADER_EVENT_TYPE, and PERF_RECORD_HEADER_FEATURE
652 that are generated by perf record in pipe-mode 652 that are generated by perf record in pipe-mode.
653 653
654 654
655 References: 655 References:
656 656
657 include/uapi/linux/perf_event.h 657 include/uapi/linux/perf_event.h
658 658
659 This is the canonical description of the kerne 659 This is the canonical description of the kernel generated perf_events
660 and the perf_event_attrs. 660 and the perf_event_attrs.
661 661
662 perf_events manpage 662 perf_events manpage
663 663
664 A manpage describing perf_event and perf_event 664 A manpage describing perf_event and perf_event_attr is here:
665 http://web.eece.maine.edu/~vweaver/projects/pe 665 http://web.eece.maine.edu/~vweaver/projects/perf_events/programming.html
666 This tends to be slightly behind the kernel in 666 This tends to be slightly behind the kernel include, but has better
667 descriptions. An (typically older) version of 667 descriptions. An (typically older) version of the man page may be
668 included with the standard Linux man pages, av 668 included with the standard Linux man pages, available with "man
669 perf_events" 669 perf_events"
670 670
671 pmu-tools 671 pmu-tools
672 672
673 https://github.com/andikleen/pmu-tools/tree/ma 673 https://github.com/andikleen/pmu-tools/tree/master/parser
674 674
675 A definition of the perf.data format in python 675 A definition of the perf.data format in python "construct" format is available
676 in pmu-tools parser. This allows to read perf. 676 in pmu-tools parser. This allows to read perf.data from python and dump it.
677 677
678 quipper 678 quipper
679 679
680 The quipper C++ parser is available at 680 The quipper C++ parser is available at
681 http://github.com/google/perf_data_converter/t 681 http://github.com/google/perf_data_converter/tree/master/src/quipper
682 682
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.