head 1.1; branch 1.1.1; access; symbols binutils-2-46:1.1.1.2 binutils-2-45:1.1.1.1 FSF:1.1.1; locks; strict; comment @# @; 1.1 date 2025.08.25.14.43.14; author christos; state Exp; branches 1.1.1.1; next ; commitid aUBKFf4jmEzPv78G; 1.1.1.1 date 2025.08.25.14.43.14; author christos; state Exp; branches; next 1.1.1.2; commitid aUBKFf4jmEzPv78G; 1.1.1.2 date 2026.02.11.19.50.17; author christos; state Exp; branches; next ; commitid vybCSY05tblOMZtG; desc @@ 1.1 log @Initial revision @ text @@@c ---------------------------------------------------------------------------- @@c This is the Texinfo source file for the gprofng-display-text man page. @@c @@c Author: Ruud van der Pas @@c ---------------------------------------------------------------------------- @@ifset man \input texinfo @@c -*-texinfo-*- @@setfilename gprofng-display-text @@settitle Display the performance data in plain text format @@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-text - Display the performance data in plain text format @@c man end @@ManPageEnd{} @@c ---------------------------------------------------------------------------- @@c SYNOPSIS section @@c ---------------------------------------------------------------------------- @@ManPageStart{SYNOPSIS} @@c man begin SYNOPSIS @@command{gprofng display text} [@@var{option(s)}] [@@var{commands}] [-script @@var{script-file}] @@var{experiment(s)} @@c man end @@ManPageEnd{} @@c ---------------------------------------------------------------------------- @@c DESCRIPTION section @@c ---------------------------------------------------------------------------- @@ManPageStart{DESCRIPTION} @@c man begin DESCRIPTION Print a plain text version of the various displays supported by gprofng. The input consists of one or more experiment directories. Through commands, the user controls the output. There is a rich set of commands to control the display of the data. The @@samp{NOTES} section lists the most common ones. The gprofng user guide lists all the commands supported. Commands specified on the command line need to be prepended with the dash ('-') symbol. In this example, a function overview will be shown, followed by the source code listing of function @@samp{my-func}, annotated with the performance metrics that have been recorded during the data collection and stored in experiment directory @@samp{my-exp.er}: @@smallexample $ gprofng display text -functions -source my-func my-exp.er @@end smallexample Instead of, or in addition to, specifying these commands on the command line, commands may also be included in a file called the @@var{script-file}. Note that the commands are processed and interpreted from left to right, @@emph{so the order matters}. If this tool is invoked without options, commands, or a script file, it starts in interpreter mode. The user can then issue the commands interactively. The session is terminated with the @@command{exit} command in the interpreter. @@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 -script @@var{script-file} @@ifclear man @@IndexSubentry{Options, @@code{-script}} @@IndexSubentry{Commands, @@code{script}} @@end ifclear Execute the commands stored in the script file. This feature may be combined with commands specified at the command line. @@end table @@c man end @@ManPageEnd{} @@c ---------------------------------------------------------------------------- @@c NOTES section @@c ---------------------------------------------------------------------------- @@ManPageStart{NOTES} @@c man begin NOTES Many commands are supported. Below, the more common ones are listed in mostly alphabetical order, because sometimes it is more logical to swap the order of two entries. @@ifset man There are many more commands. These are documented in the user guide. @@end ifset @@table @@code @@item callers-callees @@ifclear man @@IndexSubentry{Options, @@code{-callers-callees}} @@IndexSubentry{Commands, @@code{callers-callees}} @@end ifclear In a callers-callees panel, it is shown which function(s) call the target function (the @@emph{callers}) and what functions it is calling (the @@emph{callees}). This command prints the callers-callees panel for each of the functions, in the order specified by the function sort metric. @@item calltree @@ifclear man @@IndexSubentry{Options, @@code{-calltree}} @@IndexSubentry{Commands, @@code{calltree}} @@end ifclear Display the dynamic call graph from the experiment, showing the hierarchical metrics at each level. @@item compare @@{on | off | delta | ratio@@} @@ifclear man @@IndexSubentry{Options, @@code{-compare}} @@IndexSubentry{Commands, @@code{compare}} @@end ifclear By default, the results for multiple experiments are aggregated. This command changes this to enable the comparison of experiments for certain views (e.g. the function view). The first experiment specified is defined to be the reference. The following options are supported: @@table @@code @@item on For each experiment specified on the command line, print the values for the metrics that have been activated for the experiment. @@item off Disable the comparison of experiments. This is the default. @@item delta Print the values for the reference experiment. The results for the other experiments are shown as a delta relative to the reference (current-reference). @@item ratio Print the values for the reference experiment. The results for the other experiments are shown as a ratio relative to the reference (current/reference). @@end table @@item disasm @@var{function-name} @@ifclear man @@IndexSubentry{Options, @@code{-disasm}} @@IndexSubentry{Commands, @@code{disasm}} @@end ifclear List the source code and instructions for the function specified. The instructions are annotated with the metrics used. @@item fsingle @@var{function-name} [@@samp{n}] @@ifclear man @@IndexSubentry{Options, @@code{-fsingle}} @@IndexSubentry{Commands, @@code{fsingle}} @@end ifclear Write a summary panel for the specified function. The optional parameter @@var{n} is needed for those cases where several functions have the same name. @@item fsummary @@ifclear man @@IndexSubentry{Options, @@code{-fsummary}} @@IndexSubentry{Commands, @@code{fsummary}} @@end ifclear Write a summary panel for each function in the function list. @@item functions @@ifclear man @@IndexSubentry{Options, @@code{-functions}} @@IndexSubentry{Commands, @@code{functions}} @@end ifclear Display a list of all functions executed. For each function the used metrics (e.g. the CPU time) are shown. @@item header @@ifclear man @@IndexSubentry{Options, @@code{-header}} @@IndexSubentry{Commands, @@code{header}} @@end ifclear Shows several operational characteristics of the experiment(s) specified on the command line. @@item limit @@var{n} @@ifclear man @@IndexSubentry{Options, @@code{-limit}} @@IndexSubentry{Commands, @@code{limit}} @@end ifclear Limit the output to @@var{n} lines. @@item lines @@ifclear man @@IndexSubentry{Options, @@code{-lines}} @@IndexSubentry{Commands, @@code{lines}} @@end ifclear Write a list of source lines and their metrics, ordered by the current sort metric. @@item metric_list @@ifclear man @@IndexSubentry{Options, @@code{-metric_list}} @@IndexSubentry{Commands, @@code{metric_list}} @@end ifclear Display the currently selected metrics in the function view and a list of all the metrics available for the target experiment(s). @@item metrics @@var{metric-spec} @@ifclear man @@IndexSubentry{Options, @@code{-metrics}} @@IndexSubentry{Commands, @@code{metrics}} @@end ifclear Define the metrics to be displayed in the function and callers-callees overviews. The @@var{metric-spec} can either be the keyword @@samp{default} to restore the default metrics selection, or a colon separated list with metrics. @@ifclear man @@IndexSubentry{Hardware event counters, @@code{hwc} metric} @@end ifclear A special metric is @@code{hwc}. It automatically expands to the active set of hardware event counters used in the experiment(s). @@ifclear man @@IndexSubentry{Hardware event counters, @@code{IPC} metric} @@IndexSubentry{Hardware event counters, @@code{CPI} metric} @@end ifclear If both instructions and clock cycles have been measured, the @@code{CPI} and @@code{IPC} metrics can be used to see the Clockcycles Per Instruction and Instructions Per Clockcyle values, respectively. The gprofng user guide has more details how to define metrics. @@item name @@{short | long | mangled@@}[:@@{soname | nosoname@@}] @@ifclear man @@IndexSubentry{Options, @@code{-name}} @@IndexSubentry{Commands, @@code{name}} @@end ifclear Specify whether to use the short, long, or mangled form of function names. Optionally, the load object that the function is part of can be included in the output by adding the @@emph{soname} keyword. It can also be ommitted (@@emph{nosoname}), which is the default. Whether there is an actual difference between these types of names depends on the language. Note that there should be no (white)space to the left and right of the colon (@@samp{:}). This option should not be confused with the keyword @@samp{name} in a metric definition, which is used to specify that the names of functions should be shown in the function overview. @@item overview @@ifclear man @@IndexSubentry{Options, @@code{-overview}} @@IndexSubentry{Commands, @@code{overview}} @@end ifclear Shows a summary of the recorded performance data for the experiment(s) specified on the command line. @@item pcs @@ifclear man @@IndexSubentry{Options, @@code{-pcs}} @@IndexSubentry{Commands, @@code{pcs}} @@end ifclear Write a list of program counters (PCs) and their metrics, ordered by the current sort metric. @@item sort @@var{metric-spec} @@ifclear man @@IndexSubentry{Options, @@code{-sort}} @@IndexSubentry{Commands, @@code{sort}} @@end ifclear Sort the function list on the @@var{metric-spec} given. @@IndexSubentry{Sort, Reverse order} The data can be sorted in reverse order by prepending the metric definition with a minus (@@samp{-}) sign. @@noindent For example @@command{sort -e.totalcpu}. @@IndexSubentry{Sort, Reset to default} A default metric for the sort operation has been defined and since this is a persistent command, this default can be restored with @@code{default} as the key (@@command{sort default}). @@item source @@var{function-name} @@ifclear man @@IndexSubentry{Options, @@code{-source}} @@IndexSubentry{Commands, @@code{source}} @@end ifclear List the source code for the function specified, annotated with the metrics used. @@item viewmode @@{user | expert | machine@@} @@ifclear man @@IndexSubentry{Options, @@code{-viewmode}} @@IndexSubentry{Commands, @@code{viewmode}} @@end ifclear This command is only relevant for Java programs. For all other languages supported, the viewmode setting has no effect. The following options are supported: @@table @@code @@item user Show the Java call stacks for Java threads, but do not show housekeeping threads. The function view includes a function called @@samp{}. This represents the aggregated time from non-Java threads. In case the JVM software does not report a Java call stack, time is reported against the function @@samp{}. @@item expert Show the Java call stacks for Java threads when the user Java code is executed, and machine call stacks when JVM code is executed, or when the JVM software does not report a Java call stack. Show the machine call stacks for housekeeping threads. @@item machine Show the actual native call stacks for all threads. This is the view mode for C, C++, and Fortran. @@end table @@end table @@c man end @@ManPageEnd{} @@c ---------------------------------------------------------------------------- @@c SEEALSO section @@c ---------------------------------------------------------------------------- @@ManPageStart{SEE ALSO} @@c man begin SEEALSO gprofng(1), gprofng-archive(1), gprofng-collect-app(1), @@c -- gprofng-display-gui(1), gprofng-display-html(1), gprofng-display-src(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{} 2022-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 @ 1.1.1.1 log @Import binutils 2.45 (previous was 2.42) 2.45 Release Notes ------------------ Assembler: All sframe information generated by the assembler is now in compliance with the SFrame V2 specification. The assembler now supports .errif and .warnif directives, permitting user-controlled diagnostics with conditionals that are evaluated only at the end of assembly. The assembler predefines the symbol "GAS(version)". The assembler now supports the generation of SFrame stack trace information (.sframe) from CFI directives on s390 64-bit (s390x). For RISC-V, the ".option arch, -ext" format is deprecated due to its controversial use. For RISC-V, stop generating mapping symbols $x and replace with $x. The $x was defined to have the same ISA as previous $x, but now is defined to have the same ISA as elf architecture attribute. Once both used .option arch/rvc/norvc/push/pop directives (some code have different architectures with file attribute) and data directives in text, then the file need to be rebuilt since 2.45. The assembler supports the latest architecture extensions for the RISC-V, LoongArch and AArch64 architectures. Linker: The linker's --stats option can take an optional argument which if used is interpreted as a filename into which resource usage information should be stored. As an alternative mechanism the LD_STATS environment variable can also be used to achieve the same results. Resource usage information for various phases of the linking operation is now included in the report. If a map file is being produced then the information is also included there. The --no-stats option can be used to disable stat reporting, should it have been enabled. On s390 64-bit (s390x), generate SFrame stack trace information (.sframe) for the linker generated .plt section. On s390 32-bit, generate ".eh_frame" unwind information for the linker generated .plt section. Both features are enabled by default and can be disabled using linker option --no-ld-generated-unwind-info. On RISC-V, add new PLT formats, and GNU property merge rules for zicfiss and zicfilp extensions. On AVR, the default linker scripts now assert that the .progmem sections don't extend past 0xffff since they are accessed by means of LPM. For data in program memory that may be located past 0xffff, a .progmemx section should be used. On LoongArch, linker relaxation time complexity is no longer quadratic with respect to relocation counts. Linking time of large software should be improved. In addition R_LARCH_32_PCREL records are now checked for overflow. Other binary utilities: New versioned release of libsframe: libsframe.so.2. This release introduces versioned symbols with version node name LIBSFRAME_2.0. Some new symbols have been added to support the new flag SFRAME_F_FDE_FUNC_START_PCREL and retrieving flags from SFrame decoder and encoder objects: - Addition of sframe_decoder_get_flags, sframe_decoder_get_offsetof_fde_start_addr, sframe_encoder_get_flags, sframe_encoder_get_offsetof_fde_start_addr. This release also includes backward-incompatible ABI changes: - Removal of sframe_get_funcdesc_with_addr. - Change in the behavior of sframe_decoder_get_funcdesc_v2, sframe_encoder_add_funcdesc_v2 and sframe_encoder_write. For SFrame stack trace format, the function start address in each SFrame FDE has a changed encoding: The 32-bit signed integer now holds the offset of the start PC of the associated function from the sfde_func_start_address field itself (instead of the earlier where it was the offset from the start of the SFrame section itself). All SFrame sections generated by gas and ld now default to this new encoding, setting the (new) SFRAME_F_FDE_FUNC_START_PCREL flag. Relocatable SFrame links are now fixed. Readelf now recognizes RISC-V GNU_PROPERTY_RISCV_FEATURE_1_CFI_SS and GNU_PROPERTY_RISCV_FEATURE_1_CFI_LP_UNLABELED for zicfiss and zicfilp extensions. The LoongArch disassembler now properly accepts multiple disassembly options given by -M, such as "-M no-aliases,numeric". (Previously only the first option took effect.) 2.44 Release Notes ------------------ Assembler: Support for new architecture extensions for AArch64, Risc-V and x86. Linker: The default maximum page size was changed from 16KiB to 64KiB for LoongArch. This now supports mixed LTO and non-LTO object files in relocatable output. The ELF forms of the linker support a --image-base= option for compatibility with LLD. The --build-id= option now accepts an argument of "xx" which enables the use of the xxhash library. This produces a 128-bit hash and is 2-4x faster than md5 or sha1. The ELF linker option --package-metadata supports percent-encoded and %[string] encoded JSON payloads. Disassembler: The RISC-V disassembler now supports -M,max option like QEMU to dump instruction without checking architecture support as usual. GprofNG: Support added for hardware event counters for Neoverse-N1, Ampere-1, and Appliedmicro processors. Support for the Nios II target has been removed. 2.43 Release Notes ------------------ Assembler: * Add a .base64 directive to the assembler which allows base64 encoded binary data to be provided as strings. * Assembler macros as well as the bodies of .irp / .irpc / .rept can now use the syntax \+ to access the number of times a given macro has been executed. This is similar to the already existing \@@ syntax, except that the count is maintained on a per-macro basis. * References to FB and dollar labels, when supported, are no longer permitted in a radix other than 10. (Note that definitions of such labels were already thus restricted, except that leading zeroes were permitted). Linker: * Add support for DT_RELR type compressed runtime relocations for the AArch64 and LoongArch architectures. * Add --rosegment option which changes the -z separate-code option so that only one read-only segment is created (instead of two). * Add --section-ordering-file option to add extra mapping of input sections to output sections. * Add -plugin-save-temps to store plugin intermediate files permanently. Utilities: * Readelf will now display DT_RELR relocations in full detail. * Readelf now has a -j/--display-section option which takes the name or index of a section and displays its contents according to its type. The option can be used multiple times on the command line to display multiple sections. * When objdump or readelf are used to display the contents of a .eh_frame section they will now also display the contents of the .eh_frame_hdr section, if present. Gprofng: * Improved the support for hardware event counters: - Re-designed and streamlined the implementation. - Defined a common set of events for ARM processors. - Added specific events for AMD ZEN3 / ZEN4, and Intel Ice Lake processors. * Added a minimal support for RISC-V. General: * Target specific improvements for many architectures. @ text @@ 1.1.1.2 log @Import binutils-2.46.0 (previous was 2.45) Changes in 2.45: * New versioned release of libsframe: libsframe.so.2. This release introduces versioned symbols with version node name LIBSFRAME_2.0. Some new symbols have been added to support the new flag SFRAME_F_FDE_FUNC_START_PCREL and retrieving flags from SFrame decoder and encoder objects: - Addition of sframe_decoder_get_flags, sframe_decoder_get_offsetof_fde_start_addr, sframe_encoder_get_flags, sframe_encoder_get_offsetof_fde_start_addr. This release also includes backward-incompatible ABI changes: - Removal of sframe_get_funcdesc_with_addr. - Change in the behavior of sframe_decoder_get_funcdesc_v2, sframe_encoder_add_funcdesc_v2 and sframe_encoder_write. * On s390 64-bit (s390x), gas, ld, objdump, and readelf now support generating and processing SFrame V2 stack trace information (.sframe). The assembler generates SFrame info from CFI directives with option "--gsframe". The linker generates SFrame info for the linker-generated .plt section and merges all .sframe sections. Both objdump and readelf dump SFrame info with option "--sframe[=]". * For SFrame stack trace format, the function start address in each SFrame FDE has a changed encoding: The 32-bit signed integer now holds the offset of the start PC of the associated function from the sfde_func_start_address field itself (instead of the earlier where it was the offset from the start of the SFrame section itself). All SFrame sections generated by gas and ld now default to this new encoding, setting the (new) SFRAME_F_FDE_FUNC_START_PCREL flag. Relocatable SFrame links are now fixed. * Readelf now recognizes RISC-V GNU_PROPERTY_RISCV_FEATURE_1_CFI_SS and GNU_PROPERTY_RISCV_FEATURE_1_CFI_LP_UNLABELED for zicfiss and zicfilp extensions. * For RISC-V dis-assembler, the definition of mapping symbol $x is changed, so the file needs to be rebuilt since 2.45 once used .option arch directives. * The LoongArch disassembler now properly accepts multiple disassembly options given by -M, such as "-M no-aliases,numeric". (Previously only the first option took effect.) @ text @d440 1 a440 1 Copyright @@copyright{} 2022-2026 Free Software Foundation, Inc. @