.\" Man page for pahole
.\" Arnaldo Carvalho de Melo, 2009
.\" Licensed under version 2 of the GNU General Public License.
.TH pahole 1 "January 16, 2020" "dwarves" "dwarves"
.\"
.SH NAME
pahole \- Shows and manipulates data structure layout.
.SH SYNOPSIS
\fBpahole\fR [\fIoptions\fR] \fIfiles\fR
.SH DESCRIPTION
.B pahole
shows data structure layouts encoded in debugging information formats,
DWARF and CTF being supported.

This is useful for, among other things: optimizing important data structures by
reducing its size, figuring out what is the field sitting at an offset from the
start of a data structure, investigating ABI changes and more generally
understanding a new codebase you have to work with.

The files must have associated debugging information.  This information may be
inside the file itself, in ELF sections, or in another file.

One way to have this information is to specify the \fB\-g\fR option to the
compiler when building it. When this is done the information will be stored in
an ELF section. For the DWARF debugging information format this, adds, among
others, the \fB.debug_info\fR ELF section. For CTF it is found in just one ELF
section, \fB.SUNW_ctf\fR. BTF comes in at least the \fB.BTF\fR ELF section, and
may come also with the \fB.BTF.ext\fR ELF section.

The \fBdebuginfo\fR packages available in most Linux distributions are also
supported by \fBpahole\fR, where the debugging information is available in a
separate file.

By default, \fBpahole\fR shows the layout of all named structs in the files
specified.

If no files are specified, then it will look if the /sys/kernel/btf/vmlinux
is present, using the BTF information present in it about the running kernel,
i.e. this works:
.PP
.nf
$ pahole list_head
struct list_head {
	struct list_head *         next;                 /*     0     8 */
	struct list_head *         prev;                 /*     8     8 */

	/* size: 16, cachelines: 1, members: 2 */
	/* last cacheline: 16 bytes */
};
$
.fi

If BTF is not present and no file is passed, then a vmlinux that matches the
build-id for the running kernel will be looked up in the usual places,
including where the kernel debuginfo packages put it, looking for DWARF info
instead.

See the EXAMPLES section for more usage suggestions.

.SH OPTIONS
pahole supports the following options.

