Generating image-related information

RealView^® Compilation Tools for µVision Linker and Utilities Guide

Version 3.1

Home > The Linker Command Syntax > armlink command syntax > Generating image-related information

2.2.11. Generating image-related information

With the exception of ‑‑callgraph, the linker prints the information you request on the standard output stream, stdout, by default.You can redirect the information to a text file using the ‑‑list command-line option.

These options control how to extract and present information about the image:

‑‑[no_]callgraph

‑‑callgraph creates a static callgraph of functions. This is saved in the same directory as the generated image. The callgraph gives definition and reference information for all functions in the image.

Note

Any functions defined in the assembler files must have the appropriate PROC/ENDP and FRAME PUSH/POP directives if the linker is to calculate the function stack usage.

For each function func the linker lists the:

processor state for which the function is compiled (ARM or Thumb)
set of functions that call func
set of functions that are called by func
number of times the address of func is used in the image.

In addition, the callgraph identifies functions that are:

called through interworking veneers
defined outside the image
permitted to remain undefined (weak references).

The static callgraph also gives information about stack usage. It lists the:

size of the stack frame used by each function
maximum size of the stack used by the function over any call sequence, that is, over any acyclic chain of function calls.

If there is a cycle, or if the linker detects a function with no stack size information in the call chain, + Unknown is added to the stack usage. A reason is added to indicate why stack usage is unknown.

The linker reports missing stack frame information if there is no debug frame information for the function.

For indirect functions, the linker cannot reliably determine which function made the indirect call. This might affect how the maximum stack usage is calculated for a call chain. The linker lists all function pointers used in the image.

Use frame directives in assembly language code to describe how your code uses the stack. These directives ensure that debug frame information is present for debuggers to perform stack unwinding or profiling.

See the chapter describing the directives reference in the Assembler Guide for more information on how stack usage is determined.

‑‑callgraph_file=filename

Controls the output name filename of the callgraph. For example: ‑‑callgraph_file=myfile

The default filename is the same as the image. The output format is controlled by the ‑‑callgraph_output=fmt option.

‑‑callgraph_output=fmt

Controls the output format of the callgraph, where fmt can be one of the following:

html: Outputs the callgraph in html format. This is the default.
text: Outputs the callgraph in plain text format.

‑‑cgfile=type

Controls what is included in the callgraph, where type can be one of the following:

all: Includes symbols from all files. This is the default.
user: Includes only symbols from user defined objects and libraries.
system: Includes only symbols from system libraries.

‑‑cgsymbol=type

Controls what is included in the callgraph, where type can be one of the following:

all: Includes both local and global symbols. This is the default.
locals: Includes only local symbols.
globals: Includes only global symbols.

‑‑cgundefined=type

Controls what is included in the callgraph, where type can be one of the following:

all: Includes both function entries and calls to undefined weak references. This is the default.
entries: Includes function entries for undefined weak references.
calls: Includes calls to undefined weak references.
none: Omits all undefined weak references from the output.

‑‑feedback file

Generates a feedback file, for the next time a file is compiled, to inform the compiler about unused functions.

When you next compile the file, use the compiler option ‑‑feedback file to specify the feedback file to use. Unused functions are placed in their own sections for possible future elimination by the linker. For information on how to use the feedback file, see Linker feedback.

‑‑feedback_image option

Changes the behavior of the linker when writing a feedback file. Use this option to produce a feedback file where an executable ELF image cannot normally be created. For example, use --feedback_image noerrors if your code does not fit into the region limits described in your scatter file before unused functions are removed.

Where option can be one of the following:

none: Uses the scatter-loading file. Disables region overlap and region size overflow messages. Does not write an ELF image. Error messages are still produced if a region overflows the 32-bit address space.
noerrors: Uses the scatter-loading file. Warns on region overlap and region size overflow messages. Writes an ELF image, which might not be executable. Error messages are still produced if a region overflows the 32-bit address space.
simple: Ignores the scatter-loading file. Disables ROPI/RWPI errors and warnings. Writes an ELF image, which might not be executable.
full: Enables all error and warning messages and writes a valid ELF image. This is the default option.

‑‑info topics

Prints information about specified topics, where topics is a comma-separated list of topic keywords. A topic keyword can be one of the following:

architecture

Summarizes the image architecture by listing the CPU, FPU and byte order.

common

Lists all common sections that are eliminated from the image. Using this option implies ‑‑info common,totals.

