1pahole(1) dwarves pahole(1)
2
3
4
6 pahole - Shows, manipulates data structure layout and pretty prints raw
7 data.
8
10 pahole [options] files
11
13 pahole shows data structure layouts encoded in debugging information
14 formats, DWARF, CTF and BTF being supported.
15
16 This is useful for, among other things: optimizing important data
17 structures by reducing its size, figuring out what is the field sitting
18 at an offset from the start of a data structure, investigating ABI
19 changes and more generally understanding a new codebase you have to
20 work with.
21
22 It also uses these structure layouts to pretty print data feed to its
23 standard input, e.g.:
24
25 $ pahole --header elf64_hdr --prettify /lib/modules/5.8.0-rc6+/build/vmlinux
26 {
27 .e_ident = { 127, 69, 76, 70, 2, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0 },
28 .e_type = 2,
29 .e_machine = 62,
30 .e_version = 1,
31 .e_entry = 16777216,
32 .e_phoff = 64,
33 .e_shoff = 604653784,
34 .e_flags = 0,
35 .e_ehsize = 64,
36 .e_phentsize = 56,
37 .e_phnum = 5,
38 .e_shentsize = 64,
39 .e_shnum = 80,
40 .e_shstrndx = 79,
41 },
42 $
43
44 See the PRETTY PRINTING section for further examples and documentation.
45
46 The files must have associated debugging information. This information
47 may be inside the file itself, in ELF sections, or in another file.
48
49 One way to have this information is to specify the -g option to the
50 compiler when building it. When this is done the information will be
51 stored in an ELF section. For the DWARF debugging information format
52 this, adds, among others, the .debug_info ELF section. For CTF it is
53 found in just one ELF section, .SUNW_ctf. BTF comes in at least the
54 .BTF ELF section, and may come also with the .BTF.ext ELF section.
55
56 The debuginfo packages available in most Linux distributions are also
57 supported by pahole, where the debugging information is available in a
58 separate file.
59
60 By default, pahole shows the layout of all named structs in the files
61 specified.
62
63 If no files are specified, then it will look if the /sys/kernel/btf/vm‐
64 linux is present, using the BTF information present in it about the
65 running kernel, i.e. this works:
66
67 $ pahole list_head
68 struct list_head {
69 struct list_head * next; /* 0 8 */
70 struct list_head * prev; /* 8 8 */
71
72 /* size: 16, cachelines: 1, members: 2 */
73 /* last cacheline: 16 bytes */
74 };
75 $
76
77 If BTF is not present and no file is passed, then a vmlinux that
78 matches the build-id for the running kernel will be looked up in the
79 usual places, including where the kernel debuginfo packages put it,
80 looking for DWARF info instead.
81
82 See the EXAMPLES section for more usage suggestions.
83
84 It also pretty prints whatever is fed to its standard input, according
85 to the type specified, see the EXAMPLE session.
86
87 Use --count to state how many records should be pretty printed.
88
89
91 pahole supports the following options.
92
93
94 -C, --class_name=CLASS_NAMES
95 Show just these classes. This can be a comma separated list of
96 class names or file URLs (e.g.: file://class_list.txt)
97
98
99 -c, --cacheline_size=SIZE
100 Set cacheline size to SIZE bytes.
101
102
103 Sort the output by type name, maybe this will grow to allow sorting by
104 other
105 criteria.
106
107 This is mostly needed so that pretty printing from BTF and DWARF
108 can be comparable when using using multiple threads to load
109 DWARF data, when the order that the types in the compile units
110 is processed is not deterministic.
111
112
113 --count=COUNT
114 Pretty print the first COUNT records from input.
115
116
117 --skip=COUNT
118 Skip COUNT input records.
119
120
121 -E, --expand_types
122 Expand class members. Useful to find in what member of inner
123 structs where an offset from the beginning of a struct is.
124
125
126 -F, --format_path
127 Allows specifying a list of debugging formats to try, in order.
128 Right now this includes "ctf" and "dwarf". The default format
129 path used is equivalent to "-F dwarf,ctf".
130
131
132 --hashbits=BITS
133 Allows specifying the number of bits for the debugging format
134 loader to use. The only one affected so far is the "dwarf" one,
135 its default now is 15, the maximum for it is now 21 bits. Tweak
136 it to see if it improves performance as the kernel evolves and
137 more types and functions have to be loaded.
138
139
140 --hex Print offsets and sizes in hexadecimal.
141
142
143 -r, --rel_offset
144 Show relative offsets of members in inner structs.
145
146
147 -p, --expand_pointers
148 Expand class pointer members.
149
150
151 -R, --reorganize
152 Reorganize struct, demoting and combining bitfields, moving mem‐
153 bers to remove alignment holes and padding.
154
155
156 -S, --show_reorg_steps
157 Show the struct layout at each reorganization step.
158
159
160 -i, --contains=CLASS_NAME
161 Show classes that contains CLASS_NAME.
162
163
164 -a, --anon_include
165 Include anonymous classes.
166
167
168 -A, --nested_anon_include
169 Include nested (inside other structs) anonymous classes.
170
171
172 -B, --bit_holes=NR_HOLES
173 Show only structs at least NR_HOLES bit holes.
174
175
176 -d, --recursive
177 Recursive mode, affects several other flags.
178
179
180 -D, --decl_exclude=PREFIX
181 exclude classes declared in files with PREFIX.
182
183
184 -f, --find_pointers_to=CLASS_NAME
185 Find pointers to CLASS_NAME.
186
187
188 -H, --holes=NR_HOLES
189 Show only structs with at least NR_HOLES holes.
190
191
192 -I, --show_decl_info
193 Show the file and line number where the tags were defined, if
194 available in the debugging information.
195
196
197 --skip_encoding_btf_vars
198 Do not encode VARs in BTF.
199
200
201 -j, --jobs=N
202 Run N jobs in parallel. Defaults to number of online processors
203 + 10% (like the 'ninja' build system) if no argument is speci‐
204 fied.
205
206
207 -J, --btf_encode
208 Encode BTF information from DWARF, used in the Linux kernel
209 build process when CONFIG_DEBUG_INFO_BTF=y is present, intro‐
210 duced in Linux v5.2. Used to implement features such as BPF CO-
211 RE (Compile Once - Run Everywhere).
212
213 See https://nakryiko.com/posts/bpf-portability-and-co-re/.
214
215
216 --btf_encode_detached=FILENAME
217 Same thing as -J/--btf_encode, but storing the raw BTF info into
218 a separate file.
219
220
221 --btf_encode_force
222 Ignore those symbols found invalid when encoding BTF.
223
224
225 --btf_base=PATH
226 Path to the base BTF file, for instance: vmlinux when encoding
227 kernel module BTF information. This may be inferred when asking
228 for a /sys/kernel/btf/MODULE, when it will be autoconfigured to
229 "/sys/kernel/btf/vmlinux".
230
231
232 --btf_gen_floats
233 Allow producing BTF_KIND_FLOAT entries in systems where the vm‐
234 linux DWARF information has float types.
235
236
237 --btf_gen_all
238 Allow using all the BTF features supported by pahole.
239
240
241 -l, --show_first_biggest_size_base_type_member
242 Show first biggest size base_type member.
243
244
245 -m, --nr_methods
246 Show number of methods of all classes, i.e. the number of func‐
247 tions have arguments that are pointers to a given class.
248
249 To get the number of methods for an specific class, please use:
250
251 $ pahole --nr_methods | grep -w sock
252 sock 1005
253 $
254
255 In the above example it used the BTF information in /sys/ker‐
256 nel/btf/vmlinux.
257
258
259 -M, --show_only_data_members
260 Show only the members that use space in the class layout. C++
261 methods will be suppressed.
262
263
264 -n, --nr_members
265 Show number of members.
266
267
268 -N, --class_name_len
269 Show size of classes.
270
271
272 -O, --dwarf_offset=OFFSET
273 Show tag with DWARF OFFSET.
274
275
276 -P, --packable
277 Show only structs that has holes that can be packed if members
278 are reorganized, for instance when using the --reorganize op‐
279 tion.
280
281
282 -P, --with_flexible_array
283 Show only structs that have a flexible array.
284
285
286 -q, --quiet
287 Be quieter.
288
289
290 -s, --sizes
291 Show size of classes.
292
293
294 -t, --separator=SEP
295 Use SEP as the field separator.
296
297
298 -T, --nr_definitions
299 Show how many times struct was defined.
300
301
302 -u, --defined_in
303 Show CUs where CLASS_NAME (-C) is defined.
304
305
306 --flat_arrays
307 Flatten arrays, so that array[10][2] becomes array[20]. Useful
308 when generating from both CTF/BTF and DWARF encodings for the
309 same binary for testing purposes.
310
311
312 --suppress_aligned_attribute
313 Suppress forced alignment markers, so that one can compare BTF
314 or CTF output, that don't have that info, to output from DWARF
315 >= 5.
316
317
318 --suppress_force_paddings
319
320 Suppress bitfield forced padding at the end of structs, as this
321 requires something like DWARF's DW_AT_alignment, so that one can
322 compare BTF or CTF output, that don't have that info.
323
324
325 --suppress_packed
326
327 Suppress the output of the inference of __attri‐
328 bute__((__packed__)), so that one can compare BTF or CTF output,
329 the inference algorithm uses things like DW_AT_alignment, so un‐
330 til it is improved to infer that as well for BTF, allow dis‐
331 abling this output.
332
333
334 --fixup_silly_bitfields
335 Converts silly bitfields such as "int foo:32" to plain "int
336 foo".
337
338
339 -V, --verbose
340 be verbose
341
342
343 --ptr_table_stats
344 Print statistics about ptr_table data structures, used to hold
345 all the types, tags and functions data structures, for develop‐
346 ment tuning of such tables, tuned for a typical 2021 vmlinux
347 file.
348
349
350 -w, --word_size=WORD_SIZE
351 Change the arch word size to WORD_SIZE.
352
353
354 -x, --exclude=PREFIX
355 Exclude PREFIXed classes.
356
357
358 -X, --cu_exclude=PREFIX
359 Exclude PREFIXed compilation units.
360
361
362 -y, --prefix_filter=PREFIX
363 Include PREFIXed classes.
364
365
366 -z, --hole_size_ge=HOLE_SIZE
367 Show only structs with at least one hole greater or equal to
368 HOLE_SIZE.
369
370
371 --structs
372 Show only structs, all the other filters apply, i.e. to show
373 just the sizes of all structs combine --structs with --sizes,
374 etc.
375
376
377 --packed
378 Show only packed structs, all the other filters apply, i.e. to
379 show just the sizes of all packed structs combine --packed with
380 --sizes, etc.
381
382
383 --unions
384 Show only unions, all the other filters apply, i.e. to show just
385 the sizes of all unions combine --union with --sizes, etc.
386
387
388 --version
389 Show a traditional string version, i.e.: "v1.18".
390
391
392 --numeric_version
393 Show a numeric only version, suitable for use in Makefiles and
394 scripts where one wants to know what if the installed version
395 has some feature, i.e.: 118 instead of "v1.18".
396
397
398 --kabi_prefix=STRING
399 When the prefix of the string is STRING, treat the string as
400 STRING.
401
402
404 To enable the generation of debugging information in the Linux kernel
405 build process select CONFIG_DEBUG_INFO. This can be done using make
406 menuconfig by this path: "Kernel Hacking" -> "Compile-time checks and
407 compiler options" -> "Compile the kernel with debug info". Consider as
408 well enabling CONFIG_DEBUG_INFO_BTF by going thru the aforementioned
409 menuconfig path and then selecting "Generate BTF typeinfo". Most modern
410 distributions with eBPF support should come with that in all its ker‐
411 nels, greatly facilitating the use of pahole.
412
413 Many distributions also come with debuginfo packages, so just enable it
414 in your package manager repository configuration and install the ker‐
415 nel-debuginfo, or any other userspace program written in a language
416 that the compiler generates debuginfo (C, C++, for instance).
417
418
420 All the examples here use either /sys/kernel/btf/vmlinux, if present,
421 or lookup a vmlinux file matching the running kernel, using the build-
422 id info found in /sys/kernel/notes to make sure it matches.
423
424 Show a type:
425
426 $ pahole -C __u64
427 typedef long long unsigned int __u64;
428 $
429
430
431 Works as well if the only argument is a type name:
432
433 $ pahole raw_spinlock_t
434 typedef struct raw_spinlock raw_spinlock_t;
435 $
436
437
438 Multiple types can be passed, separated by commas:
439
440 $ pahole raw_spinlock_t,raw_spinlock
441 struct raw_spinlock {
442 arch_spinlock_t raw_lock; /* 0 4 */
443
444 /* size: 4, cachelines: 1, members: 1 */
445 /* last cacheline: 4 bytes */
446 };
447 typedef struct raw_spinlock raw_spinlock_t;
448 $
449
450
451 Types can be expanded:
452
453 $ pahole -E raw_spinlock
454 struct raw_spinlock {
455 /* typedef arch_spinlock_t */ struct qspinlock {
456 union {
457 /* typedef atomic_t */ struct {
458 int counter; /* 0 4 */
459 } val; /* 0 4 */
460 struct {
461 /* typedef u8 -> __u8 */ unsigned char locked; /* 0 1 */
462 /* typedef u8 -> __u8 */ unsigned char pending; /* 1 1 */
463 }; /* 0 2 */
464 struct {
465 /* typedef u16 -> __u16 */ short unsigned int locked_pending; /* 0 2 */
466 /* typedef u16 -> __u16 */ short unsigned int tail; /* 2 2 */
467 }; /* 0 4 */
468 }; /* 0 4 */
469 } raw_lock; /* 0 4 */
470
471 /* size: 4, cachelines: 1, members: 1 */
472 /* last cacheline: 4 bytes */
473 };
474 $
475
476
477 When decoding OOPSes you may want to see the offsets and sizes in hexa‐
478 decimal:
479
480 $ pahole --hex thread_struct
481 struct thread_struct {
482 struct desc_struct tls_array[3]; /* 0 0x18 */
483 long unsigned int sp; /* 0x18 0x8 */
484 short unsigned int es; /* 0x20 0x2 */
485 short unsigned int ds; /* 0x22 0x2 */
486 short unsigned int fsindex; /* 0x24 0x2 */
487 short unsigned int gsindex; /* 0x26 0x2 */
488 long unsigned int fsbase; /* 0x28 0x8 */
489 long unsigned int gsbase; /* 0x30 0x8 */
490 struct perf_event * ptrace_bps[4]; /* 0x38 0x20 */
491 /* --- cacheline 1 boundary (64 bytes) was 24 bytes ago --- */
492 long unsigned int debugreg6; /* 0x58 0x8 */
493 long unsigned int ptrace_dr7; /* 0x60 0x8 */
494 long unsigned int cr2; /* 0x68 0x8 */
495 long unsigned int trap_nr; /* 0x70 0x8 */
496 long unsigned int error_code; /* 0x78 0x8 */
497 /* --- cacheline 2 boundary (128 bytes) --- */
498 struct io_bitmap * io_bitmap; /* 0x80 0x8 */
499 long unsigned int iopl_emul; /* 0x88 0x8 */
500 mm_segment_t addr_limit; /* 0x90 0x8 */
501 unsigned int sig_on_uaccess_err:1; /* 0x98: 0 0x4 */
502 unsigned int uaccess_err:1; /* 0x98:0x1 0x4 */
503
504 /* XXX 30 bits hole, try to pack */
505 /* XXX 36 bytes hole, try to pack */
506
507 /* --- cacheline 3 boundary (192 bytes) --- */
508 struct fpu fpu; /* 0xc0 0x1040 */
509
510 /* size: 4352, cachelines: 68, members: 20 */
511 /* sum members: 4312, holes: 1, sum holes: 36 */
512 /* sum bitfield members: 2 bits, bit holes: 1, sum bit holes: 30 bits */
513 };
514 $
515
516
517 OK, I know the offset that causes its a 'struct thread_struct' and that
518 the offset is 0x178, so must be in that 'fpu' struct... No problem, ex‐
519 pand 'struct thread_struct' and combine with grep:
520
521 $ pahole --hex -E thread_struct | egrep '(0x178|struct fpu)' -B4 -A4
522 /* XXX 30 bits hole, try to pack */
523 /* XXX 36 bytes hole, try to pack */
524
525 /* --- cacheline 3 boundary (192 bytes) --- */
526 struct fpu {
527 unsigned int last_cpu; /* 0xc0 0x4 */
528
529 /* XXX 4 bytes hole, try to pack */
530
531 --
532 /* typedef u8 -> __u8 */ unsigned char alimit; /* 0x171 0x1 */
533
534 /* XXX 6 bytes hole, try to pack */
535
536 struct math_emu_info * info; /* 0x178 0x8 */
537 /* --- cacheline 6 boundary (384 bytes) --- */
538 /* typedef u32 -> __u32 */ unsigned int entry_eip; /* 0x180 0x4 */
539 } soft; /* 0x100 0x88 */
540 struct xregs_state {
541 $
542
543
544 Want to know where 'struct thread_struct' is defined in the kernel
545 sources?
546
547 $ pahole -I thread_struct | head -2
548 /* Used at: /sys/kernel/btf/vmlinux */
549 /* <0> (null):0 */
550 $
551
552
553 Not present in BTF, so use DWARF, takes a little bit longer, and assum‐
554 ing it finds the matching vmlinux file:
555
556 $ pahole -Fdwarf -I thread_struct | head -2
557 /* Used at: /home/acme/git/linux/arch/x86/kernel/head64.c */
558 /* <3333> /home/acme/git/linux/arch/x86/include/asm/processor.h:485 */
559 $
560
561
562 To find the biggest data structures in the Linux kernel:
563
564 $ pahole -s | sort -k2 -nr | head -5
565 cmp_data 290904 1
566 dec_datas 274520 1
567 cpu_entry_area 217088 0
568 pglist_data 172928 4
569 saved_cmdlines_buffer 131104 1
570 $
571
572 The second column is the size in bytes and the third is the number of
573 alignment holes in that structure.
574
575 Show data structures that have a raw spinlock and are related to the
576 RCU mechanism:
577
578 $ pahole --contains raw_spinlock_t --prefix rcu
579 rcu_node
580 rcu_data
581 rcu_state
582 $
583
584 To see that in context, combine it with grep:
585
586 $ pahole rcu_state | grep raw_spinlock_t -B1 -A5
587 /* --- cacheline 52 boundary (3328 bytes) --- */
588 raw_spinlock_t ofl_lock; /* 3328 4 */
589
590 /* size: 3392, cachelines: 53, members: 35 */
591 /* sum members: 3250, holes: 7, sum holes: 82 */
592 /* padding: 60 */
593 };
594 $
595
596
598 pahole can also use the data structure types to pretty print raw data
599 specified via --prettify. To consume raw data from the standard input,
600 just use '--prettify -'
601
602 It can also pretty print raw data from stdin according to the type
603 specified:
604
605 $ pahole -C modversion_info drivers/scsi/sg.ko
606 struct modversion_info {
607 long unsigned int crc; /* 0 8 */
608 char name[56]; /* 8 56 */
609
610 /* size: 64, cachelines: 1, members: 2 */
611 };
612 $
613 $ objcopy -O binary --only-section=__versions drivers/scsi/sg.ko versions
614 $
615 $ ls -la versions
616 -rw-rw-r--. 1 acme acme 7616 Jun 25 11:33 versions
617 $
618 $ pahole --count 3 -C modversion_info drivers/scsi/sg.ko --prettify versions
619 {
620 .crc = 0x8dabd84,
621 .name = "module_layout",
622 },
623 {
624 .crc = 0x45e4617b,
625 .name = "no_llseek",
626 },
627 {
628 .crc = 0xa23fae8c,
629 .name = "param_ops_int",
630 },
631 $
632 $ pahole --skip 1 --count 2 -C modversion_info drivers/scsi/sg.ko --prettify - < versions
633 {
634 .crc = 0x45e4617b,
635 .name = "no_llseek",
636 },
637 {
638 .crc = 0xa23fae8c,
639 .name = "param_ops_int",
640 },
641 $
642 This is equivalent to:
643
644 $ pahole --seek_bytes 64 --count 1 -C modversion_info drivers/scsi/sg.ko --prettify versions
645 {
646 .crc = 0x45e4617b,
647 .name = "no_llseek",
648 },
649 $
650
651 -C, --class_name=CLASS_NAME
652 Pretty print according to this class. Arguments may be passed to
653 it to affect how the pretty printing is performed, e.g.:
654
655
656 -C 'perf_event_header(sizeof,type,type_enum=perf_event_type,filter=type==PERF_RECORD_EXIT)'
657
658 This would select the 'struct perf_event_header' as the type to use to
659 pretty print records states that the 'size' field in that struct should
660 be used to figure out the size of the record (variable sized records),
661 that the 'enum perf_event_type' should be used to pretty print the nu‐
662 meric value in perf_event_header->type and furthermore that it should
663 be used to heuristically look for structs with the same name (lower‐
664 case) of the enum entry that is converted from the type field, using it
665 to pretty print instead of the base 'perf_event_header' type. See the
666 PRETTY PRINTING EXAMPLES section below.
667
668 Furthermore the 'filter=' part can be used, so far with only the '=='
669 operator to filter based on the 'type' field and converting the string
670 'PERF_RECORD_EXIT' to a number according to type_enum.
671
672 The 'sizeof' arg defaults to the 'size' member name, if the name is
673 different, one can use
674 'sizeof=sz' form, ditto for 'type=other_member_name' field, that de‐
675 faults to 'type'.
676
677
679 Looking at the ELF header for a vmlinux file, using BTF, first lets
680 discover the ELF header type:
681
682 $ pahole --sizes | grep -i elf | grep -i _h
683 elf64_hdr 64 0
684 elf32_hdr 52 0
685 $
686
687 Now we can use this to show the first record from offset zero:
688
689 $ pahole -C elf64_hdr --count 1 --prettify /lib/modules/5.8.0-rc3+/build/vmlinux
690 {
691 .e_ident = { 127, 69, 76, 70, 2, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0 },
692 .e_type = 2,
693 .e_machine = 62,
694 .e_version = 1,
695 .e_entry = 16777216,
696 .e_phoff = 64,
697 .e_shoff = 775923840,
698 .e_flags = 0,
699 .e_ehsize = 64,
700 .e_phentsize = 56,
701 .e_phnum = 5,
702 .e_shentsize = 64,
703 .e_shnum = 80,
704 .e_shstrndx = 79,
705 },
706 $
707
708 This is equivalent to:
709
710 $ pahole --header elf64_hdr --prettify /lib/modules/5.8.0-rc3+/build/vmlinux
711
712 The --header option also allows reference in other command line options
713 to fields in the header. This is useful when one wants to show multi‐
714 ple records in a file and the range where those fields are located is
715 specified in header fields, such as for perf.data files:
716
717 $ pahole --hex ~/bin/perf --header perf_file_header --prettify perf.data
718 {
719 .magic = 0x32454c4946524550,
720 .size = 0x68,
721 .attr_size = 0x88,
722 .attrs = {
723 .offset = 0xa8,
724 .size = 0x88,
725 },
726 .data = {
727 .offset = 0x130,
728 .size = 0x588,
729 },
730 .event_types = {
731 .offset = 0,
732 .size = 0,
733 },
734 .adds_features = { 0x16717ffc, 0, 0, 0 },
735 },
736 $
737
738 So to display the cgroups records in the perf_file_header.data section
739 we can use:
740
741 $ pahole ~/bin/perf --header=perf_file_header --seek_bytes '$header.data.offset' --size_bytes='$header.data.size' -C 'perf_event_header(sizeof,type,type_enum=perf_event_type,filter=type==PERF_RECORD_CGROUP)' --prettify perf.data
742 {
743 .header = {
744 .type = PERF_RECORD_CGROUP,
745 .misc = 0,
746 .size = 40,
747 },
748 .id = 1,
749 .path = "/",
750 },
751 {
752 .header = {
753 .type = PERF_RECORD_CGROUP,
754 .misc = 0,
755 .size = 48,
756 },
757 .id = 1553,
758 .path = "/system.slice",
759 },
760 {
761 .header = {
762 .type = PERF_RECORD_CGROUP,
763 .misc = 0,
764 .size = 48,
765 },
766 .id = 8,
767 .path = "/machine.slice",
768 },
769 {
770 .header = {
771 .type = PERF_RECORD_CGROUP,
772 .misc = 0,
773 .size = 128,
774 },
775 .id = 7828,
776 .path = "/machine.slice/libpod-42be8e8d4eb9d22405845005f0d04ea398548dccc934a150fbaa3c1f1f9492c2.scope",
777 },
778 {
779 .header = {
780 .type = PERF_RECORD_CGROUP,
781 .misc = 0,
782 .size = 88,
783 },
784 .id = 13,
785 .path = "/machine.slice/machine-qemud1drhel6.sandy.scope",
786 },
787 $
788
789 For the common case of the header having a member that has the 'offset'
790 and 'size' members, it is possible to use this more compact form:
791
792 $ pahole ~/bin/perf --header=perf_file_header --range=data -C 'perf_event_header(sizeof,type,type_enum=perf_event_type,filter=type==PERF_RECORD_CGROUP)' --prettify perf.data
793
794 This uses ~/bin/perf to get the type definitions, the defines 'struct
795 perf_file_header' as the header, then seeks '$header.data.offset' bytes
796 from the start of the file, and considers '$header.data.size' bytes
797 worth of such records. The filter expression may omit a common prefix,
798 in this case it could additonally be equivalently written as both 'fil‐
799 ter=type==CGROUP' or the 'filter=' can also be omitted, getting as com‐
800 pact as 'type==CGROUP':
801
802 If we look at:
803
804 $ pahole ~/bin/perf -C perf_event_header
805 struct perf_event_header {
806 __u32 type; /* 0 4 */
807 __u16 misc; /* 4 2 */
808 __u16 size; /* 6 2 */
809
810 /* size: 8, cachelines: 1, members: 3 */
811 /* last cacheline: 8 bytes */
812 };
813 $
814
815 And:
816
817 $ pahole ~/bin/perf -C perf_event_type
818 enum perf_event_type {
819 PERF_RECORD_MMAP = 1,
820 PERF_RECORD_LOST = 2,
821 PERF_RECORD_COMM = 3,
822 PERF_RECORD_EXIT = 4,
823 PERF_RECORD_THROTTLE = 5,
824 PERF_RECORD_UNTHROTTLE = 6,
825 PERF_RECORD_FORK = 7,
826 PERF_RECORD_READ = 8,
827 PERF_RECORD_SAMPLE = 9,
828 PERF_RECORD_MMAP2 = 10,
829 PERF_RECORD_AUX = 11,
830 PERF_RECORD_ITRACE_START = 12,
831 PERF_RECORD_LOST_SAMPLES = 13,
832 PERF_RECORD_SWITCH = 14,
833 PERF_RECORD_SWITCH_CPU_WIDE = 15,
834 PERF_RECORD_NAMESPACES = 16,
835 PERF_RECORD_KSYMBOL = 17,
836 PERF_RECORD_BPF_EVENT = 18,
837 PERF_RECORD_CGROUP = 19,
838 PERF_RECORD_TEXT_POKE = 20,
839 PERF_RECORD_MAX = 21,
840 };
841 $
842
843 And furthermore:
844
845 $ pahole ~/bin/perf -C perf_record_cgroup
846 struct perf_record_cgroup {
847 struct perf_event_header header; /* 0 8 */
848 __u64 id; /* 8 8 */
849 char path[4096]; /* 16 4096 */
850
851 /* size: 4112, cachelines: 65, members: 3 */
852 /* last cacheline: 16 bytes */
853 };
854 $
855
856 Then we can see how the perf_event_header.type could be converted from
857 a __u32 to a string (PERF_RECORD_CGROUP). If we remove that
858 type_enum=perf_event_type, we will lose the conversion of 'struct
859 perf_event_header' to the more descriptive 'struct perf_record_cgroup',
860 and also the beautification of the header.type field:
861
862 $ pahole ~/bin/perf --header=perf_file_header --seek_bytes '$header.data.offset' --size_bytes='$header.data.size' -C 'perf_event_header(sizeof,type,filter=type==19)' --prettify perf.data
863 {
864 .type = 19,
865 .misc = 0,
866 .size = 40,
867 },
868 {
869 .type = 19,
870 .misc = 0,
871 .size = 48,
872 },
873 {
874 .type = 19,
875 .misc = 0,
876 .size = 48,
877 },
878 {
879 .type = 19,
880 .misc = 0,
881 .size = 128,
882 },
883 {
884 .type = 19,
885 .misc = 0,
886 .size = 88,
887 },
888 $
889
890 Some of the records are not found in 'type_enum=perf_event_type' so
891 some of the records don't get converted to a type that fully shows its
892 contents. For perf we know that those are in another enumeration, 'enum
893 perf_user_event_type', so, for these cases, we can create a 'virtual
894 enum', i.e. the sum of two enums and then get all those entries decoded
895 and properly casted, first few records with just 'enum
896 perf_event_type':
897
898 $ pahole ~/bin/perf --header=perf_file_header --seek_bytes '$header.data.offset' --size_bytes='$header.data.size' -C 'perf_event_header(sizeof,type,type_enum=perf_event_type)' --count 4 --prettify perf.data
899 {
900 .type = 79,
901 .misc = 0,
902 .size = 32,
903 },
904 {
905 .type = 73,
906 .misc = 0,
907 .size = 40,
908 },
909 {
910 .type = 74,
911 .misc = 0,
912 .size = 32,
913 },
914 {
915 .header = {
916 .type = PERF_RECORD_CGROUP,
917 .misc = 0,
918 .size = 40,
919 },
920 .id = 1,
921 .path = "/",
922 },
923 $
924
925 Now with both enumerations, i.e. with
926 'type_enum=perf_event_type+perf_user_event_type':
927
928 $ pahole ~/bin/perf --header=perf_file_header --seek_bytes '$header.data.offset' --size_bytes='$header.data.size' -C 'perf_event_header(sizeof,type,type_enum=perf_event_type+perf_user_event_type)' --count 5 --prettify perf.data
929 {
930 .header = {
931 .type = PERF_RECORD_TIME_CONV,
932 .misc = 0,
933 .size = 32,
934 },
935 .time_shift = 31,
936 .time_mult = 1016803377,
937 .time_zero = 435759009518382,
938 },
939 {
940 .header = {
941 .type = PERF_RECORD_THREAD_MAP,
942 .misc = 0,
943 .size = 40,
944 },
945 .nr = 1,
946 .entries = 0x50 0x7e 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00,
947 },
948 {
949 .header = {
950 .type = PERF_RECORD_CPU_MAP,
951 .misc = 0,
952 .size = 32,
953 },
954 .data = {
955 .type = 1,
956 .data = "",
957 },
958 },
959 {
960 .header = {
961 .type = PERF_RECORD_CGROUP,
962 .misc = 0,
963 .size = 40,
964 },
965 .id = 1,
966 .path = "/",
967 },
968 {
969 .header = {
970 .type = PERF_RECORD_CGROUP,
971 .misc = 0,
972 .size = 48,
973 },
974 .id = 1553,
975 .path = "/system.slice",
976 },
977 $
978
979 It is possible to pass multiple types, one has only to make sure they
980 appear in the file in sequence, i.e. for the perf.data example, see the
981 perf_file_header dump above, one can print the perf_file_attr structs
982 in the header attrs range, then the perf_event_header in the data range
983 with the following command:
984
985 pahole ~/bin/perf --header=perf_file_header -C 'perf_file_attr(range=attrs),perf_event_header(range=data,sizeof,type,type_enum=perf_event_type+perf_user_event_type)' --prettify perf.data
986
987
989 eu-readelf(1), readelf(1), objdump(1).
990
991 https://www.kernel.org/doc/ols/2007/ols2007v2-pages-35-44.pdf.
992
994 pahole was written and is maintained by Arnaldo Carvalho de Melo
995 <acme@kernel.org>.
996
997 Thanks to Andrii Nakryiko and Martin KaFai Lau for providing the BTF
998 encoder and improving the codebase while making sure the BTF encoder
999 works as needed to be used in encoding the Linux kernel .BTF section
1000 from the DWARF info generated by gcc. For that Andrii wrote a BTF dedu‐
1001 plicator in libbpf that is used by pahole.
1002
1003 Also thanks to Conectiva, Mandriva and Red Hat for allowing me to work
1004 on these tools.
1005
1006 Please send bug reports to <dwarves@vger.kernel.org>.
1007
1008 No subscription is required.
1009
1010
1011
1012dwarves January 16, 2020 pahole(1)