man-pages/pahole.1 - platform/external/dwarves - Git at Google

 .\" Man page for pahole
 .\" Arnaldo Carvalho de Melo, 2009
 .\" Licensed under version 2 of the GNU General Public License.
 .TH pahole 1 "February 13, 2009" "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.

 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.

 .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" -> "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).

 .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 by Arnaldo Carvalho de Melo <acme@ghostprotocols.net>.

 Please send bug reports to <dwarves@vger.kernel.org>.
 .P
 No\ subscription is required.
	.\" Man page for pahole
	.\" Arnaldo Carvalho de Melo, 2009
	.\" Licensed under version 2 of the GNU General Public License.
	.TH pahole 1 "February 13, 2009" "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.

	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.

	.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" -> "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).

	.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 by Arnaldo Carvalho de Melo <acme@ghostprotocols.net>.

	Please send bug reports to <dwarves@vger.kernel.org>.
	.P
	No\ subscription is required.