# Using the analyzer

After building a program, use the Resource Analyzer to analyze that program and display its resource usage.

The analyzer can input programs in either of the following forms:

- A single binary ELF file
- Multiple files stored in a program’s source code folder

The analyzer operates as a standalone command line tool. The resource usage information is generated in several text files, with the file data in an easy-to-read format.

## Start command

To start the Resource Analyzer from a command line, enter the following command:

`hexagon-analyzer-backend [option...]`

Use command switches to specify the input and output files for the program, and any additional command options ([Options](https://docs.qualcomm.com/doc/80-N2040-21/topic/using-the-analyzer.html#analyzer-options)). A switch consists of one or two dash characters
followed by a switch name and parameter. Switch names are case sensitive, and the switches must be separated by at least one space.

For example:

`hexagon-analyzer-backend --dsp v68 --folder my_prog`

To list the proper command line syntax and available command options, use the `--help` option:

`hexagon-analyzer-backend --help`

## Options

The options are specified by the command switches listed below. Some options have alternate abbreviated switches defined for ease of use.

### Display information

`--help | -h`

`--version | -v`

### Input files

`-aidfile filename`

`--elffile filename`

`--folder pathname | -f pathname`

`--rootfile filename`

### Output files

`--outdir pathname | -o pathname`

### Processor information

`--dsp version`

## Display information

**NOTE:** These options are used as sole command arguments. They do not launch the Resource Analyzer.

- `--help` | `-h`
    - Display the proper command line syntax and available options, and then exit.

- `--version` | `-v`
    - Display the release version of the Resource Analyzer and exit.

## Input files

- `--aidfile filename`
    - Specify the file name of the aiding file. For more information on aiding files, see [Aiding files](https://docs.qualcomm.com/doc/80-N2040-21/topic/using-the-analyzer.html#analyzer-aiding-files).

- `--elffile filename`
    - Specify the file name of the program file to be analyzed.

- `--folder pathname` | `-f pathname`
    - Specify the path name of the program folder to be analyzed.

- `--rootfile filename`
    - Specify the file name of the root specification file. For more information on specification files see [Root specification files](https://docs.qualcomm.com/doc/80-N2040-21/topic/using-the-analyzer.html#analyzer-root-specification-files).

## Output files

- `--outdir pathname` | `-o pathname`
    - Specify the target directory for output files. For more information on output files see [Output files](https://docs.qualcomm.com/doc/80-N2040-21/topic/using-the-analyzer.html#analyzer-output-files-usage).

## Processor information

- `--dsp version`
    - Specify the Hexagon processor version of the program file to be analyzed: v4, v5, v55, v60, v61, v62, v65, v66, v67, v67t (for Small Core), v68.

For more information on the Hexagon processor versions, see the appropriate *Qualcomm Hexagon V6x Programmer’s Reference Manual*.

Note

Not all of the -dsp option settings are supported in a specific Hexagon tools release.
For more information, see the *Qualcomm Hexagon LLVM C/C++ Compiler User Guide*.

## Screen messages

The following example shows the screen messages generated by the Resource Analyzer.

C:>hexagon-analyzer-backend --elffile bootimg.pbn --aidfile
    aidfile.txt -o ./outputs
    Processing ELF file bootimg.pbn
    Processing aid file aidfile.txt
    Processing aid file
    C:\Qualcomm\HEXAGON_Tools\5.0.05\qc\bin/libcAidFile.txt
    Calling hexagon-objdump ...
    Creating disassembly file ./outputs\\bootimg.pbn.dis from bootimg.pbn
    Please wait ... This could take several minutes with a large elf file.
    hexagon-objdump complete.
    Processing Disassembly file ./outputs\\bootimg.pbn.dis
    0% complete
    18% complete
    36% complete
    55% complete
    74% complete
    94% complete
    100% complete
    Writing output file ./outputs\RA_FunctionStackSizes.csv
    Writing output file ./outputs\RA_FunctionsByName.txt
    Writing output file ./outputs\\RA_WorstCaseCallPaths.txt
    Writing output file ./outputs\\RA_UnknownFunctions.txt
    Number of functions in ELF file: 856
    Number of memory objects in ELF file: 282
    Backend Processing Complete
    Copy to clipboard

## Errors and warnings

The Resource Analyzer outputs error messages when a failure occurs. Errors cannot be disabled.

The analyzer also generates the following warnings. All warnings can be enabled or disabled.

### Could not compute R29 = for function name in file name

The analyzer can only interpret three types of operations on the stack pointer:

allocframe(#48)
    r29 = add(#-48)
    r29 = sub(#48)
    Copy to clipboard

The R29 alias SP is also supported.

The analyzer cannot interpret other manipulations of the stack pointer. For example:

r29 = memw(r23+#0)
    r29 = r9
    Copy to clipboard

In these cases, the stack value of the function is marked as INDETERMINATE, and manual inspection is required to determine the function’s actual stack value.

### Missing @function declaration for function name in file name

The function does not have an @function declaration, which results in the function being categorized as an STT\_NOTYPE in the ELF symbol table. Also, the profiler does not interpret STT\_NOTYPE as a function.

All functions must have the following declaration:

.type funcname, @function
    Copy to clipboard

### Missing .size directive for function name in file name

The function does not have a terminating .size directive, which results in the function being categorized as an STT\_NOTYPE in the ELF symbol table with a size of zero. Also, the profiler does not interpret STT\_NOTYPE as a function.

All functions must be terminated with the directive:

.size funcname, .-funcname
    Copy to clipboard

### Missing @object declaration for object name in file name

The object does not have an @object declaration, which results in the object being categorized as an STT\_NOTYPE in the ELF symbol table.

All memory objects must have the following declaration:

.type objectname, @object
    Copy to clipboard

### Missing .size directive for object name in file name

The object does not have a terminating .size directive, which results in the object being categorized as an `STT_NOTYPE` in the ELF symbol table with a size of zero. Also, the profiler does not interpret `STT_NOTYPE` as a function.

All objects must be terminated with the directive:

.size objectcname, .-objectcname
    Copy to clipboard

### Label name does not begin with .L in file name

Labels must begin with .L, otherwise they are categorized as an `STT_NOTYPE` item in the ELF symbol table.

### Global collision for function name in file name

The analyzer found two global functions with the same name.

The analyzer forces the second instance of the function to have local scope. Any subsequent files that reference the function use the first function found.

### Global collision for object name in file name

The analyzer found two global objects with the same name.

The analyzer forces the second instance of the object to have local scope. Any subsequent files that reference the object use the first object found.

### Recursion encountered at function name in file name

This function has already been encountered at a higher node in this branch.

This node and the entire call path are marked as RECURSIVE. The cumulative stack value cannot be calculated.

## Output files

The Resource Analyzer writes the resource usage information to text files. The following sections describe these files.

**NOTE:** The cumulative stack value of a function is only accurate if the branch type of that function is Closed.

### List functions by name

The analyzer outputs a file that lists all the functions alphabetically with their attributes and call lists.

Output file name: FunctionsByName.txt

### List functions by size

The analyzer outputs a file that lists all the functions sorted by largest cumulative stack size with their attributes and call lists.

Output file name: FunctionsBySize.txt

### List function call paths

The analyzer outputs a file that lists all the functions sorted by largest cumulative stack size with a list of the largest call path.

Output file name: FunctionsCallPaths.txt

### List unknown functions

The analyzer outputs a file that lists all the unknown functions, which means there were calls to functions not found in the database.

Output file name: UnknownFunctions.txt

### File format

The output files are generated as text files in an easy-to-read format. For example:

Function Name: ThreadMain
        Mangled Name: ThreadMain
         Branch Type: Closed
               Scope: Global
               Stack: 48 bytes
    Cumulative Stack: 1128 bytes
               Calls: Called function     Cumulative Stack, Branch Type
                      __save_r16_through_r23             0, Closed
                      qurt_sem_down                     16, Closed
                      printf                           904, Closed
                      qurt_pipe_send                  1032, Closed
                      __restore_r16_through_r23_and_deallocframe_before_tailcall 0, Closed
                      qurt_thread_exit                1080, Closed
                      qurt_pipe_receive               1032, Closed
                      qurt_barrier_init                  0, Closed
                      qurt_sem_init_val                  0, Closed
                      qurt_pipe_init                    16, Closed
                      qurt_sem_add                       0, Closed
    Copy to clipboard

The `RA_FunctionStackSizes.csv` file is better suited for postprocessing with a script. The information in this file has the following data format:

function_name, cumulative_stack_size, branch_type
    Copy to clipboard

For example:

ThreadMain,1128,Closed
    _Mbtowc,1128,Closed
    fputc,1128,Closed
    _pthread_stub,1120,Closed
    pthread_mutex_lock,1120,Closed
    pthread_mutex_trylock,1120,Closed
    _Fwprep,1112,Closed
    pthread_cond_wait,1112,Closed
    _Getmbcurmax,1104,Closed
    _Getpctype,1104,Closed
    __register_frame_info_bases,1104,Closed
    __registerx,1104,Closed
    pthread_cond_broadcast,1104,Closed
    Copy to clipboard

## Aiding files

The Resource Analyzer optionally accepts (with the –aidfile option) an aiding file that provides information on missing resources. You can also use aiding files to override certain resource information (such as the function stack size and call list).

Each aiding file has the following properties:

- The file does not contain branches; instead, it contains only nodes that are treated as leafs.

    The stack size of a node in the file is the cumulative stack size for that node.
- The file can include comments that are preceded with the double forward slash. No other commenting styles are supported.
- For functions, nodes in an aiding file have the following data format:

code; symbol; size; scope
        Copy to clipboard

    Where:

    `code` - Informs the analyzer that this is a function node

    `symbol` - The function name (for C++, it must be the mangled name)

    `size` - The cumulative stack size of the node

    `scope` - The scope of the function
- For memory blocks, nodes in an aiding file have the following data format:

data; symbol; size; scope
        Copy to clipboard

    Where:

    `data` - Informs the analyzer that this is a memory block

> 
> 
> `symbol` - The memory block name
> 
> 
> `size` - The memory block size
> 
> 
> `scope` - The scope of the function
- The scope of a node in the aiding file has one of the following values.

    - 0 - Local
    - 1 - Global
    - 2 - Weak
    - 3 - Override
- The analyzer supports the following delimiters:

<comma> <space> <tab> <semicolon>
        Copy to clipboard

    The following lines are valid:

code name, 128, 1// comment
        code;_Znwj;300, 1
        Copy to clipboard

### Example aiding file

// Format:
    // code;name;stacksize;scope;
    // data;name;memsize;scope;
    code;function1;288;1;
    code;function2;144;3;
    data;memobject1;4;2;
    data;memobject2;400;3;
    Copy to clipboard

## Root specification files

The Resource Analyzer optionally accepts (with the `--rootfile` option) a file that identifies the default program entry points. These files
are known as *root specification* files.

Each root specification file is a text file that contains a list of function names, with one name per line. The # character indicates a
comment and is ignored by the analyzer.

Example of a root specification file:

threadmain
    main
    test
    Copy to clipboard

## Handling recursive and indeterminate functions

While recursion can be caused by a function calling itself, it is more often caused by a function tree that loops back on itself. The best way to resolve recursion is to rewrite the code to be non-recursive; however this may not always be possible.

The Resource Analyzer provides a mechanism for breaking recursion through the use of an aiding file ([Aiding files](https://docs.qualcomm.com/doc/80-N2040-21/topic/using-the-analyzer.html#analyzer-aiding-files)).
The aiding file allows you to override any function’s cumulative stack value and remove its call list, thus breaking the recursive chain.

Indeterminate functions are caused by direct manipulation of the stack pointer with run-time arguments. The cumulative stack value of
an indeterminate function must be considered as *at least*. You can use the aiding file to override the indeterminate state of the function.

Perform overriding by setting the scope value to 3 in the aiding file (for details, see [Aiding files](https://docs.qualcomm.com/doc/80-N2040-21/topic/using-the-analyzer.html#analyzer-aiding-files)).

Last Published: Oct 06, 2026

[Previous Topic
Limitations](https://docs.qualcomm.com/bundle/publicresource/80-N2040-21/topics/resource-analyzer-ug-overview.md) [Next Topic
Analysis methodology](https://docs.qualcomm.com/bundle/publicresource/80-N2040-21/topics/analysis-methodology.md)