debug

Lists all rejected input debug sections that are eliminated from the image as a result of using ‑‑remove. Using this option implies ‑‑info debug,totals.

exceptions

Gives information on exception table generation and optimization.

inline

Lists all functions that are inlined by the linker, and the total number of inlines if ‑‑inline is used. For more information on branch inlining see Branch inlining.

inputs

Lists the input symbols, objects and libraries.

libraries

Lists the full path name of every library automatically selected for the link stage.

You can use this option with a modifier, ‑‑info_lib_prefix, to display information about a specific library. For example, use the following options to identify the floating-point library used by the linker: ‑‑info libraries ‑‑info_lib_prefix=f.

sizes

Lists the Code and Data (RO Data, RW Data, ZI Data, and Debug Data) sizes for each input object and library member in the image. Using this option implies ‑‑info sizes,totals.

stack

Lists the stack usage of all global symbols.

summarysizes

Summarizes the Code and Data sizes of the image.

summarystack

Summarizes the stack usage of all global symbols.

tailreorder

Lists all the tail calling sections that are moved above their targets, as a result of using ‑‑tailreorder. For more information on handling tail calling sections see Branch inlining.

totals

Lists the totals of the Code and Data (RO Data, RW Data, ZI Data, and Debug Data) sizes for input objects and libraries.

unused

Lists all unused sections that are eliminated from the image as a result of using ‑‑remove.

veneers

Lists the linker-generated veneers. See Veneer generation for more information.

veneercallers

Lists the linker-generated veneers with additional information about the callers to each veneer. Use with --verbose to list each call individually. See Veneer generation for more information.

The output from ‑‑info sizes,totals always includes the padding values in the totals for input objects and libraries.

If you are using RW data compression (the default), or if you have specified a compressor using the ‑‑datacompressor id option, the output from ‑‑info sizes,totals includes an entry under Grand Totals to reflect the true size of the image.

Note

Spaces are not permitted between keywords in a list. For example, you can enter ‑‑info sizes,totals but not ‑‑info sizes, totals.

See Getting information about images for more information.

‑‑[un]mangled

Instructs the linker to display mangled or unmangled C++ symbol names in diagnostic messages, and in listings produced by the ‑‑xref, ‑‑xreffrom, ‑‑xrefto, and ‑‑symbols options.

‑‑unmangled is the default. This means that the linker unmangles C++ symbol names so that they are displayed as they appear in your source code.

If ‑‑mangled is selected, the linker does not unmangle C++ symbol names. Therefore, symbol names are displayed as they appear in the object symbol tables.

‑‑[no_]map

‑‑map creates an image map. The map contains the address and the size of each load region, execution region, and input section in the image, including linker-generated input sections.

‑‑[no_]symbols

‑‑symbols lists each local and global symbol used in the link step, and its value.

Note

This does not include mapping symbols. Use ‑‑list_mapping_symbols to include mapping symbols in the output.

‑‑[no_]list_mapping_symbols

‑‑list_mapping_symbols includes mapping symbols in the output produced by ‑‑symbols. For example:

$a: ARM code
$t: Thumb code
$d: data.

Mapping symbols are used to flag transitions between ARM code, Thumb code, and data. See ELF for the ARM Architecture (AAELF) for more information.

‑‑symdefs file

Creates a file containing the global symbol definitions from the output image.

By default, all global symbols are written to the symdefs file. If a symdefs file called file already exists, the linker restricts its output to the symbols already listed in this file.

Note

If you do not want this behavior, be sure to delete any existing symdefs file before the link step.

If file is specified without path information, the linker searches for it in the directory where the output image is being written. If it is not found, it is created in that directory.

You can use the symbol definitions file as input when linking another image. See Accessing symbols in another image for more information.

‑‑[no_]xref

‑‑xref lists all cross-references between input sections.

‑‑[no_]xrefdbg

‑‑xrefdbg lists all cross-references between input debug sections.

‑‑xref{from|to} object(section)

Lists cross-references:

from input section in object to other input sections
to input section in object from other input sections.

This is a useful subset of the listing produced by the ‑‑xref linker option if you are interested in references from or to a specific input section. You can have multiple occurrences of this option to list references from or to more than one input section.

Copyright © 2007 ARM Limited. All rights reserved.	ARM DUI 0377A
PDF version

Home > The Linker Command Syntax > armlink command syntax > Generating image-related information