-qipa

Pragma equivalent

None.

Purpose

Enables or customizes a class of optimizations known as interprocedural analysis (IPA).

IPA is a two-step process: the first step, which takes place during compilation, consists of performing an initial analysis and storing interprocedural analysis information in the object file. The second step, which takes place during linking, and causes a complete recompilation of the entire application, applies the optimizations to the entire program.

You can use -qipa during the compilation step, the link step, or both. If you compile and link in a single compiler invocation, only the link-time suboptions are relevant. If you compile and link in separate compiler invocations, only the compile-time suboptions are relevant during the compile step, and only the link-time suboptions are relevant during the link step.

Syntax


-qipa compile-time syntax

        .-noipa--------------------.   
>>- -q--+-ipa--+-----------------+-+---------------------------><
               |    .-object---. |     
               '-=--+-noobject-+-'


-qipa link-time syntax

        .-noipa--------------------------------------------------.   
>>- -q--+-ipa--+-----------------------------------------------+-+-><
               |    .-:--------------------------------------. |     
               |    |             .-,-------------.          | |     
               |    V             V               |          | |     
               '-=----+-exits--=----function_name-+--------+-+-'     
                      |                     .-,----------. |         
                      |                     V            | |         
                      +-infrequentlabel--=----label_name-+-+         
                      |           .-1-.                    |         
                      +-level--=--+-0-+--------------------+         
                      |           '-2-'                    |         
                      +-list--+------------------+---------+         
                      |       '-=--+-file_name-+-'         |         
                      |            +-long------+           |         
                      |            '- short----'           |         
                      |             .-,-------------.      |         
                      |             V               |      |         
                      +-lowfreq--=----function_name-+------+         
                      |             .-unknown--.           |         
                      +-missing--=--+-safe-----+-----------+         
                      |             +-isolated-+           |         
                      |             '-pure-----'           |         
                      |               .-medium-.           |         
                      +-partition--=--+-small--+-----------+         
                      |               '-large--'           |         
                      |                  .-,-------------. |         
                      |                  V               | |         
                      +-+-isolated-+--=----function_name-+-+         
                      | +-pure-----+                       |         
                      | +-safe-----+                       |         
                      | '-unknown--'                       |         
                      '-file_name--------------------------'

Defaults

-qnoipa

Parameters

You can specify the following parameters during a separate compile step only:

object | noobject

Specifies whether to include standard object code in the output object files.

Specifying noobject can substantially reduce overall compile time by not generating object code during the first IPA phase. Note that if you specify -S with noobject, noobject will be ignored.

If compiling and linking are performed in the same step and you do not specify the -S or any listing option, -qipa=noobject is implied.

Specifying -qipa with no suboptions on the compile step is equivalent to -qipa=object.

You can specify the following parameters during a combined compilation and link step in the same compiler invocation, or during a separate link step only:

clonearch | noclonearch

This suboption is no longer supported. Consider using -qtune=balanced.

cloneproc | nocloneproc

This suboption is no longer supported. Consider using -qtune=balanced.

exits

Specifies names of functions which represent program exits. Program exits are calls which can never return and can never call any function which has been compiled with IPA pass 1. The compiler can optimize calls to these functions (for example, by eliminating save/restore sequences), because the calls never return to the program. These functions must not call any other parts of the program that are compiled with -qipa.

infrequentlabel

Specifies user-defined labels that are likely to be called infrequently during a program run.

label_name: The name of a label, or a comma-separated list of labels.

isolated

Specifies a comma-separated list of functions that are not compiled with -qipa. Functions that you specify as isolated or functions within their call chains cannot refer directly to any global variable.

level

Specifies the optimization level for interprocedural analysis. Valid suboptions are as follows:

0: Performs only minimal interprocedural analysis and optimization.
1: Enables inlining, limited alias analysis, and limited call-site tailoring.
2: Performs full interprocedural data flow and alias analysis.

If you do not specify a level, the default is 1.

To generate data reorganization information, specify the optimization level -qipa=level=2 or -O5 together with -qreport. During the IPA link phase, the data reorganization messages for program variable data are produced in the data reorganization section of the listing file. Reorganizations include array splitting, array transposing, memory allocation merging, array interleaving, and array coalescing.

list

Specifies that a listing file be generated during the link phase. The listing file contains information about transformations and analyses performed by IPA, as well as an optional object listing for each partition.

