1pahole(1) dwarves pahole(1)
2
6 pahole - Shows and manipulates data structure layout.
7
9 pahole [options] files
10
12 pahole shows data structure layouts encoded in debugging information
13 formats, DWARF and CTF being supported.
14 This is useful for, among other things: optimizing important data
16 structures by reducing its size, figuring out what is the field sitting
17 at an offset from the start of a data structure, investigating ABI
18 changes and more generally understanding a new codebase you have to
19 work with.
20 The files must have associated debugging information. This information
22 may be inside the file itself, in ELF sections, or in another file.
23 One way to have this information is to specify the -g option to the
25 compiler when building it. When this is done the information will be
26 stored in an ELF section. For the DWARF debugging information format
27 this, adds, among others, the .debug_info ELF section. For CTF it is
28 found in just one ELF section, .SUNW_ctf. BTF comes in at least the
29 .BTF ELF section, and may come also with the .BTF.ext ELF section.
30 The debuginfo packages available in most Linux distributions are also
32 supported by pahole, where the debugging information is available in a
33 separate file.
34 By default, pahole shows the layout of all named structs in the files
36 specified.
37 If no files are specified, then it will look if the /sys/ker‐
39 nel/btf/vmlinux is present, using the BTF information present in it
40 about the running kernel, i.e. this works:
41 $ pahole list_head
43 struct list_head {
44 struct list_head * next; /* 0 8 */
45 struct list_head * prev; /* 8 8 */
46 /* size: 16, cachelines: 1, members: 2 */
48 /* last cacheline: 16 bytes */
49 };
50 $
51 If BTF is not present and no file is passed, then a vmlinux that
53 matches the build-id for the running kernel will be looked up in the
54 usual places, including where the kernel debuginfo packages put it,
55 looking for DWARF info instead.
56 See the EXAMPLES section for more usage suggestions.
58
61 pahole supports the following options.
62 -C, --class_name=CLASS_NAMES
65 Show just these classes. This can be a comma separated list of
66 class names or file URLs (e.g.: file://class_list.txt)
67 -c, --cacheline_size=SIZE
70 Set cacheline size to SIZE bytes.
71 -E, --expand_types
74 Expand class members. Useful to find in what member of inner
75 structs where an offset from the beginning of a struct is.
76 -F, --format_path
79 Allows specifying a list of debugging formats to try, in order.
80 Right now this includes "ctf" and "dwarf". The default format
81 path used is equivalent to "-F dwarf,ctf".
82 --hex Print offsets and sizes in hexadecimal.
85 -r, --rel_offset
88 Show relative offsets of members in inner structs.
89 -p, --expand_pointers
92 Expand class pointer members.
93 -R, --reorganize
96 Reorganize struct, demoting and combining bitfields, moving mem‐
97 bers to remove alignment holes and padding.
98 -S, --show_reorg_steps
101 Show the struct layout at each reorganization step.
102 -i, --contains=CLASS_NAME
105 Show classes that contains CLASS_NAME.
106 -a, --anon_include
109 Include anonymous classes.
110 -A, --nested_anon_include
113 Include nested (inside other structs) anonymous classes.
114 -B, --bit_holes=NR_HOLES
117 Show only structs at least NR_HOLES bit holes.
118 -d, --recursive
121 Recursive mode, affects several other flags.
122 -D, --decl_exclude=PREFIX
125 exclude classes declared in files with PREFIX.
126 -f, --find_pointers_to=CLASS_NAME
129 Find pointers to CLASS_NAME.
130 -H, --holes=NR_HOLES
133 Show only structs with at least NR_HOLES holes.
134 -I, --show_decl_info
137 Show the file and line number where the tags were defined, if
138 available in the debugging information.
139 -l, --show_first_biggest_size_base_type_member
142 Show first biggest size base_type member.
143 -m, --nr_methods
146 Show number of methods.
147 -M, --show_only_data_members
150 Show only the members that use space in the class layout. C++
151 methods will be suppressed.
152 -n, --nr_members
155 Show number of members.
156 -N, --class_name_len
159 Show size of classes.
160 -O, --dwarf_offset=OFFSET
163 Show tag with DWARF OFFSET.
164 -P, --packable
167 Show only structs that has holes that can be packed if members
168 are reorganized, for instance when using the --reorganize
169 option.
170 -q, --quiet
173 Be quieter.
174 -s, --sizes
177 Show size of classes.
178 -t, --separator=SEP
181 Use SEP as the field separator.
182 -T, --nr_definitions
185 Show how many times struct was defined.
186 -u, --defined_in
189 Show CUs where CLASS_NAME (-C) is defined.
190 --flat_arrays
193 Flatten arrays, so that array[10][2] becomes array[20]. Useful
194 when generating from both CTF/BTF and DWARF encodings for the
195 same binary for testing purposes.
196 --suppress_aligned_attribute
199 Suppress forced alignment markers, so that one can compare BTF
200 or CTF output, that don't have that info, to output from DWARF
201 >= 5.
202 --suppress_force_paddings
205 Suppress bitfield forced padding at the end of structs, as this
207 requires something like DWARF's DW_AT_alignment, so that one can
208 compare BTF or CTF output, that don't have that info.
209 --suppress_packed
212 Suppress the output of the inference of
214 __attribute__((__packed__)), so that one can compare BTF or CTF
215 output, the inference algorithm uses things like DW_AT_align‐
216 ment, so until it is improved to infer that as well for BTF,
217 allow disabling this output.
218 --fixup_silly_bitfields
221 Converts silly bitfields such as "int foo:32" to plain "int
222 foo".
223 -V, --verbose
226 be verbose
227 -w, --word_size=WORD_SIZE
230 Change the arch word size to WORD_SIZE.
231 -x, --exclude=PREFIX
234 Exclude PREFIXed classes.
235 -X, --cu_exclude=PREFIX
238 Exclude PREFIXed compilation units.
239 -y, --prefix_filter=PREFIX
242 Include PREFIXed classes.
243 -z, --hole_size_ge=HOLE_SIZE
246 Show only structs with at least one hole greater or equal to
247 HOLE_SIZE.
248 --structs
251 Show only structs, all the other filters apply, i.e. to show
252 just the sizes of all structs coimbine --structs with --sizes,
253 etc.
254 --unions
257 Show only unions, all the other filters apply, i.e. to show just
258 the sizes of all unions coimbine --union with --sizes, etc.
259
262 To enable the generation of debugging information in the Linux kernel
263 build process select CONFIG_DEBUG_INFO. This can be done using make
264 menuconfig by this path: "Kernel Hacking" -> "Compile-time checks and
265 compiler options" -> "Compile the kernel with debug info". Consider as
266 well enabling CONFIG_DEBUG_INFO_BTF by going thru the aforementioned
267 menuconfig path and then selecting "Generate BTF typeinfo". Most modern
268 distributions with eBPF support should come with that in all its ker‐
269 nels, greatly facilitating the use of pahole.
270 Many distributions also come with debuginfo packages, so just enable it
272 in your package manager repository configuration and install the ker‐
273 nel-debuginfo, or any other userspace program written in a language
274 that the compiler generates debuginfo (C, C++, for instance).
275
278 All the examples here use either /sys/kernel/btf/vmlinux, if present,
279 or lookup a vmlinux file matching the running kernel, using the build-
280 id info found in /sys/kernel/notes to make sure it matches.
281 Show a type:
283 $ pahole -C __u64
285 typedef long long unsigned int __u64;
286 $
287 Works as well if the only argument is a type name:
290 $ pahole raw_spinlock_t
292 typedef struct raw_spinlock raw_spinlock_t;
293 $
294 Multiple types can be passed, separated by commas:
297 $ pahole raw_spinlock_t,raw_spinlock
299 struct raw_spinlock {
300 arch_spinlock_t raw_lock; /* 0 4 */
301 /* size: 4, cachelines: 1, members: 1 */
303 /* last cacheline: 4 bytes */
304 };
305 typedef struct raw_spinlock raw_spinlock_t;
306 $
307 Types can be expanded:
310 $ pahole -E raw_spinlock
312 struct raw_spinlock {
313 /* typedef arch_spinlock_t */ struct qspinlock {
314 union {
315 /* typedef atomic_t */ struct {
316 int counter; /* 0 4 */
317 } val; /* 0 4 */
318 struct {
319 /* typedef u8 -> __u8 */ unsigned char locked; /* 0 1 */
320 /* typedef u8 -> __u8 */ unsigned char pending; /* 1 1 */
321 }; /* 0 2 */
322 struct {
323 /* typedef u16 -> __u16 */ short unsigned int locked_pending; /* 0 2 */
324 /* typedef u16 -> __u16 */ short unsigned int tail; /* 2 2 */
325 }; /* 0 4 */
326 }; /* 0 4 */
327 } raw_lock; /* 0 4 */
328 /* size: 4, cachelines: 1, members: 1 */
330 /* last cacheline: 4 bytes */
331 };
332 $
333 When decoding OOPSes you may want to see the offsets and sizes in hexa‐
336 decimal:
337 $ pahole --hex thread_struct
339 struct thread_struct {
340 struct desc_struct tls_array[3]; /* 0 0x18 */
341 long unsigned int sp; /* 0x18 0x8 */
342 short unsigned int es; /* 0x20 0x2 */
343 short unsigned int ds; /* 0x22 0x2 */
344 short unsigned int fsindex; /* 0x24 0x2 */
345 short unsigned int gsindex; /* 0x26 0x2 */
346 long unsigned int fsbase; /* 0x28 0x8 */
347 long unsigned int gsbase; /* 0x30 0x8 */
348 struct perf_event * ptrace_bps[4]; /* 0x38 0x20 */
349 /* --- cacheline 1 boundary (64 bytes) was 24 bytes ago --- */
350 long unsigned int debugreg6; /* 0x58 0x8 */
351 long unsigned int ptrace_dr7; /* 0x60 0x8 */
352 long unsigned int cr2; /* 0x68 0x8 */
353 long unsigned int trap_nr; /* 0x70 0x8 */
354 long unsigned int error_code; /* 0x78 0x8 */
355 /* --- cacheline 2 boundary (128 bytes) --- */
356 struct io_bitmap * io_bitmap; /* 0x80 0x8 */
357 long unsigned int iopl_emul; /* 0x88 0x8 */
358 mm_segment_t addr_limit; /* 0x90 0x8 */
359 unsigned int sig_on_uaccess_err:1; /* 0x98: 0 0x4 */
360 unsigned int uaccess_err:1; /* 0x98:0x1 0x4 */
361 /* XXX 30 bits hole, try to pack */
363 /* XXX 36 bytes hole, try to pack */
364 /* --- cacheline 3 boundary (192 bytes) --- */
366 struct fpu fpu; /* 0xc0 0x1040 */
367 /* size: 4352, cachelines: 68, members: 20 */
369 /* sum members: 4312, holes: 1, sum holes: 36 */
370 /* sum bitfield members: 2 bits, bit holes: 1, sum bit holes: 30 bits */
371 };
372 $
373 OK, I know the offset that causes its a 'struct thread_struct' and that
376 the offset is 0x178, so must be in that 'fpu' struct... No problem,
377 expand 'struct thread_struct' and combine with grep:
378 $ pahole --hex -E thread_struct | egrep '(0x178|struct fpu)' -B4 -A4
380 /* XXX 30 bits hole, try to pack */
381 /* XXX 36 bytes hole, try to pack */
382 /* --- cacheline 3 boundary (192 bytes) --- */
384 struct fpu {
385 unsigned int last_cpu; /* 0xc0 0x4 */
386 /* XXX 4 bytes hole, try to pack */
388 --
390 /* typedef u8 -> __u8 */ unsigned char alimit; /* 0x171 0x1 */
391 /* XXX 6 bytes hole, try to pack */
393 struct math_emu_info * info; /* 0x178 0x8 */
395 /* --- cacheline 6 boundary (384 bytes) --- */
396 /* typedef u32 -> __u32 */ unsigned int entry_eip; /* 0x180 0x4 */
397 } soft; /* 0x100 0x88 */
398 struct xregs_state {
399 $
400 Want to know where 'struct thread_struct' is defined in the kernel
403 sources?
404 $ pahole -I thread_struct | head -2
406 /* Used at: /sys/kernel/btf/vmlinux */
407 /* <0> (null):0 */
408 $
409 Not present in BTF, so use DWARF, takes a little bit longer, and assum‐
412 ing it finds the matching vmlinux file:
413 $ pahole -Fdwarf -I thread_struct | head -2
415 /* Used at: /home/acme/git/linux/arch/x86/kernel/head64.c */
416 /* <3333> /home/acme/git/linux/arch/x86/include/asm/processor.h:485 */
417 $
418 To find the biggest data structures in the Linux kernel:
421 $ pahole -s | sort -k2 -nr | head -5
423 cmp_data 290904 1
424 dec_datas 274520 1
425 cpu_entry_area 217088 0
426 pglist_data 172928 4
427 saved_cmdlines_buffer 131104 1
428 $
429 The second column is the size in bytes and the third is the number of
431 alignment holes in that structure.
432 Show data structures that have a raw spinlock and are related to the
434 RCU mechanism:
435 $ pahole --contains raw_spinlock_t --prefix rcu
437 rcu_node
438 rcu_data
439 rcu_state
440 $
441 To see that in context, combine it with grep:
443 $ pahole rcu_state | grep raw_spinlock_t -B1 -A5
445 /* --- cacheline 52 boundary (3328 bytes) --- */
446 raw_spinlock_t ofl_lock; /* 3328 4 */
447 /* size: 3392, cachelines: 53, members: 35 */
449 /* sum members: 3250, holes: 7, sum holes: 82 */
450 /* padding: 60 */
451 };
452 $
453
455 eu-readelf(1), readelf(1), objdump(1).
456 https://www.kernel.org/doc/ols/2007/ols2007v2-pages-35-44.pdf.
458
460 pahole was written and is maintained by Arnaldo Carvalho de Melo
461 <acme@kernel.org>.
462 Thanks to Andrii Nakryiko and Martin KaFai Lau for providing the BTF
464 encoder and improving the codebase while making sure the BTF encoder
465 works as needed to be used in encoding the Linux kernel .BTF section
466 from the DWARF info generated by gcc. For that Andrii wrote a BTF dedu‐
467 plicator in libbpf that is used by pahole.
468 Please send bug reports to <dwarves@vger.kernel.org>.
470 No subscription is required.
472dwarves January 16, 2020 pahole(1)