From: Claudiu Zissulescu Date: Thu, 20 Nov 2025 12:59:33 +0000 (+0200) Subject: gprofng: Add documentation on converting gmon files. X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=669c215363cc5500262f9c0773f3f09dd799903d;p=thirdparty%2Fbinutils-gdb.git gprofng: Add documentation on converting gmon files. Signed-off-by: Claudiu Zissulescu --- diff --git a/gprof/gprof.texi b/gprof/gprof.texi index c2a6a1029c8..772b9f46d25 100644 --- a/gprof/gprof.texi +++ b/gprof/gprof.texi @@ -429,6 +429,10 @@ to interpret the information in it. The @code{gprof} program prints a flat profile and a call graph on standard output. Typically you would redirect the output of @code{gprof} into a file with @samp{>}. +Note that @code{gprofng}, a more modern profiler which is also part of +binutils, can also read gmon files and provides more functionality +than @code{gprof}. + You run @code{gprof} like this: @smallexample diff --git a/gprofng/doc/Makefile.am b/gprofng/doc/Makefile.am index 8678f22e3a4..331b2686d1f 100644 --- a/gprofng/doc/Makefile.am +++ b/gprofng/doc/Makefile.am @@ -36,7 +36,8 @@ TEXINFO_TEX = . MAKEINFOHTML = $(MAKEINFO) --html --no-split man_MANS = gprofng.1 gprofng-archive.1 gprofng-collect-app.1 \ - gprofng-display-html.1 gprofng-display-src.1 gprofng-display-text.1 + gprofng-display-html.1 gprofng-display-src.1 gprofng-display-text.1 \ + gprofng-display-gmon.1 # Build the man page from the texinfo file # The sed command removes the no-adjust Nroff command so that @@ -54,6 +55,7 @@ gprofng-collect-app.1: $(srcdir)/gprofng-collect-app.texi gprofng-display-html.1: $(srcdir)/gprofng-display-html.texi gprofng-display-src.1: $(srcdir)/gprofng-display-src.texi gprofng-display-text.1: $(srcdir)/gprofng-display-text.texi +gprofng-display-gmon.1: $(srcdir)/gprofng-display-gmon.texi MAINTAINERCLEANFILES = gprofng.info $(man_MANS) EXTRA_DIST = $(man_MANS) version.texi diff --git a/gprofng/doc/Makefile.in b/gprofng/doc/Makefile.in index 32dd83d79ab..04c34c70129 100644 --- a/gprofng/doc/Makefile.in +++ b/gprofng/doc/Makefile.in @@ -382,7 +382,8 @@ gprofng_ug_TEXINFOS = fdl.texi gp-macros.texi TEXINFO_TEX = . MAKEINFOHTML = $(MAKEINFO) --html --no-split man_MANS = gprofng.1 gprofng-archive.1 gprofng-collect-app.1 \ - gprofng-display-html.1 gprofng-display-src.1 gprofng-display-text.1 + gprofng-display-html.1 gprofng-display-src.1 gprofng-display-text.1 \ + gprofng-display-gmon.1 MAINTAINERCLEANFILES = gprofng.info $(man_MANS) EXTRA_DIST = $(man_MANS) version.texi @@ -897,6 +898,7 @@ gprofng-collect-app.1: $(srcdir)/gprofng-collect-app.texi gprofng-display-html.1: $(srcdir)/gprofng-display-html.texi gprofng-display-src.1: $(srcdir)/gprofng-display-src.texi gprofng-display-text.1: $(srcdir)/gprofng-display-text.texi +gprofng-display-gmon.1: $(srcdir)/gprofng-display-gmon.texi info: $(man_MANS) diff --git a/gprofng/doc/gprofng-display-gmon.texi b/gprofng/doc/gprofng-display-gmon.texi new file mode 100644 index 00000000000..463f18bcd5c --- /dev/null +++ b/gprofng/doc/gprofng-display-gmon.texi @@ -0,0 +1,213 @@ +@c ---------------------------------------------------------------------------- +@c This is the Texinfo source file for the gprofng-display-gmon man page. +@c +@c Author: Claudiu Zissulescu +@c ---------------------------------------------------------------------------- +@ifset man +\input texinfo @c -*-texinfo-*- +@setfilename gprofng-display-gmon +@settitle Convert a gmon profile data to a gprofng experiment. +@include gp-macros.texi +@end ifset + +@c ---------------------------------------------------------------------------- +@c This is from the man-pages(7) man page +@c +@c "The list below shows conventional or suggested sections. Most manual pages +@c should include at least the highlighted sections. Arrange a new manual +@c page so that sections are placed in the order shown in the list." +@c +@c NAME +@c SYNOPSIS +@c CONFIGURATION [Normally only in Section 4] +@c DESCRIPTION +@c OPTIONS [Normally only in Sections 1, 8] +@c EXIT STATUS [Normally only in Sections 1, 8] +@c RETURN VALUE [Normally only in Sections 2, 3] +@c ERRORS [Typically only in Sections 2, 3] +@c ENVIRONMENT +@c FILES +@c VERSIONS [Normally only in Sections 2, 3] +@c ATTRIBUTES [Normally only in Sections 2, 3] +@c CONFORMING TO +@c NOTES +@c BUGS +@c EXAMPLES +@c AUTHORS [Discouraged] +@c REPORTING BUGS [Not used in man-pages] +@c COPYRIGHT [Not used in man-pages] +@c SEE ALSO +@c +@c This is what the texi2pod.pl tool recognizes: +@c +@c for $sect (qw(NAME SYNOPSIS TARGET DESCRIPTION OPTIONS ENVIRONMENT FILES +@c BUGS NOTES FOOTNOTES SEEALSO AUTHOR COPYRIGHT)) { +@c +@c What is interesting is that it places "SEE ALSO" before "COPYRIGHT", which +@c makes sense and adhered to for the other formats. +@c ---------------------------------------------------------------------------- + +@c ---------------------------------------------------------------------------- +@c NAME section +@c ---------------------------------------------------------------------------- + +@ManPageStart{NAME} +@c man begin NAME + +gprofng-display-gmon - Convert a given @file{gmon.out} file to gprofng +experiments. + +@c man end +@ManPageEnd{} + +@c ---------------------------------------------------------------------------- +@c SYNOPSIS section +@c ---------------------------------------------------------------------------- + +@ManPageStart{SYNOPSIS} +@c man begin SYNOPSIS + +@command{gprofng display gmon} [@var{option(s)}] [@var{target} [@var{gmon-file}]] + +@c man end +@ManPageEnd{} + +@c ---------------------------------------------------------------------------- +@c DESCRIPTION section +@c ---------------------------------------------------------------------------- + +@ManPageStart{DESCRIPTION} +@c man begin DESCRIPTION + +Reads the @file{gmon.out} file and the profiled executable. With the +executable, we can reconstruct information about the profiled symbols +and the memory map layout. The @file{gmon.out} file provides details +about the execution duration for each symbol, as well as data used to +build the call graph. The profile data is taken from the call graph +profile file (@file{gmon.out} default) which is created by programs +that are compiled with profile arches (i.e., the @samp{-pg} option of +@code{cc}). + +For example, this command converts the profile data (@file{gmon.out}) +for an executable called @samp{a.out} and stores the data collected in +an experiment directory with the name @samp{example.er}. + +@smallexample +$ gprofng display gmon -o example.er ./a.out gmon.out +@end smallexample + +@c man end +@ManPageEnd{} + +@c ---------------------------------------------------------------------------- +@c OPTIONS section +@c ---------------------------------------------------------------------------- + +@ManPageStart{OPTIONS} +@c man begin OPTIONS + +@table @gcctabopt + +@item --version +@ifclear man +@IndexSubentry{Options, @code{--version}} +@end ifclear + +Print the version number and exit. + +@item --help +@ifclear man +@IndexSubentry{Options, @code{--help}} +@end ifclear + +Print usage information and exit. + +@item -o @var{} +@ifclear man +@IndexSubentry{Options, @code{-o}} +@end ifclear + +Specify the name for the experiment directory. The name has to end with +@samp{.er} and may contain an absolute path (e.g. @file{/tmp/experiment.er}). +An existing experiment with the same name will not be overwritten. + +@item -O @var{} +@ifclear man +@IndexSubentry{Options, @code{-O}} +@end ifclear + +This is the same as the @samp{-o} option, but unlike this option, silently +overwrites an existing experiment directory with the same name. + +@end table + +@c man end +@ManPageEnd{} + +@c ---------------------------------------------------------------------------- +@c NOTES section +@c ---------------------------------------------------------------------------- + +@ManPageStart{NOTES} +@c man begin NOTES + +Any executable in the ELF (Executable and Linkable Format) object +format can be used for profiling with gprofng. If @var{target} is +missing, the default executable name is @file{a.out}. If +@var{gmon-file} is missing, the default profile data file name is +@file{gmon.out}. + +@c man end +@ManPageEnd{} + +@c ---------------------------------------------------------------------------- +@c SEEALSO section +@c ---------------------------------------------------------------------------- + +@ManPageStart{SEE ALSO} +@c man begin SEEALSO + +gprofng(1), +gprofng-archive(1), +@c -- gprofng-display-gui(1), +gprofng-display-html(1), +gprofng-display-src(1), +gprofng-display-text(1) + +@iftex +@vspace{1} +@end iftex + +The user guide for gprofng is maintained as a Texinfo manual. If the +@command{info} and @command{gprofng} programs are correctly installed, the +command @command{info gprofng} should give access to this document. + +@c man end +@ManPageEnd{} + +@c ---------------------------------------------------------------------------- +@c COPYRIGHT section +@c ---------------------------------------------------------------------------- + +@ManPageStart{COPYRIGHT} +@c man begin COPYRIGHT + +Copyright @copyright{} 2025 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 +or any later version published by the Free Software Foundation; +with no Invariant Sections, with no Front-Cover Texts, and with no +Back-Cover Texts. A copy of the license is included in the +section entitled ``GNU Free Documentation License''. + +@c man end +@ManPageEnd{} + +@c ---------------------------------------------------------------------------- +@c If this text is used for a man page, exit. Otherwise we need to continue. +@c ---------------------------------------------------------------------------- + +@ifset man +@bye +@end ifset diff --git a/gprofng/doc/gprofng.texi b/gprofng/doc/gprofng.texi index 67f6167d5ab..04dce20dc47 100644 --- a/gprofng/doc/gprofng.texi +++ b/gprofng/doc/gprofng.texi @@ -299,6 +299,9 @@ be installed seperately. @item gprofng display src Display source or disassembly with compiler annotations. +@item gprofng display gmon +Convert a given @file{gmon.out} file to gprofng experiments. + @item gprofng archive Include binaries and source code in an experiment directory. @@ -329,6 +332,7 @@ gprofng-collect-app(1), gprofng-display-html(1), gprofng-display-src(1), gprofng-display-text(1) +gprofng-display-gmon(1) @iftex @vspace{1} diff --git a/gprofng/doc/gprofng_ug.texi b/gprofng/doc/gprofng_ug.texi index f23f7b379ee..7b04a3f7c5a 100644 --- a/gprofng/doc/gprofng_ug.texi +++ b/gprofng/doc/gprofng_ug.texi @@ -157,6 +157,7 @@ The gprofng Man Pages * Man page for @command{gprofng display text}:: The man page for gprofng display text. * Man page for @command{gprofng display html}:: The man page for gprofng display html. * Man page for @command{gprofng display src}:: The man page for gprofng display src. +* Man page for @command{gprofng display gmon}:: The man page for gprofng display gmon. * Man page for @command{gprofng archive}:: The man page for gprofng archive. @c -- Index @@ -4426,6 +4427,14 @@ In this appendix the man pages for the various @ProductName{} tools are listed. @include gprofng-display-src.texi +@c -- A new node -------------------------------------------------------------- +@page +@node Man page for @command{gprofng display gmon} +@section Man page for @command{gprofng display gmon} +@c ---------------------------------------------------------------------------- + +@include gprofng-display-gmon.texi + @c -- A new node -------------------------------------------------------------- @page @node Man page for @command{gprofng archive}