1d4897e19SAndi Kleenperf.data format 2d4897e19SAndi Kleen 3d4897e19SAndi KleenUptodate as of v4.7 4d4897e19SAndi Kleen 5d4897e19SAndi KleenThis document describes the on-disk perf.data format, generated by perf record 6d4897e19SAndi Kleenor perf inject and consumed by the other perf tools. 7d4897e19SAndi Kleen 8d4897e19SAndi KleenOn a high level perf.data contains the events generated by the PMUs, plus metadata. 9d4897e19SAndi Kleen 10d4897e19SAndi KleenAll fields are in native-endian of the machine that generated the perf.data. 11d4897e19SAndi Kleen 12d4897e19SAndi KleenWhen perf is writing to a pipe it uses a special version of the file 13d4897e19SAndi Kleenformat that does not rely on seeking to adjust data offsets. This 146d13491eSDavid Carrillo-Cisnerosformat is described in "Pipe-mode data" section. The pipe data version can be 156d13491eSDavid Carrillo-Cisnerosaugmented with additional events using perf inject. 16d4897e19SAndi Kleen 17d4897e19SAndi KleenThe file starts with a perf_header: 18d4897e19SAndi Kleen 19d4897e19SAndi Kleenstruct perf_header { 20d4897e19SAndi Kleen char magic[8]; /* PERFILE2 */ 21d4897e19SAndi Kleen uint64_t size; /* size of the header */ 22d4897e19SAndi Kleen uint64_t attr_size; /* size of an attribute in attrs */ 23d4897e19SAndi Kleen struct perf_file_section attrs; 24d4897e19SAndi Kleen struct perf_file_section data; 25d4897e19SAndi Kleen struct perf_file_section event_types; 26d4897e19SAndi Kleen uint64_t flags; 27d4897e19SAndi Kleen uint64_t flags1[3]; 28d4897e19SAndi Kleen}; 29d4897e19SAndi Kleen 30d4897e19SAndi KleenThe magic number identifies the perf file and the version. Current perf versions 31d4897e19SAndi Kleenuse PERFILE2. Old perf versions generated a version 1 format (PERFFILE). Version 1 32d4897e19SAndi Kleenis not described here. The magic number also identifies the endian. When the 33d4897e19SAndi Kleenmagic value is 64bit byte swapped compared the file is in non-native 34d4897e19SAndi Kleenendian. 35d4897e19SAndi Kleen 36d4897e19SAndi KleenA perf_file_section contains a pointer to another section of the perf file. 37d4897e19SAndi KleenThe header contains three such pointers: for attributes, data and event types. 38d4897e19SAndi Kleen 39d4897e19SAndi Kleenstruct perf_file_section { 40d4897e19SAndi Kleen uint64_t offset; /* offset from start of file */ 41d4897e19SAndi Kleen uint64_t size; /* size of the section */ 42d4897e19SAndi Kleen}; 43d4897e19SAndi Kleen 44d4897e19SAndi KleenFlags section: 45d4897e19SAndi Kleen 468c23a522SJonas RabensteinFor each of the optional features a perf_file_section it placed after the data 478c23a522SJonas Rabensteinsection if the feature bit is set in the perf_header flags bitset. The 488c23a522SJonas Rabensteinrespective perf_file_section points to the data of the additional header and 498c23a522SJonas Rabensteindefines its size. 50d4897e19SAndi Kleen 51d4897e19SAndi KleenSome headers consist of strings, which are defined like this: 52d4897e19SAndi Kleen 53d4897e19SAndi Kleenstruct perf_header_string { 54d4897e19SAndi Kleen uint32_t len; 55d4897e19SAndi Kleen char string[len]; /* zero terminated */ 56d4897e19SAndi Kleen}; 57d4897e19SAndi Kleen 58d4897e19SAndi KleenSome headers consist of a sequence of strings, which start with a 59d4897e19SAndi Kleen 60d4897e19SAndi Kleenstruct perf_header_string_list { 61d4897e19SAndi Kleen uint32_t nr; 62d4897e19SAndi Kleen struct perf_header_string strings[nr]; /* variable length records */ 63d4897e19SAndi Kleen}; 64d4897e19SAndi Kleen 65d4897e19SAndi KleenThe bits are the flags bits in a 256 bit bitmap starting with 66d4897e19SAndi Kleenflags. These define the valid bits: 67d4897e19SAndi Kleen 68d4897e19SAndi Kleen HEADER_RESERVED = 0, /* always cleared */ 69d4897e19SAndi Kleen HEADER_FIRST_FEATURE = 1, 70d4897e19SAndi Kleen HEADER_TRACING_DATA = 1, 71d4897e19SAndi Kleen 72d4897e19SAndi KleenDescribe me. 73d4897e19SAndi Kleen 74d4897e19SAndi Kleen HEADER_BUILD_ID = 2, 75d4897e19SAndi Kleen 76d4897e19SAndi KleenThe header consists of an sequence of build_id_event. The size of each record 77d4897e19SAndi Kleenis defined by header.size (see perf_event.h). Each event defines a ELF build id 78d4897e19SAndi Kleenfor a executable file name for a pid. An ELF build id is a unique identifier 79d4897e19SAndi Kleenassigned by the linker to an executable. 80d4897e19SAndi Kleen 81d4897e19SAndi Kleenstruct build_id_event { 82d4897e19SAndi Kleen struct perf_event_header header; 83d4897e19SAndi Kleen pid_t pid; 84d4897e19SAndi Kleen uint8_t build_id[24]; 85d4897e19SAndi Kleen char filename[header.size - offsetof(struct build_id_event, filename)]; 86d4897e19SAndi Kleen}; 87d4897e19SAndi Kleen 88d4897e19SAndi Kleen HEADER_HOSTNAME = 3, 89d4897e19SAndi Kleen 90d4897e19SAndi KleenA perf_header_string with the hostname where the data was collected 91d4897e19SAndi Kleen(uname -n) 92d4897e19SAndi Kleen 93d4897e19SAndi Kleen HEADER_OSRELEASE = 4, 94d4897e19SAndi Kleen 95d4897e19SAndi KleenA perf_header_string with the os release where the data was collected 96d4897e19SAndi Kleen(uname -r) 97d4897e19SAndi Kleen 98d4897e19SAndi Kleen HEADER_VERSION = 5, 99d4897e19SAndi Kleen 100d4897e19SAndi KleenA perf_header_string with the perf user tool version where the 101d4897e19SAndi Kleendata was collected. This is the same as the version of the source tree 102d4897e19SAndi Kleenthe perf tool was built from. 103d4897e19SAndi Kleen 104d4897e19SAndi Kleen HEADER_ARCH = 6, 105d4897e19SAndi Kleen 106d4897e19SAndi KleenA perf_header_string with the CPU architecture (uname -m) 107d4897e19SAndi Kleen 108d4897e19SAndi Kleen HEADER_NRCPUS = 7, 109d4897e19SAndi Kleen 110d4897e19SAndi KleenA structure defining the number of CPUs. 111d4897e19SAndi Kleen 112d4897e19SAndi Kleenstruct nr_cpus { 113d4897e19SAndi Kleen uint32_t nr_cpus_available; /* CPUs not yet onlined */ 11418a70574SArnaldo Carvalho de Melo uint32_t nr_cpus_online; 115d4897e19SAndi Kleen}; 116d4897e19SAndi Kleen 117d4897e19SAndi Kleen HEADER_CPUDESC = 8, 118d4897e19SAndi Kleen 119d4897e19SAndi KleenA perf_header_string with description of the CPU. On x86 this is the model name 120d4897e19SAndi Kleenin /proc/cpuinfo 121d4897e19SAndi Kleen 122d4897e19SAndi Kleen HEADER_CPUID = 9, 123d4897e19SAndi Kleen 124d4897e19SAndi KleenA perf_header_string with the exact CPU type. On x86 this is 125d4897e19SAndi Kleenvendor,family,model,stepping. For example: GenuineIntel,6,69,1 126d4897e19SAndi Kleen 127d4897e19SAndi Kleen HEADER_TOTAL_MEM = 10, 128d4897e19SAndi Kleen 1292e9a06ddSVince WeaverAn uint64_t with the total memory in kilobytes. 130d4897e19SAndi Kleen 131d4897e19SAndi Kleen HEADER_CMDLINE = 11, 132d4897e19SAndi Kleen 1337a663c0fSJonas RabensteinA perf_header_string_list with the perf arg-vector used to collect the data. 134d4897e19SAndi Kleen 135d4897e19SAndi Kleen HEADER_EVENT_DESC = 12, 136d4897e19SAndi Kleen 137d4897e19SAndi KleenAnother description of the perf_event_attrs, more detailed than header.attrs 138d4897e19SAndi Kleenincluding IDs and names. See perf_event.h or the man page for a description 139d4897e19SAndi Kleenof a struct perf_event_attr. 140d4897e19SAndi Kleen 141d4897e19SAndi Kleenstruct { 142d4897e19SAndi Kleen uint32_t nr; /* number of events */ 143d4897e19SAndi Kleen uint32_t attr_size; /* size of each perf_event_attr */ 144d4897e19SAndi Kleen struct { 145d4897e19SAndi Kleen struct perf_event_attr attr; /* size of attr_size */ 146d4897e19SAndi Kleen uint32_t nr_ids; 147d4897e19SAndi Kleen struct perf_header_string event_string; 148d4897e19SAndi Kleen uint64_t ids[nr_ids]; 149d4897e19SAndi Kleen } events[nr]; /* Variable length records */ 150d4897e19SAndi Kleen}; 151d4897e19SAndi Kleen 152d4897e19SAndi Kleen HEADER_CPU_TOPOLOGY = 13, 153d4897e19SAndi Kleen 154d4897e19SAndi Kleenstruct { 15536edfb94SArnaldo Carvalho de Melo /* 15636edfb94SArnaldo Carvalho de Melo * First revision of HEADER_CPU_TOPOLOGY 15736edfb94SArnaldo Carvalho de Melo * 15836edfb94SArnaldo Carvalho de Melo * See 'struct perf_header_string_list' definition earlier 15936edfb94SArnaldo Carvalho de Melo * in this file. 16036edfb94SArnaldo Carvalho de Melo */ 16136edfb94SArnaldo Carvalho de Melo 162d4897e19SAndi Kleen struct perf_header_string_list cores; /* Variable length */ 163d4897e19SAndi Kleen struct perf_header_string_list threads; /* Variable length */ 16436edfb94SArnaldo Carvalho de Melo 16536edfb94SArnaldo Carvalho de Melo /* 16636edfb94SArnaldo Carvalho de Melo * Second revision of HEADER_CPU_TOPOLOGY, older tools 16736edfb94SArnaldo Carvalho de Melo * will not consider what comes next 16836edfb94SArnaldo Carvalho de Melo */ 16936edfb94SArnaldo Carvalho de Melo 1700c711138SThomas Richter struct { 1710c711138SThomas Richter uint32_t core_id; 1720c711138SThomas Richter uint32_t socket_id; 1730c711138SThomas Richter } cpus[nr]; /* Variable length records */ 17436edfb94SArnaldo Carvalho de Melo /* 'nr' comes from previously processed HEADER_NRCPUS's nr_cpu_avail */ 17536edfb94SArnaldo Carvalho de Melo 17636edfb94SArnaldo Carvalho de Melo /* 17736edfb94SArnaldo Carvalho de Melo * Third revision of HEADER_CPU_TOPOLOGY, older tools 17836edfb94SArnaldo Carvalho de Melo * will not consider what comes next 17936edfb94SArnaldo Carvalho de Melo */ 18036edfb94SArnaldo Carvalho de Melo 18136edfb94SArnaldo Carvalho de Melo struct perf_header_string_list dies; /* Variable length */ 18236edfb94SArnaldo Carvalho de Melo uint32_t die_id[nr_cpus_avail]; /* from previously processed HEADER_NR_CPUS, VLA */ 183d4897e19SAndi Kleen}; 184d4897e19SAndi Kleen 185d4897e19SAndi KleenExample: 186e05a8997SKan Liang sibling sockets : 0-8 187acae8b36SKan Liang sibling dies : 0-3 188acae8b36SKan Liang sibling dies : 4-7 189d4897e19SAndi Kleen sibling threads : 0-1 190d4897e19SAndi Kleen sibling threads : 2-3 191acae8b36SKan Liang sibling threads : 4-5 192acae8b36SKan Liang sibling threads : 6-7 193d4897e19SAndi Kleen 194d4897e19SAndi Kleen HEADER_NUMA_TOPOLOGY = 14, 195d4897e19SAndi Kleen 196d4897e19SAndi Kleen A list of NUMA node descriptions 197d4897e19SAndi Kleen 198d4897e19SAndi Kleenstruct { 199d4897e19SAndi Kleen uint32_t nr; 200d4897e19SAndi Kleen struct { 201d4897e19SAndi Kleen uint32_t nodenr; 202d4897e19SAndi Kleen uint64_t mem_total; 203d4897e19SAndi Kleen uint64_t mem_free; 204d4897e19SAndi Kleen struct perf_header_string cpus; 205d4897e19SAndi Kleen } nodes[nr]; /* Variable length records */ 206d4897e19SAndi Kleen}; 207d4897e19SAndi Kleen 208d4897e19SAndi Kleen HEADER_BRANCH_STACK = 15, 209d4897e19SAndi Kleen 210d4897e19SAndi KleenNot implemented in perf. 211d4897e19SAndi Kleen 212d4897e19SAndi Kleen HEADER_PMU_MAPPINGS = 16, 213d4897e19SAndi Kleen 214d4897e19SAndi Kleen A list of PMU structures, defining the different PMUs supported by perf. 215d4897e19SAndi Kleen 216d4897e19SAndi Kleenstruct { 217d4897e19SAndi Kleen uint32_t nr; 218d4897e19SAndi Kleen struct pmu { 219d4897e19SAndi Kleen uint32_t pmu_type; 220d4897e19SAndi Kleen struct perf_header_string pmu_name; 221d4897e19SAndi Kleen } [nr]; /* Variable length records */ 222d4897e19SAndi Kleen}; 223d4897e19SAndi Kleen 224d4897e19SAndi Kleen HEADER_GROUP_DESC = 17, 225d4897e19SAndi Kleen 226d4897e19SAndi Kleen Description of counter groups ({...} in perf syntax) 227d4897e19SAndi Kleen 228d4897e19SAndi Kleenstruct { 229d4897e19SAndi Kleen uint32_t nr; 230d4897e19SAndi Kleen struct { 231d4897e19SAndi Kleen struct perf_header_string string; 232d4897e19SAndi Kleen uint32_t leader_idx; 233d4897e19SAndi Kleen uint32_t nr_members; 234d4897e19SAndi Kleen } [nr]; /* Variable length records */ 235d4897e19SAndi Kleen}; 236d4897e19SAndi Kleen 237d4897e19SAndi Kleen HEADER_AUXTRACE = 18, 238d4897e19SAndi Kleen 239d4897e19SAndi KleenDefine additional auxtrace areas in the perf.data. auxtrace is used to store 240d4897e19SAndi Kleenundecoded hardware tracing information, such as Intel Processor Trace data. 241d4897e19SAndi Kleen 242d4897e19SAndi Kleen/** 243d4897e19SAndi Kleen * struct auxtrace_index_entry - indexes a AUX area tracing event within a 244d4897e19SAndi Kleen * perf.data file. 245d4897e19SAndi Kleen * @file_offset: offset within the perf.data file 246d4897e19SAndi Kleen * @sz: size of the event 247d4897e19SAndi Kleen */ 248d4897e19SAndi Kleenstruct auxtrace_index_entry { 249d4897e19SAndi Kleen u64 file_offset; 250d4897e19SAndi Kleen u64 sz; 251d4897e19SAndi Kleen}; 252d4897e19SAndi Kleen 253d4897e19SAndi Kleen#define PERF_AUXTRACE_INDEX_ENTRY_COUNT 256 254d4897e19SAndi Kleen 255d4897e19SAndi Kleen/** 256d4897e19SAndi Kleen * struct auxtrace_index - index of AUX area tracing events within a perf.data 257d4897e19SAndi Kleen * file. 258d4897e19SAndi Kleen * @list: linking a number of arrays of entries 259d4897e19SAndi Kleen * @nr: number of entries 260d4897e19SAndi Kleen * @entries: array of entries 261d4897e19SAndi Kleen */ 262d4897e19SAndi Kleenstruct auxtrace_index { 263d4897e19SAndi Kleen struct list_head list; 264d4897e19SAndi Kleen size_t nr; 265d4897e19SAndi Kleen struct auxtrace_index_entry entries[PERF_AUXTRACE_INDEX_ENTRY_COUNT]; 266d4897e19SAndi Kleen}; 267d4897e19SAndi Kleen 26835c0a81aSAndi Kleen HEADER_STAT = 19, 26935c0a81aSAndi Kleen 27035c0a81aSAndi KleenThis is merely a flag signifying that the data section contains data 27135c0a81aSAndi Kleenrecorded from perf stat record. 27235c0a81aSAndi Kleen 27335c0a81aSAndi Kleen HEADER_CACHE = 20, 27435c0a81aSAndi Kleen 27535c0a81aSAndi KleenDescription of the cache hierarchy. Based on the Linux sysfs format 27635c0a81aSAndi Kleenin /sys/devices/system/cpu/cpu*/cache/ 27735c0a81aSAndi Kleen 27835c0a81aSAndi Kleen u32 version Currently always 1 27935c0a81aSAndi Kleen u32 number_of_cache_levels 28035c0a81aSAndi Kleen 28135c0a81aSAndi Kleenstruct { 28235c0a81aSAndi Kleen u32 level; 28335c0a81aSAndi Kleen u32 line_size; 28435c0a81aSAndi Kleen u32 sets; 28535c0a81aSAndi Kleen u32 ways; 28635c0a81aSAndi Kleen struct perf_header_string type; 28735c0a81aSAndi Kleen struct perf_header_string size; 28835c0a81aSAndi Kleen struct perf_header_string map; 28935c0a81aSAndi Kleen}[number_of_cache_levels]; 29035c0a81aSAndi Kleen 2916011518dSJin Yao HEADER_SAMPLE_TIME = 21, 2926011518dSJin Yao 2936011518dSJin YaoTwo uint64_t for the time of first sample and the time of last sample. 2946011518dSJin Yao 295835fbf12SArnaldo Carvalho de Melo HEADER_SAMPLE_TOPOLOGY = 22, 296835fbf12SArnaldo Carvalho de Melo 297835fbf12SArnaldo Carvalho de MeloPhysical memory map and its node assignments. 298835fbf12SArnaldo Carvalho de Melo 299835fbf12SArnaldo Carvalho de MeloThe format of data in MEM_TOPOLOGY is as follows: 300835fbf12SArnaldo Carvalho de Melo 3013143906cSVince Weaver u64 version; // Currently 1 3023143906cSVince Weaver u64 block_size_bytes; // /sys/devices/system/memory/block_size_bytes 3033143906cSVince Weaver u64 count; // number of nodes 304835fbf12SArnaldo Carvalho de Melo 3053143906cSVince Weaverstruct memory_node { 3063143906cSVince Weaver u64 node_id; // node index 3073143906cSVince Weaver u64 size; // size of bitmap 3083143906cSVince Weaver struct bitmap { 3093143906cSVince Weaver /* size of bitmap again */ 3103143906cSVince Weaver u64 bitmapsize; 3113143906cSVince Weaver /* bitmap of memory indexes that belongs to node */ 3123143906cSVince Weaver /* /sys/devices/system/node/node<NODE>/memory<INDEX> */ 3133143906cSVince Weaver u64 entries[(bitmapsize/64)+1]; 3143143906cSVince Weaver } 3153143906cSVince Weaver}[count]; 316835fbf12SArnaldo Carvalho de Melo 317835fbf12SArnaldo Carvalho de MeloThe MEM_TOPOLOGY can be displayed with following command: 318835fbf12SArnaldo Carvalho de Melo 319835fbf12SArnaldo Carvalho de Melo$ perf report --header-only -I 320835fbf12SArnaldo Carvalho de Melo... 321835fbf12SArnaldo Carvalho de Melo# memory nodes (nr 1, block size 0x8000000): 322835fbf12SArnaldo Carvalho de Melo# 0 [7G]: 0-23,32-69 323835fbf12SArnaldo Carvalho de Melo 324a9de7cfcSArnaldo Carvalho de Melo HEADER_CLOCKID = 23, 325a9de7cfcSArnaldo Carvalho de Melo 326a9de7cfcSArnaldo Carvalho de MeloOne uint64_t for the clockid frequency, specified, for instance, via 'perf 327a9de7cfcSArnaldo Carvalho de Melorecord -k' (see clock_gettime()), to enable timestamps derived metrics 328a9de7cfcSArnaldo Carvalho de Meloconversion into wall clock time on the reporting stage. 329a9de7cfcSArnaldo Carvalho de Melo 3300da6ae94SArnaldo Carvalho de Melo HEADER_DIR_FORMAT = 24, 3310da6ae94SArnaldo Carvalho de Melo 3320da6ae94SArnaldo Carvalho de MeloThe data files layout is described by HEADER_DIR_FORMAT feature. Currently it 3330da6ae94SArnaldo Carvalho de Meloholds only version number (1): 3340da6ae94SArnaldo Carvalho de Melo 3350da6ae94SArnaldo Carvalho de Melo uint64_t version; 3360da6ae94SArnaldo Carvalho de Melo 3370da6ae94SArnaldo Carvalho de MeloThe current version holds only version value (1) means that data files: 3380da6ae94SArnaldo Carvalho de Melo 3390da6ae94SArnaldo Carvalho de Melo- Follow the 'data.*' name format. 3400da6ae94SArnaldo Carvalho de Melo 3410da6ae94SArnaldo Carvalho de Melo- Contain raw events data in standard perf format as read from kernel (and need 3420da6ae94SArnaldo Carvalho de Melo to be sorted) 3430da6ae94SArnaldo Carvalho de Melo 3440da6ae94SArnaldo Carvalho de MeloFuture versions are expected to describe different data files layout according 3450da6ae94SArnaldo Carvalho de Meloto special needs. 3460da6ae94SArnaldo Carvalho de Melo 3478e21be4fSSong Liu HEADER_BPF_PROG_INFO = 25, 3488e21be4fSSong Liu 3498e21be4fSSong Liustruct bpf_prog_info_linear, which contains detailed information about 3508e21be4fSSong Liua BPF program, including type, id, tag, jited/xlated instructions, etc. 3518e21be4fSSong Liu 3528e21be4fSSong Liu HEADER_BPF_BTF = 26, 3538e21be4fSSong Liu 3548e21be4fSSong LiuContains BPF Type Format (BTF). For more information about BTF, please 3558e21be4fSSong Liurefer to Documentation/bpf/btf.rst. 3568e21be4fSSong Liu 3578e21be4fSSong Liustruct { 3588e21be4fSSong Liu u32 id; 3598e21be4fSSong Liu u32 data_size; 3608e21be4fSSong Liu char data[]; 3618e21be4fSSong Liu}; 3628e21be4fSSong Liu 36342e1fd80SAlexey Budankov HEADER_COMPRESSED = 27, 36442e1fd80SAlexey Budankov 36542e1fd80SAlexey Budankovstruct { 36642e1fd80SAlexey Budankov u32 version; 36742e1fd80SAlexey Budankov u32 type; 36842e1fd80SAlexey Budankov u32 level; 36942e1fd80SAlexey Budankov u32 ratio; 37042e1fd80SAlexey Budankov u32 mmap_len; 37142e1fd80SAlexey Budankov}; 37242e1fd80SAlexey Budankov 37342e1fd80SAlexey BudankovIndicates that trace contains records of PERF_RECORD_COMPRESSED type 37442e1fd80SAlexey Budankovthat have perf_events records in compressed form. 37542e1fd80SAlexey Budankov 3766f91ea28SKan Liang HEADER_CPU_PMU_CAPS = 28, 3776f91ea28SKan Liang 3786f91ea28SKan Liang A list of cpu PMU capabilities. The format of data is as below. 3796f91ea28SKan Liang 3806f91ea28SKan Liangstruct { 3816f91ea28SKan Liang u32 nr_cpu_pmu_caps; 3826f91ea28SKan Liang { 3836f91ea28SKan Liang char name[]; 3846f91ea28SKan Liang char value[]; 3856f91ea28SKan Liang } [nr_cpu_pmu_caps] 3866f91ea28SKan Liang}; 3876f91ea28SKan Liang 3886f91ea28SKan Liang 3896f91ea28SKan LiangExample: 3906f91ea28SKan Liang cpu pmu capabilities: branches=32, max_precise=3, pmu_name=icelake 3916f91ea28SKan Liang 392d1e325cfSJiri Olsa HEADER_CLOCK_DATA = 29, 393d1e325cfSJiri Olsa 394d1e325cfSJiri Olsa Contains clock id and its reference time together with wall clock 395d1e325cfSJiri Olsa time taken at the 'same time', both values are in nanoseconds. 396d1e325cfSJiri Olsa The format of data is as below. 397d1e325cfSJiri Olsa 398d1e325cfSJiri Olsastruct { 399d1e325cfSJiri Olsa u32 version; /* version = 1 */ 400d1e325cfSJiri Olsa u32 clockid; 401d1e325cfSJiri Olsa u64 wall_clock_ns; 402d1e325cfSJiri Olsa u64 clockid_time_ns; 403d1e325cfSJiri Olsa}; 404d1e325cfSJiri Olsa 405*f7d74ce3SJin Yao HEADER_HYBRID_TOPOLOGY = 30, 406*f7d74ce3SJin Yao 407*f7d74ce3SJin YaoIndicate the hybrid CPUs. The format of data is as below. 408*f7d74ce3SJin Yao 409*f7d74ce3SJin Yaostruct { 410*f7d74ce3SJin Yao u32 nr; 411*f7d74ce3SJin Yao struct { 412*f7d74ce3SJin Yao char pmu_name[]; 413*f7d74ce3SJin Yao char cpus[]; 414*f7d74ce3SJin Yao } [nr]; /* Variable length records */ 415*f7d74ce3SJin Yao}; 416*f7d74ce3SJin Yao 417*f7d74ce3SJin YaoExample: 418*f7d74ce3SJin Yao hybrid cpu system: 419*f7d74ce3SJin Yao cpu_core cpu list : 0-15 420*f7d74ce3SJin Yao cpu_atom cpu list : 16-23 421*f7d74ce3SJin Yao 422d4897e19SAndi Kleen other bits are reserved and should ignored for now 423d4897e19SAndi Kleen HEADER_FEAT_BITS = 256, 424d4897e19SAndi Kleen 425d4897e19SAndi KleenAttributes 426d4897e19SAndi Kleen 427d4897e19SAndi KleenThis is an array of perf_event_attrs, each attr_size bytes long, which defines 428d4897e19SAndi Kleeneach event collected. See perf_event.h or the man page for a detailed 429d4897e19SAndi Kleendescription. 430d4897e19SAndi Kleen 431d4897e19SAndi KleenData 432d4897e19SAndi Kleen 433d4897e19SAndi KleenThis section is the bulk of the file. It consist of a stream of perf_events 434d4897e19SAndi Kleendescribing events. This matches the format generated by the kernel. 435d4897e19SAndi KleenSee perf_event.h or the manpage for a detailed description. 436d4897e19SAndi Kleen 437d4897e19SAndi KleenSome notes on parsing: 438d4897e19SAndi Kleen 439d4897e19SAndi KleenOrdering 440d4897e19SAndi Kleen 441d4897e19SAndi KleenThe events are not necessarily in time stamp order, as they can be 442d4897e19SAndi Kleencollected in parallel on different CPUs. If the events should be 443d4897e19SAndi Kleenprocessed in time order they need to be sorted first. It is possible 444d4897e19SAndi Kleento only do a partial sort using the FINISHED_ROUND event header (see 445d4897e19SAndi Kleenbelow). perf record guarantees that there is no reordering over a 446d4897e19SAndi KleenFINISHED_ROUND. 447d4897e19SAndi Kleen 448d4897e19SAndi KleenID vs IDENTIFIER 449d4897e19SAndi Kleen 450d4897e19SAndi KleenWhen the event stream contains multiple events each event is identified 451d4897e19SAndi Kleenby an ID. This can be either through the PERF_SAMPLE_ID or the 452d4897e19SAndi KleenPERF_SAMPLE_IDENTIFIER header. The PERF_SAMPLE_IDENTIFIER header is 453d4897e19SAndi Kleenat a fixed offset from the event header, which allows reliable 4541291927aSKim Phillipsparsing of the header. Relying on ID may be ambiguous. 455d4897e19SAndi KleenIDENTIFIER is only supported by newer Linux kernels. 456d4897e19SAndi Kleen 457d4897e19SAndi KleenPerf record specific events: 458d4897e19SAndi Kleen 459d4897e19SAndi KleenIn addition to the kernel generated event types perf record adds its 460d4897e19SAndi Kleenown event types (in addition it also synthesizes some kernel events, 461d4897e19SAndi Kleenfor example MMAP events) 462d4897e19SAndi Kleen 463d4897e19SAndi Kleen PERF_RECORD_USER_TYPE_START = 64, 464d4897e19SAndi Kleen PERF_RECORD_HEADER_ATTR = 64, 465d4897e19SAndi Kleen 466d4897e19SAndi Kleenstruct attr_event { 467d4897e19SAndi Kleen struct perf_event_header header; 468d4897e19SAndi Kleen struct perf_event_attr attr; 469d4897e19SAndi Kleen uint64_t id[]; 470d4897e19SAndi Kleen}; 471d4897e19SAndi Kleen 4721291927aSKim Phillips PERF_RECORD_HEADER_EVENT_TYPE = 65, /* deprecated */ 473d4897e19SAndi Kleen 474d4897e19SAndi Kleen#define MAX_EVENT_NAME 64 475d4897e19SAndi Kleen 476d4897e19SAndi Kleenstruct perf_trace_event_type { 477d4897e19SAndi Kleen uint64_t event_id; 478d4897e19SAndi Kleen char name[MAX_EVENT_NAME]; 479d4897e19SAndi Kleen}; 480d4897e19SAndi Kleen 481d4897e19SAndi Kleenstruct event_type_event { 482d4897e19SAndi Kleen struct perf_event_header header; 483d4897e19SAndi Kleen struct perf_trace_event_type event_type; 484d4897e19SAndi Kleen}; 485d4897e19SAndi Kleen 486d4897e19SAndi Kleen 487d4897e19SAndi Kleen PERF_RECORD_HEADER_TRACING_DATA = 66, 488d4897e19SAndi Kleen 489d4897e19SAndi KleenDescribe me 490d4897e19SAndi Kleen 491d4897e19SAndi Kleenstruct tracing_data_event { 492d4897e19SAndi Kleen struct perf_event_header header; 493d4897e19SAndi Kleen uint32_t size; 494d4897e19SAndi Kleen}; 495d4897e19SAndi Kleen 496d4897e19SAndi Kleen PERF_RECORD_HEADER_BUILD_ID = 67, 497d4897e19SAndi Kleen 498d4897e19SAndi KleenDefine a ELF build ID for a referenced executable. 499d4897e19SAndi Kleen 500d4897e19SAndi Kleen struct build_id_event; /* See above */ 501d4897e19SAndi Kleen 502d4897e19SAndi Kleen PERF_RECORD_FINISHED_ROUND = 68, 503d4897e19SAndi Kleen 504d4897e19SAndi KleenNo event reordering over this header. No payload. 505d4897e19SAndi Kleen 506d4897e19SAndi Kleen PERF_RECORD_ID_INDEX = 69, 507d4897e19SAndi Kleen 508d4897e19SAndi KleenMap event ids to CPUs and TIDs. 509d4897e19SAndi Kleen 510d4897e19SAndi Kleenstruct id_index_entry { 511d4897e19SAndi Kleen uint64_t id; 512d4897e19SAndi Kleen uint64_t idx; 513d4897e19SAndi Kleen uint64_t cpu; 514d4897e19SAndi Kleen uint64_t tid; 515d4897e19SAndi Kleen}; 516d4897e19SAndi Kleen 517d4897e19SAndi Kleenstruct id_index_event { 518d4897e19SAndi Kleen struct perf_event_header header; 519d4897e19SAndi Kleen uint64_t nr; 520d4897e19SAndi Kleen struct id_index_entry entries[nr]; 521d4897e19SAndi Kleen}; 522d4897e19SAndi Kleen 523d4897e19SAndi Kleen PERF_RECORD_AUXTRACE_INFO = 70, 524d4897e19SAndi Kleen 525d4897e19SAndi KleenAuxtrace type specific information. Describe me 526d4897e19SAndi Kleen 527d4897e19SAndi Kleenstruct auxtrace_info_event { 528d4897e19SAndi Kleen struct perf_event_header header; 529d4897e19SAndi Kleen uint32_t type; 530d4897e19SAndi Kleen uint32_t reserved__; /* For alignment */ 531d4897e19SAndi Kleen uint64_t priv[]; 532d4897e19SAndi Kleen}; 533d4897e19SAndi Kleen 534d4897e19SAndi Kleen PERF_RECORD_AUXTRACE = 71, 535d4897e19SAndi Kleen 536d4897e19SAndi KleenDefines auxtrace data. Followed by the actual data. The contents of 537d4897e19SAndi Kleenthe auxtrace data is dependent on the event and the CPU. For example 538d4897e19SAndi Kleenfor Intel Processor Trace it contains Processor Trace data generated 539d4897e19SAndi Kleenby the CPU. 540d4897e19SAndi Kleen 541d4897e19SAndi Kleenstruct auxtrace_event { 542d4897e19SAndi Kleen struct perf_event_header header; 543d4897e19SAndi Kleen uint64_t size; 544d4897e19SAndi Kleen uint64_t offset; 545d4897e19SAndi Kleen uint64_t reference; 546d4897e19SAndi Kleen uint32_t idx; 547d4897e19SAndi Kleen uint32_t tid; 548d4897e19SAndi Kleen uint32_t cpu; 549d4897e19SAndi Kleen uint32_t reserved__; /* For alignment */ 550d4897e19SAndi Kleen}; 551d4897e19SAndi Kleen 552d4897e19SAndi Kleenstruct aux_event { 553d4897e19SAndi Kleen struct perf_event_header header; 554d4897e19SAndi Kleen uint64_t aux_offset; 555d4897e19SAndi Kleen uint64_t aux_size; 556d4897e19SAndi Kleen uint64_t flags; 557d4897e19SAndi Kleen}; 558d4897e19SAndi Kleen 559d4897e19SAndi Kleen PERF_RECORD_AUXTRACE_ERROR = 72, 560d4897e19SAndi Kleen 561d4897e19SAndi KleenDescribes an error in hardware tracing 562d4897e19SAndi Kleen 563d4897e19SAndi Kleenenum auxtrace_error_type { 564d4897e19SAndi Kleen PERF_AUXTRACE_ERROR_ITRACE = 1, 565d4897e19SAndi Kleen PERF_AUXTRACE_ERROR_MAX 566d4897e19SAndi Kleen}; 567d4897e19SAndi Kleen 568d4897e19SAndi Kleen#define MAX_AUXTRACE_ERROR_MSG 64 569d4897e19SAndi Kleen 570d4897e19SAndi Kleenstruct auxtrace_error_event { 571d4897e19SAndi Kleen struct perf_event_header header; 572d4897e19SAndi Kleen uint32_t type; 573d4897e19SAndi Kleen uint32_t code; 574d4897e19SAndi Kleen uint32_t cpu; 575d4897e19SAndi Kleen uint32_t pid; 576d4897e19SAndi Kleen uint32_t tid; 577d4897e19SAndi Kleen uint32_t reserved__; /* For alignment */ 578d4897e19SAndi Kleen uint64_t ip; 579d4897e19SAndi Kleen char msg[MAX_AUXTRACE_ERROR_MSG]; 580d4897e19SAndi Kleen}; 581d4897e19SAndi Kleen 582e9def1b2SDavid Carrillo-Cisneros PERF_RECORD_HEADER_FEATURE = 80, 583e9def1b2SDavid Carrillo-Cisneros 584e9def1b2SDavid Carrillo-CisnerosDescribes a header feature. These are records used in pipe-mode that 585e9def1b2SDavid Carrillo-Cisneroscontain information that otherwise would be in perf.data file's header. 586e9def1b2SDavid Carrillo-Cisneros 58742e1fd80SAlexey Budankov PERF_RECORD_COMPRESSED = 81, 58842e1fd80SAlexey Budankov 58942e1fd80SAlexey Budankovstruct compressed_event { 59042e1fd80SAlexey Budankov struct perf_event_header header; 59142e1fd80SAlexey Budankov char data[]; 59242e1fd80SAlexey Budankov}; 59342e1fd80SAlexey Budankov 59442e1fd80SAlexey BudankovThe header is followed by compressed data frame that can be decompressed 59542e1fd80SAlexey Budankovinto array of perf trace records. The size of the entire compressed event 59642e1fd80SAlexey Budankovrecord including the header is limited by the max value of header.size. 59742e1fd80SAlexey Budankov 598d4897e19SAndi KleenEvent types 599d4897e19SAndi Kleen 600d4897e19SAndi KleenDefine the event attributes with their IDs. 601d4897e19SAndi Kleen 602d4897e19SAndi KleenAn array bound by the perf_file_section size. 603d4897e19SAndi Kleen 604d4897e19SAndi Kleen struct { 605d4897e19SAndi Kleen struct perf_event_attr attr; /* Size defined by header.attr_size */ 606d4897e19SAndi Kleen struct perf_file_section ids; 607d4897e19SAndi Kleen } 608d4897e19SAndi Kleen 609d4897e19SAndi Kleenids points to a array of uint64_t defining the ids for event attr attr. 610d4897e19SAndi Kleen 6116d13491eSDavid Carrillo-CisnerosPipe-mode data 6126d13491eSDavid Carrillo-Cisneros 6136d13491eSDavid Carrillo-CisnerosPipe-mode avoid seeks in the file by removing the perf_file_section and flags 6146d13491eSDavid Carrillo-Cisnerosfrom the struct perf_header. The trimmed header is: 6156d13491eSDavid Carrillo-Cisneros 6166d13491eSDavid Carrillo-Cisnerosstruct perf_pipe_file_header { 6176d13491eSDavid Carrillo-Cisneros u64 magic; 6186d13491eSDavid Carrillo-Cisneros u64 size; 6196d13491eSDavid Carrillo-Cisneros}; 6206d13491eSDavid Carrillo-Cisneros 6216d13491eSDavid Carrillo-CisnerosThe information about attrs, data, and event_types is instead in the 622e9def1b2SDavid Carrillo-Cisnerossynthesized events PERF_RECORD_ATTR, PERF_RECORD_HEADER_TRACING_DATA, 623e9def1b2SDavid Carrillo-CisnerosPERF_RECORD_HEADER_EVENT_TYPE, and PERF_RECORD_HEADER_FEATURE 624e9def1b2SDavid Carrillo-Cisnerosthat are generated by perf record in pipe-mode. 6256d13491eSDavid Carrillo-Cisneros 6266d13491eSDavid Carrillo-Cisneros 627d4897e19SAndi KleenReferences: 628d4897e19SAndi Kleen 629d4897e19SAndi Kleeninclude/uapi/linux/perf_event.h 630d4897e19SAndi Kleen 631d4897e19SAndi KleenThis is the canonical description of the kernel generated perf_events 632d4897e19SAndi Kleenand the perf_event_attrs. 633d4897e19SAndi Kleen 634d4897e19SAndi Kleenperf_events manpage 635d4897e19SAndi Kleen 636d4897e19SAndi KleenA manpage describing perf_event and perf_event_attr is here: 637d4897e19SAndi Kleenhttp://web.eece.maine.edu/~vweaver/projects/perf_events/programming.html 638d4897e19SAndi KleenThis tends to be slightly behind the kernel include, but has better 639d4897e19SAndi Kleendescriptions. An (typically older) version of the man page may be 640d4897e19SAndi Kleenincluded with the standard Linux man pages, available with "man 641d4897e19SAndi Kleenperf_events" 642d4897e19SAndi Kleen 643d4897e19SAndi Kleenpmu-tools 644d4897e19SAndi Kleen 645d4897e19SAndi Kleenhttps://github.com/andikleen/pmu-tools/tree/master/parser 646d4897e19SAndi Kleen 647d4897e19SAndi KleenA definition of the perf.data format in python "construct" format is available 648d4897e19SAndi Kleenin pmu-tools parser. This allows to read perf.data from python and dump it. 649d4897e19SAndi Kleen 650d4897e19SAndi Kleenquipper 651d4897e19SAndi Kleen 652d4897e19SAndi KleenThe quipper C++ parser is available at 6532427b432SStephane Eranianhttp://github.com/google/perf_data_converter/tree/master/src/quipper 6542acad195SSimon Que 655