If you do not specify a list_file_name, the listing file name defaults to a.lst. If you specify -qipa=list together with any other option that generates a listing file, IPA generates an a.lst file that overwrites any existing a.lst file. If you have a source file named a.c, the IPA listing will overwrite the regular compiler listing a.lst. You can use the -qipa=list=list_file_name suboption to specify an alternative listing file name.

Additional suboptions are one of the following suboptions:

short: Requests less information in the listing file. Generates the Object File Map, Source File Map and Global Symbols Map sections of the listing.
long: Requests more information in the listing file. Generates all of the sections generated by the short suboption, plus the Object Resolution Warnings, Object Reference Map, Inliner Report and Partition Map sections.

lowfreq

Specifies functions that are likely to be called infrequently. These are typically error handling, trace, or initialization functions. The compiler may be able to make other parts of the program run faster by doing less optimization for calls to these functions.

missing

Specifies the interprocedural behavior of functions that are not compiled with -qipa and are not explicitly named in an unknown, safe, isolated, or pure suboption.

Valid suboptions are one of the following suboptions:

safe: Specifies that the missing functions do not indirectly call a visible (not missing) function either through direct call or through a function pointer.
isolated: Specifies that the missing functions do not directly reference global variables accessible to visible function. Functions bound from shared libraries are assumed to be isolated.
pure: Specifies that the missing functions are safe and isolated and do not indirectly alter storage accessible to visible functions. pure functions also have no observable internal state.
unknown: Specifies that the missing functions are not known to be safe, isolated, or pure. This suboption greatly restricts the amount of interprocedural optimization for calls to missing functions.

The default is to assume unknown.

partition

Specifies the size of each program partition created by IPA during pass 2. Valid suboptions are one of the following suboptions:

small
medium
large

Larger partitions contain more functions, which result in better interprocedural analysis but require more storage to optimize. Reduce the partition size if compilation takes too long because of paging.

pure

Specifies pure functions that are not compiled with -qipa. Any function specified as pure must be isolated and safe, and must not alter the internal state nor have side-effects, defined as potentially altering any data visible to the caller.

safe

Specifies safe functions that are not compiled with -qipa and do not call any other part of the program. Safe functions can modify global variables, but may not call functions compiled with -qipa.

unknown

Specifies unknown functions that are not compiled with -qipa. Any function specified as unknown can make calls to other parts of the program compiled with -qipa, and modify global variables.

file_name

Gives the name of a file which contains suboption information in a special format.

The file format is shown as follows:

# ... comment 
attribute{, attribute} = name{, name}
missing = attribute{, attribute} 
exits = name{, name} 
lowfreq = name{, name} 
list [ = file-name | short | long ]
level = 0 | 1 | 2 
partition = small | medium | large

where attribute is one of:

exits
lowfreq
unknown
safe
isolated
pure

Usage

Specifying -qipa automatically sets the optimization level to -O2. For additional performance benefits, you can also specify the -finline-functions (-qinline) option. The -qipa option extends the area that is examined during optimization and inlining from a single function to multiple functions (possibly in different source files) and the linkage between them.

If any object file used in linking with -qipa was created with the -qipa=noobject option, any file containing an entry point (the main program for an executable program, or an exported function for a library) must be compiled with -qipa.

You can link objects created with different releases of the compiler, but you must ensure that you use a linker that is at least at the same release level as the newer of the compilers used to create the objects being linked.

Some symbols which are clearly referenced or set in the source code may be optimized away by IPA, and may be lost to debug or nm outputs. Using IPA together with the -g compiler will usually result in non-steppable output.

Note that if you specify -qipa with -#, the compiler does not display linker information subsequent to the IPA link step.

For recommended procedures for using -qipa, see Optimizing your applications.

Predefined macros

None.

Examples

The following example shows how you might compile a set of files with interprocedural analysis:

xlc -c *.c -qipa
xlc -o product *.o -qipa

Here is how you might compile the same set of files, improving the optimization of the second compilation, and the speed of the first compile step. Assume that there exist a set of routines, user_trace1, user_trace2, and user_trace3, which are rarely executed, and the routine user_abort that exits the program:

xlc -c *.c -qipa=noobject
xlc -c *.o -qipa=lowfreq=user_trace[123]:exit=user_abort

Related information

Voice your opinion on getting help information

Ask IBM compiler experts a technical question in the IBM XL compilers forum