diff options
Diffstat (limited to 'tools/perf/Documentation/perf.data-file-format.txt')
| -rw-r--r-- | tools/perf/Documentation/perf.data-file-format.txt | 283 |
1 files changed, 264 insertions, 19 deletions
diff --git a/tools/perf/Documentation/perf.data-file-format.txt b/tools/perf/Documentation/perf.data-file-format.txt index de8b39dda7b8..c9d4dec65344 100644 --- a/tools/perf/Documentation/perf.data-file-format.txt +++ b/tools/perf/Documentation/perf.data-file-format.txt @@ -43,11 +43,10 @@ struct perf_file_section { Flags section: -The header is followed by different optional headers, described by the bits set -in flags. Only headers for which the bit is set are included. Each header -consists of a perf_file_section located after the initial header. -The respective perf_file_section points to the data of the additional -header and defines its size. +For each of the optional features a perf_file_section is placed after the data +section if the feature bit is set in the perf_header flags bitset. The +respective perf_file_section points to the data of the additional header and +defines its size. Some headers consist of strings, which are defined like this: @@ -111,8 +110,8 @@ A perf_header_string with the CPU architecture (uname -m) A structure defining the number of CPUs. struct nr_cpus { - uint32_t nr_cpus_online; uint32_t nr_cpus_available; /* CPUs not yet onlined */ + uint32_t nr_cpus_online; }; HEADER_CPUDESC = 8, @@ -127,11 +126,11 @@ vendor,family,model,stepping. For example: GenuineIntel,6,69,1 HEADER_TOTAL_MEM = 10, -An uint64_t with the total memory in bytes. +An uint64_t with the total memory in kilobytes. HEADER_CMDLINE = 11, -A perf_header_string with the perf command line used to collect the data. +A perf_header_string_list with the perf arg-vector used to collect the data. HEADER_EVENT_DESC = 12, @@ -152,17 +151,45 @@ struct { HEADER_CPU_TOPOLOGY = 13, -String lists defining the core and CPU threads topology. - struct { + /* + * First revision of HEADER_CPU_TOPOLOGY + * + * See 'struct perf_header_string_list' definition earlier + * in this file. + */ + struct perf_header_string_list cores; /* Variable length */ struct perf_header_string_list threads; /* Variable length */ + + /* + * Second revision of HEADER_CPU_TOPOLOGY, older tools + * will not consider what comes next + */ + + struct { + uint32_t core_id; + uint32_t socket_id; + } cpus[nr]; /* Variable length records */ + /* 'nr' comes from previously processed HEADER_NRCPUS's nr_cpu_avail */ + + /* + * Third revision of HEADER_CPU_TOPOLOGY, older tools + * will not consider what comes next + */ + + struct perf_header_string_list dies; /* Variable length */ + uint32_t die_id[nr_cpus_avail]; /* from previously processed HEADER_NR_CPUS, VLA */ }; Example: - sibling cores : 0-3 + sibling sockets : 0-8 + sibling dies : 0-3 + sibling dies : 4-7 sibling threads : 0-1 sibling threads : 2-3 + sibling threads : 4-5 + sibling threads : 6-7 HEADER_NUMA_TOPOLOGY = 14, @@ -238,6 +265,188 @@ struct auxtrace_index { struct auxtrace_index_entry entries[PERF_AUXTRACE_INDEX_ENTRY_COUNT]; }; + HEADER_STAT = 19, + +This is merely a flag signifying that the data section contains data +recorded from perf stat record. + + HEADER_CACHE = 20, + +Description of the cache hierarchy. Based on the Linux sysfs format +in /sys/devices/system/cpu/cpu*/cache/ + + u32 version Currently always 1 + u32 number_of_cache_levels + +struct { + u32 level; + u32 line_size; + u32 sets; + u32 ways; + struct perf_header_string type; + struct perf_header_string size; + struct perf_header_string map; +}[number_of_cache_levels]; + + HEADER_SAMPLE_TIME = 21, + +Two uint64_t for the time of first sample and the time of last sample. + + HEADER_SAMPLE_TOPOLOGY = 22, + +Physical memory map and its node assignments. + +The format of data in MEM_TOPOLOGY is as follows: + + u64 version; // Currently 1 + u64 block_size_bytes; // /sys/devices/system/memory/block_size_bytes + u64 count; // number of nodes + +struct memory_node { + u64 node_id; // node index + u64 size; // size of bitmap + struct bitmap { + /* size of bitmap again */ + u64 bitmapsize; + /* bitmap of memory indexes that belongs to node */ + /* /sys/devices/system/node/node<NODE>/memory<INDEX> */ + u64 entries[(bitmapsize/64)+1]; + } +}[count]; + +The MEM_TOPOLOGY can be displayed with following command: + +$ perf report --header-only -I +... +# memory nodes (nr 1, block size 0x8000000): +# 0 [7G]: 0-23,32-69 + + HEADER_CLOCKID = 23, + +One uint64_t for the clockid frequency, specified, for instance, via 'perf +record -k' (see clock_gettime()), to enable timestamps derived metrics +conversion into wall clock time on the reporting stage. + + HEADER_DIR_FORMAT = 24, + +The data files layout is described by HEADER_DIR_FORMAT feature. Currently it +holds only version number (1): + + uint64_t version; + +The current version holds only version value (1) means that data files: + +- Follow the 'data.*' name format. + +- Contain raw events data in standard perf format as read from kernel (and need + to be sorted) + +Future versions are expected to describe different data files layout according +to special needs. + + HEADER_BPF_PROG_INFO = 25, + +struct perf_bpil, which contains detailed information about +a BPF program, including type, id, tag, jited/xlated instructions, etc. +The format of data in HEADER_BPF_PROG_INFO is as follows: + u32 count + + struct perf_bpil { + u32 info_len; /* size of struct bpf_prog_info, when the tool is compiled */ + u32 data_len; /* total bytes allocated for data, round up to 8 bytes */ + u64 arrays; /* which arrays are included in data */ + struct bpf_prog_info info; + u8 data[]; + }[count]; + + HEADER_BPF_BTF = 26, + +Contains BPF Type Format (BTF). For more information about BTF, please +refer to Documentation/bpf/btf.rst. + +struct { + u32 id; + u32 data_size; + char data[]; +}; + + HEADER_COMPRESSED = 27, + +struct { + u32 version; + u32 type; + u32 level; + u32 ratio; + u32 mmap_len; +}; + +Indicates that trace contains records of PERF_RECORD_COMPRESSED2 type +that have perf_events records in compressed form. + + HEADER_CPU_PMU_CAPS = 28, + + A list of cpu PMU capabilities. The format of data is as below. + +struct { + u32 nr_cpu_pmu_caps; + { + char name[]; + char value[]; + } [nr_cpu_pmu_caps] +}; + + +Example: + cpu pmu capabilities: branches=32, max_precise=3, pmu_name=icelake + + HEADER_CLOCK_DATA = 29, + + Contains clock id and its reference time together with wall clock + time taken at the 'same time', both values are in nanoseconds. + The format of data is as below. + +struct { + u32 version; /* version = 1 */ + u32 clockid; + u64 wall_clock_ns; + u64 clockid_time_ns; +}; + + HEADER_HYBRID_TOPOLOGY = 30, + +Indicate the hybrid CPUs. The format of data is as below. + +struct { + u32 nr; + struct { + char pmu_name[]; + char cpus[]; + } [nr]; /* Variable length records */ +}; + +Example: + hybrid cpu system: + cpu_core cpu list : 0-15 + cpu_atom cpu list : 16-23 + + HEADER_PMU_CAPS = 31, + + List of pmu capabilities (except cpu pmu which is already + covered by HEADER_CPU_PMU_CAPS). Note that hybrid cpu pmu + capabilities are also stored here. + +struct { + u32 nr_pmu; + struct { + u32 nr_caps; + { + char name[]; + char value[]; + } [nr_caps]; + char pmu_name[]; + } [nr_pmu]; +}; + other bits are reserved and should ignored for now HEADER_FEAT_BITS = 256, @@ -398,6 +607,46 @@ struct auxtrace_error_event { char msg[MAX_AUXTRACE_ERROR_MSG]; }; + PERF_RECORD_HEADER_FEATURE = 80, + +Describes a header feature. These are records used in pipe-mode that +contain information that otherwise would be in perf.data file's header. + + PERF_RECORD_COMPRESSED = 81, /* deprecated */ + +The header is followed by compressed data frame that can be decompressed +into array of perf trace records. The size of the entire compressed event +record including the header is limited by the max value of header.size. + +It is deprecated and new files should use PERF_RECORD_COMPRESSED2 to gurantee +8-byte alignment. + +struct compressed_event { + struct perf_event_header header; + char data[]; +}; + + PERF_RECORD_FINISHED_INIT = 82, + +Marks the end of records for the system, pre-existing threads in system wide +sessions, etc. Those are the ones prefixed PERF_RECORD_USER_*. + +This is used, for instance, to 'perf inject' events after init and before +regular events, those emitted by the kernel, to support combining guest and +host records. + + PERF_RECORD_COMPRESSED2 = 83, + +8-byte aligned version of `PERF_RECORD_COMPRESSED`. `header.size` indicates the +total record size, including padding for 8-byte alignment, and `data_size` +specifies the actual size of the compressed data. + +struct perf_record_compressed2 { + struct perf_event_header header; + __u64 data_size; + char data[]; +}; + Event types Define the event attributes with their IDs. @@ -422,8 +671,9 @@ struct perf_pipe_file_header { }; The information about attrs, data, and event_types is instead in the -synthesized events PERF_RECORD_ATTR, PERF_RECORD_HEADER_TRACING_DATA and -PERF_RECORD_HEADER_EVENT_TYPE that are generated by perf record in pipe-mode. +synthesized events PERF_RECORD_ATTR, PERF_RECORD_HEADER_TRACING_DATA, +PERF_RECORD_HEADER_EVENT_TYPE, and PERF_RECORD_HEADER_FEATURE +that are generated by perf record in pipe-mode. References: @@ -452,10 +702,5 @@ in pmu-tools parser. This allows to read perf.data from python and dump it. quipper The quipper C++ parser is available at -https://chromium.googlesource.com/chromiumos/platform2 - -It is under the chromiumos-wide-profiling/ subdirectory. This library can -convert a perf data file to a protobuf and vice versa. +http://github.com/google/perf_data_converter/tree/master/src/quipper -Unfortunately this parser tends to be many versions behind and may not be able -to parse data files generated by recent perf. |