Describe perf.data file format.

1. Perf File Format
Kai

2. perf_file_header
a list of ids
(u64 array)
a list of attributes
(perf_file_attr)
data
a list of
perf_file_section
(of optional
features)
data of optional
features
perf.data

3. perf_file_header->attrs->offset
perf_file_header->data->offset
perf_file_header->data->size
perf.data
struct perf_file_header {
uint64_t magic; /* “PERFILE2” */
uint64_t size; /* sizeof(perf_file_header) */
uint64_t attr_size; /* sizeof(perf_file_attr) */
struct perf_file_section attrs;
struct perf_file_section data;
/* event_types is ignored, store zeros */
struct perf_file_section event_types;
DECLARE_BITMAP(adds_features, HEADER_FEAT_BITS);
};
struct perf_file_section {
uint64_t offset;
uint64_t size;
};
perf_file_header->attrs->size
decided by perf_file_header->adds_features
perf_file_header
a list of ids
(u64 array)
a list of attributes
(perf_file_attr)
data
a list of
perf_file_section
(of optional
features)
data of optional
features

4. perf_file_header
a list of ids (u64)
a list of attributes
(perf_file_attr)
perf.datastruct perf_file_attr {
struct perf_event_attr attr;
struct perf_file_section ids;
};
struct perf_file_section {
uint64_t offset;
uint64_t size;
};
event0.id
event1.id
event2.id
event0.attr
event0.ids
event1.attr
event1.ids
event2.attr
event2.ids
event0.ids.offset
struct perf_event_attr {
__u32 type;
__u32 size;
__u64 config;
union {
__u64 sample_period; /* Period of sampling */
__u64 sample_freq; /* Frequency of sampling */
};
__u64 sample_type; /* Specifies values included in sample */
__u64 read_format; /* Specifies values returned in read */
/* 8<——8<——8<——8<——8<—— */
/* remove for clarity */
/* ——>8——>8——>8——>8——>8 */
union {
__u32 wakeup_events; /* wakeup every n events */
__u32 wakeup_watermark; /* bytes before wakeup */
};
};
perf_file_header->attrs->offset
…

5. perf_file_header
a list of ids
a list of attributes
data
a list of
perf_file_section
data of optional
features
perf.datastruct perf_file_section {
uint64_t offset;
uint64_t size;
};
feature0.section
feature1.section
feature0
feature1
feature0.section.offset
static const struct feature_ops feat_ops[HEADER_LAST_FEATURE] = {
FEAT_OPP(HEADER_TRACING_DATA, tracing_data),
FEAT_OPP(HEADER_BUILD_ID, build_id),
FEAT_OPP(HEADER_HOSTNAME, hostname),
FEAT_OPP(HEADER_OSRELEASE, osrelease),
FEAT_OPP(HEADER_VERSION, version),
FEAT_OPP(HEADER_ARCH, arch),
FEAT_OPP(HEADER_NRCPUS, nrcpus),
FEAT_OPP(HEADER_CPUDESC, cpudesc),
FEAT_OPP(HEADER_CPUID, cpuid),
FEAT_OPP(HEADER_TOTAL_MEM, total_mem),
FEAT_OPP(HEADER_EVENT_DESC, event_desc),
FEAT_OPP(HEADER_CMDLINE, cmdline),
FEAT_OPF(HEADER_CPU_TOPOLOGY, cpu_topology),
FEAT_OPF(HEADER_NUMA_TOPOLOGY, numa_topology),
FEAT_OPA(HEADER_BRANCH_STACK, branch_stack),
FEAT_OPP(HEADER_PMU_MAPPINGS, pmu_mappings),
FEAT_OPP(HEADER_GROUP_DESC, group_desc),
FEAT_OPP(HEADER_AUXTRACE, auxtrace),
FEAT_OPA(HEADER_STAT, stat),
};

6. perf_file_header
a list of ids
(u64 array)
a list of attributes
(perf_file_attr)
data
a list of
perf_file_section
(of optional
features)
data of optional
features
perf.datastruct perf_event_header {
__u32 type;
__u16 misc;
__u16 size;
};
event0.header
event0
event1.header
event1
event2.header
event2
event3.header
event3
event4.header
event4
enum perf_event_type {
PERF_RECORD_MMAP = 1,
PERF_RECORD_LOST = 2,
PERF_RECORD_COMM = 3,
PERF_RECORD_EXIT = 4,
PERF_RECORD_THROTTLE = 5,
PERF_RECORD_UNTHROTTLE = 6,
PERF_RECORD_FORK = 7,
PERF_RECORD_READ = 8,
PERF_RECORD_SAMPLE = 9,
PERF_RECORD_MMAP2 = 10,
PERF_RECORD_AUX = 11,
PERF_RECORD_ITRACE_START = 12,
PERF_RECORD_LOST_SAMPLES = 13,
PERF_RECORD_SWITCH = 14,
PERF_RECORD_SWITCH_CPU_WIDE = 15,
PERF_RECORD_MAX, /* non-ABI */
}
according to perf_event_header.type

7. struct perf_event_attr {
__u32 type; /* Type of event */
__u32 size; /* Size of attribute structure */
__u64 config; /* Type-specific configuration */
union {
__u64 sample_period; /* Period of sampling */
__u64 sample_freq; /* Frequency of sampling */
};
__u64 sample_type; /* Specifies values included in sample */
__u64 read_format; /* Specifies values returned in read */
__u64 disabled : 1, /* off by default */
inherit : 1, /* children inherit it */
pinned : 1, /* must always be on PMU */
exclusive : 1, /* only group on PMU */
exclude_user : 1, /* don't count user */
exclude_kernel : 1, /* don't count kernel */
exclude_hv : 1, /* don't count hypervisor */
exclude_idle : 1, /* don't count when idle */
mmap : 1, /* include mmap data */
comm : 1, /* include comm data */
freq : 1, /* use freq, not period */
inherit_stat : 1, /* per task counts */
enable_on_exec : 1, /* next exec enables */
task : 1, /* trace fork/exit */
watermark : 1, /* wakeup_watermark */
precise_ip : 2, /* skid constraint */
mmap_data : 1, /* non-exec mmap data */
sample_id_all : 1, /* sample_type all events */
exclude_host : 1, /* don't count in host */
exclude_guest : 1, /* don't count in guest */
exclude_callchain_kernel : 1,
/* exclude kernel callchains */
exclude_callchain_user : 1,
/* exclude user callchains */

8. Reference
• Perf source code
• libpfm source code
• perf_event_open manpage
• http://man7.org/linux/man-pages/man2/perf_event_open.2.html
• perf.data file format specification draft
• https://lwn.net/Articles/644919/
• perf file format (CERN openlab)
• https://openlab-mu-internal.web.cern.ch/openlab-mu-internal/
03_Documents/3_Technical_Documents/Technical_Reports/2011/
Urs_Fassler_report.pdf