2009-02-11 15:19:46 +01:00
|
|
|
.\" Man page for pahole
|
|
|
|
.\" Arnaldo Carvalho de Melo, 2009
|
|
|
|
.\" Licensed under version 2 of the GNU General Public License.
|
2009-02-13 14:35:24 +01:00
|
|
|
.TH pahole 1 "February 13, 2009" "dwarves" "dwarves"
|
2009-02-11 15:19:46 +01:00
|
|
|
.\"
|
|
|
|
.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.
|
|
|
|
|
2009-02-13 14:52:58 +01:00
|
|
|
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.
|
|
|
|
|
2009-02-11 15:19:46 +01:00
|
|
|
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
|
2009-03-23 20:53:54 +01:00
|
|
|
others, the \fB.debug_info\fR ELF section. For CTF it is found in just one
|
2009-02-11 15:19:46 +01:00
|
|
|
ELF section, \fB.SUNW_ctf\fR.
|
|
|
|
|
|
|
|
The \fBdebuginfo\fR packages available in most Linux distributions are also
|
2009-02-13 14:52:58 +01:00
|
|
|
supported by \fBpahole\fR, where the debugging information is available in a
|
2009-02-11 15:19:46 +01:00
|
|
|
separate file.
|
|
|
|
|
|
|
|
By default, \fBpahole\fR shows the layout of all named structs in the files
|
|
|
|
specified.
|
|
|
|
|
|
|
|
.SH OPTIONS
|
|
|
|
pahole supports the following options.
|
|
|
|
|
|
|
|
.TP
|
pahole: Allow list of class names to be passed to -C/--class_name
CSV, and also supports file://class_list.txt as one of the entries
in the list, so:
[acme@doppio pahole]$ pahole -C str_node,strings build/libdwarves.so.1.0.0
struct strings {
void * tree; /* 0 8 */
struct gobuffer gb; /* 8 24 */
/* size: 32, cachelines: 1, members: 2 */
/* last cacheline: 32 bytes */
};
struct str_node {
struct rb_node rb_node; /* 0 24 */
const char * s; /* 24 8 */
/* size: 32, cachelines: 1, members: 2 */
/* last cacheline: 32 bytes */
};
[acme@doppio pahole]$
And also:
[acme@doppio pahole]$ pahole -C file://classes.txt,tag build/libdwarves.so.1.0.0
struct strings {
void * tree; /* 0 8 */
struct gobuffer gb; /* 8 24 */
/* size: 32, cachelines: 1, members: 2 */
/* last cacheline: 32 bytes */
};
struct tag {
struct list_head node; /* 0 16 */
uint16_t type; /* 16 2 */
uint16_t tag; /* 18 2 */
uint16_t visited:1; /* 20:15 2 */
uint16_t top_level:1; /* 20:14 2 */
/* XXX 14 bits hole, try to pack */
uint16_t recursivity_level; /* 22 2 */
void * priv; /* 24 8 */
/* size: 32, cachelines: 1, members: 7 */
/* bit holes: 1, sum bit holes: 14 bits */
/* last cacheline: 32 bytes */
};
struct str_node {
struct rb_node rb_node; /* 0 24 */
const char * s; /* 24 8 */
/* size: 32, cachelines: 1, members: 2 */
/* last cacheline: 32 bytes */
};
[acme@doppio pahole]$
Suggested-by: Zack Weinberg <zweinberg@mozilla.com>
Signed-off-by: Arnaldo Carvalho de Melo <acme@redhat.com>
2009-06-18 19:58:51 +02:00
|
|
|
.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)
|
2009-02-11 15:19:46 +01:00
|
|
|
|
|
|
|
.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.
|
|
|
|
|
2009-03-19 16:19:37 +01:00
|
|
|
.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".
|
|
|
|
|
2017-09-05 15:13:06 +02:00
|
|
|
.TP
|
|
|
|
.B \-\-hex
|
|
|
|
Print offsets and sizes in hexadecimal.
|
|
|
|
|
2009-02-11 15:19:46 +01:00
|
|
|
.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
|
2009-02-13 14:52:58 +01:00
|
|
|
suppressed.
|
2009-02-11 15:19:46 +01:00
|
|
|
|
|
|
|
.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.
|
|
|
|
|
2009-03-20 14:29:50 +01:00
|
|
|
.TP
|
|
|
|
.B \-\-flat_arrays
|
|
|
|
Flatten arrays, so that array[10][2] becomes array[20].
|
2019-04-03 18:08:02 +02:00
|
|
|
Useful when generating from both CTF/BTF and DWARF encodings
|
2009-03-20 14:29:50 +01:00
|
|
|
for the same binary for testing purposes.
|
|
|
|
|
2019-04-03 18:08:02 +02:00
|
|
|
.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.
|
|
|
|
|
2019-04-15 19:34:25 +02:00
|
|
|
.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.
|
|
|
|
|
2019-04-15 20:01:53 +02:00
|
|
|
.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.
|
|
|
|
|
2009-03-20 17:54:04 +01:00
|
|
|
.TP
|
|
|
|
.B \-\-fixup_silly_bitfields
|
|
|
|
Converts silly bitfields such as "int foo:32" to plain "int foo".
|
|
|
|
|
2009-02-11 15:19:46 +01:00
|
|
|
.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.
|
|
|
|
|
2009-02-13 14:35:24 +01:00
|
|
|
.SH NOTES
|
|
|
|
|
|
|
|
To enable the generation of debugging information in the Linux kernel build
|
2009-03-03 19:32:47 +01:00
|
|
|
process select CONFIG_DEBUG_INFO. This can be done using make menuconfig by
|
2009-02-13 14:35:24 +01:00
|
|
|
this path: "Kernel Hacking" -> "Kernel Debugging" -> "Compile the kernel with
|
|
|
|
debug info".
|
|
|
|
|
|
|
|
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).
|
|
|
|
|
2009-02-11 15:19:46 +01:00
|
|
|
.SH SEE ALSO
|
|
|
|
\fIeu-readelf\fR(1), \fIreadelf\fR(1), \fIobjdump\fR(1).
|
2009-02-13 14:52:58 +01:00
|
|
|
.P
|
2017-02-01 14:42:59 +01:00
|
|
|
\fIhttps://www.kernel.org/doc/ols/2007/ols2007v2-pages-35-44.pdf\fR.
|
2009-02-11 15:19:46 +01:00
|
|
|
.SH AUTHOR
|
|
|
|
\fBpahole\fR was written by Arnaldo Carvalho de Melo <acme@ghostprotocols.net>.
|
|
|
|
|
|
|
|
Please send bug reports to <dwarves@vger.kernel.org>.
|
2009-02-13 14:52:58 +01:00
|
|
|
.P
|
2009-02-11 15:19:46 +01:00
|
|
|
No\ subscription is required.
|