.TP
.B \-C, \-\-class_name=CLASS_NAMES
Show just these classes. This can be a comma separated list of class names
or file URLs (e.g.: file://class_list.txt)

.TP
.B \-c, \-\-cacheline_size=SIZE
Set cacheline size to SIZE bytes.

.TP
.B \-E, \-\-expand_types
Expand class members. Useful to find in what member of inner structs where an
offset from the beginning of a struct is.

.TP
.B \-F, \-\-format_path
Allows specifying a list of debugging formats to try, in order. Right now this
includes "ctf" and "dwarf". The default format path used is equivalent to
"-F dwarf,ctf".

.TP
.B \-\-hex
Print offsets and sizes in hexadecimal.

.TP
.B \-r, \-\-rel_offset
Show relative offsets of members in inner structs.

.TP
.B \-p, \-\-expand_pointers
Expand class pointer members.

.TP
.B \-R, \-\-reorganize
Reorganize struct, demoting and combining bitfields, moving members to remove
alignment holes and padding.

.TP
.B \-S, \-\-show_reorg_steps
Show the struct layout at each reorganization step.

.TP
.B \-i, \-\-contains=CLASS_NAME
Show classes that contains CLASS_NAME.

.TP
.B \-a, \-\-anon_include
Include anonymous classes.

.TP
.B \-A, \-\-nested_anon_include
Include nested (inside other structs) anonymous classes.

.TP
.B \-B, \-\-bit_holes=NR_HOLES
Show only structs at least NR_HOLES bit holes.

.TP
.B \-d, \-\-recursive
Recursive mode, affects several other flags.

.TP
.B \-D, \-\-decl_exclude=PREFIX
exclude classes declared in files with PREFIX.

.TP
.B \-f, \-\-find_pointers_to=CLASS_NAME
Find pointers to CLASS_NAME.

.TP
.B \-H, \-\-holes=NR_HOLES
Show only structs with at least NR_HOLES holes.

.TP
.B \-I, \-\-show_decl_info
Show the file and line number where the tags were defined, if available in
the debugging information.

.TP
.B \-l, \-\-show_first_biggest_size_base_type_member
Show first biggest size base_type member.

.TP
.B \-m, \-\-nr_methods
Show number of methods.

.TP
.B \-M, \-\-show_only_data_members
Show only the members that use space in the class layout. C++ methods will be
suppressed.

.TP
.B \-n, \-\-nr_members
Show number of members.

.TP
.B \-N, \-\-class_name_len
Show size of classes.

.TP
.B \-O, \-\-dwarf_offset=OFFSET
Show tag with DWARF OFFSET.

.TP
.B \-P, \-\-packable
Show only structs that has holes that can be packed if members are reorganized,
for instance when using the \fB\-\-reorganize\fR option.

.TP
.B \-q, \-\-quiet
Be quieter.

.TP
.B \-s, \-\-sizes
Show size of classes.

.TP
.B \-t, \-\-separator=SEP
Use SEP as the field separator.

.TP
.B \-T, \-\-nr_definitions
Show how many times struct was defined.

.TP
.B \-u, \-\-defined_in
Show CUs where CLASS_NAME (-C) is defined.

.TP
.B     \-\-flat_arrays
Flatten arrays, so that array[10][2] becomes array[20].
Useful when generating from both CTF/BTF and DWARF encodings
for the same binary for testing purposes.

.TP
.B     \-\-suppress_aligned_attribute
Suppress forced alignment markers, so that one can compare BTF or
CTF output, that don't have that info, to output from DWARF >= 5.

.TP
.B     \-\-suppress_force_paddings

Suppress bitfield forced padding at the end of structs, as this requires
something like DWARF's DW_AT_alignment, so that one can compare BTF or CTF
output, that don't have that info.

.TP
.B     \-\-suppress_packed

Suppress the output of the inference of __attribute__((__packed__)), so that
one can compare BTF or CTF output, the inference algorithm uses things like
DW_AT_alignment, so until it is improved to infer that as well for BTF, allow
disabling this output.

.TP
.B     \-\-fixup_silly_bitfields
Converts silly bitfields such as "int foo:32" to plain "int foo".

.TP
.B \-V, \-\-verbose
be verbose

.TP
.B \-w, \-\-word_size=WORD_SIZE
Change the arch word size to WORD_SIZE.

.TP
.B \-x, \-\-exclude=PREFIX
Exclude PREFIXed classes.

.TP
.B \-X, \-\-cu_exclude=PREFIX
Exclude PREFIXed compilation units.

.TP
.B \-y, \-\-prefix_filter=PREFIX
Include PREFIXed classes.

.TP
.B \-z, \-\-hole_size_ge=HOLE_SIZE
Show only structs with at least one hole greater or equal to HOLE_SIZE.

.TP
.B \-\-structs
Show only structs, all the other filters apply, i.e. to show just the sizes of all structs
coimbine --structs with --sizes, etc.

.TP
.B \-\-unions
Show only unions, all the other filters apply, i.e. to show just the sizes of all unions
coimbine --union with --sizes, etc.

.SH NOTES

To enable the generation of debugging information in the Linux kernel build
process select CONFIG_DEBUG_INFO. This can be done using make menuconfig by
this path: "Kernel Hacking" -> "Compile-time checks and compiler options" ->
"Compile the kernel with debug info". Consider as well enabling
CONFIG_DEBUG_INFO_BTF by going thru the aforementioned menuconfig path and then
selecting "Generate BTF typeinfo". Most modern distributions with eBPF support
should come with that in all its kernels, greatly facilitating the use of
pahole.

Many distributions also come with debuginfo packages, so just enable it in your
package manager repository configuration and install the kernel-debuginfo, or
any other userspace program written in a language that the compiler generates
debuginfo (C, C++, for instance).

.SH EXAMPLES

All the examples here use either /sys/kernel/btf/vmlinux, if present, or lookup
a vmlinux file matching the running kernel, using the build-id info found in
/sys/kernel/notes to make sure it matches.
.P
Show a type:
.PP
.nf
$ pahole -C __u64
typedef long long unsigned int __u64;
$
.fi

.P
Works as well if the only argument is a type name:
.PP
.nf
$ pahole raw_spinlock_t
typedef struct raw_spinlock raw_spinlock_t;
$
.fi

.P
Multiple types can be passed, separated by commas:
.PP
.nf
$ pahole raw_spinlock_t,raw_spinlock
struct raw_spinlock {
	arch_spinlock_t            raw_lock;             /*     0     4 */

	/* size: 4, cachelines: 1, members: 1 */
	/* last cacheline: 4 bytes */
};
typedef struct raw_spinlock raw_spinlock_t;
$
.fi

.P
Types can be expanded:
.PP
.nf
$ pahole -E raw_spinlock
struct raw_spinlock {
        /* typedef arch_spinlock_t */ struct qspinlock {
                union {
                        /* typedef atomic_t */ struct {
                                int counter;                                                  /*     0     4 */
                        } val;                                                                /*     0     4 */
                        struct {
                                /* typedef u8 -> __u8 */ unsigned char locked;                /*     0     1 */
                                /* typedef u8 -> __u8 */ unsigned char pending;               /*     1     1 */
                        };                                                                    /*     0     2 */
                        struct {
                                /* typedef u16 -> __u16 */ short unsigned int locked_pending; /*     0     2 */
                                /* typedef u16 -> __u16 */ short unsigned int tail;           /*     2     2 */
                        };                                                                    /*     0     4 */
                };                                                                            /*     0     4 */
        } raw_lock;                                                                           /*     0     4 */

        /* size: 4, cachelines: 1, members: 1 */
        /* last cacheline: 4 bytes */
};
$
.fi

.P
When decoding OOPSes you may want to see the offsets and sizes in hexadecimal:
.PP
.nf
$ pahole --hex thread_struct
struct thread_struct {
        struct desc_struct         tls_array[3];         /*     0  0x18 */
        long unsigned int          sp;                   /*  0x18   0x8 */
        short unsigned int         es;                   /*  0x20   0x2 */
        short unsigned int         ds;                   /*  0x22   0x2 */
        short unsigned int         fsindex;              /*  0x24   0x2 */
        short unsigned int         gsindex;              /*  0x26   0x2 */
        long unsigned int          fsbase;               /*  0x28   0x8 */
        long unsigned int          gsbase;               /*  0x30   0x8 */
        struct perf_event *        ptrace_bps[4];        /*  0x38  0x20 */
        /* --- cacheline 1 boundary (64 bytes) was 24 bytes ago --- */
        long unsigned int          debugreg6;            /*  0x58   0x8 */
        long unsigned int          ptrace_dr7;           /*  0x60   0x8 */
        long unsigned int          cr2;                  /*  0x68   0x8 */
        long unsigned int          trap_nr;              /*  0x70   0x8 */
        long unsigned int          error_code;           /*  0x78   0x8 */
        /* --- cacheline 2 boundary (128 bytes) --- */
        struct io_bitmap *         io_bitmap;            /*  0x80   0x8 */
        long unsigned int          iopl_emul;            /*  0x88   0x8 */
        mm_segment_t               addr_limit;           /*  0x90   0x8 */
        unsigned int               sig_on_uaccess_err:1; /*  0x98: 0 0x4 */
        unsigned int               uaccess_err:1;        /*  0x98:0x1 0x4 */

        /* XXX 30 bits hole, try to pack */
        /* XXX 36 bytes hole, try to pack */

        /* --- cacheline 3 boundary (192 bytes) --- */
        struct fpu                 fpu;                  /*  0xc0 0x1040 */

        /* size: 4352, cachelines: 68, members: 20 */
        /* sum members: 4312, holes: 1, sum holes: 36 */
        /* sum bitfield members: 2 bits, bit holes: 1, sum bit holes: 30 bits */
};
$
.fi

.P
To find the biggest data structures in the Linux kernel:
.PP
.nf
$ pahole -s | sort -k2 -nr | head -5
cmp_data               290904 1
dec_datas              274520 1
cpu_entry_area         217088 0
pglist_data            172928 4
saved_cmdlines_buffer  131104 1
$
.fi
.P
The second column is the size in bytes and the third is the number of alignment holes in
that structure.
.P
Show data structures that have a raw spinlock and are related to the RCU mechanism:
.PP
.nf
$ pahole --contains raw_spinlock_t --prefix rcu
rcu_node
rcu_data
rcu_state
$
.fi
.P
To see that in context, combine it with \fIgrep\fR:
.PP
.nf
$ pahole rcu_state | grep raw_spinlock_t -B1 -A5
	/* --- cacheline 52 boundary (3328 bytes) --- */
	raw_spinlock_t             ofl_lock;             /*  3328     4 */

	/* size: 3392, cachelines: 53, members: 35 */
	/* sum members: 3250, holes: 7, sum holes: 82 */
	/* padding: 60 */
};
$
.fi
.P

.SH SEE ALSO
\fIeu-readelf\fR(1), \fIreadelf\fR(1), \fIobjdump\fR(1).
.P
\fIhttps://www.kernel.org/doc/ols/2007/ols2007v2-pages-35-44.pdf\fR.
.SH AUTHOR
\fBpahole\fR was written and is maintained by Arnaldo Carvalho de Melo <acme@kernel.org>.
.P
Thanks to Andrii Nakryiko and Martin KaFai Lau for providing the BTF encoder
and improving the codebase while making sure the BTF encoder works as needed
to be used in encoding the Linux kernel .BTF section from the DWARF info
generated by gcc. For that Andrii wrote a BTF deduplicator in libbpf that is
used by \fBpahole\fR.
.P
Please send bug reports to <dwarves@vger.kernel.org>.
.P
No\ subscription is required.