-qipa

@PROCESS

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-+--------+-+-'     
                      |           .-1-.                    |         
                      +-level--=--+-0-+--------------------+         
                      |           '-2-'                    |         
                      +-list--+------------------+---------+         
                      |       '-=--+-file_name-+-'         |         
                      |            +-long------+           |         
                      |            '- short----'           |         
                      |             .-,-------------.      |         
                      |             V               |      |         
                      +-lowfreq--=----function_name-+------+         
                      |             .-unknown--.           |         
                      +-missing--=--+-safe-----+-----------+         
                      |             +-isolated-+           |         
                      |             '-pure-----'           |         
                      |               .-medium-.           |         
                      +-partition--=--+-small--+-----------+         
                      |               '-large--'           |         
                      | .-nostdexits-.                     |         
                      +-+-stdexits---+---------------------+         
                      | .-threads--+---------------+-.     |         
                      | |          |    .-auto---. | |     |         
                      | |          '-=--+-number-+-' |     |         
                      | |               '-noauto-'   |     |         
                      +-+-nothreads------------------+-----+         
                      |                  .-,-------------. |         
                      |                  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 compile and link in the same compiler invocation, or during a separate link step only:

exits

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

isolated

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

level

Specifies the optimization level for interprocedural analysis. Valid suboptions are one of the following suboptions:

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 written to the data reorganization section of the listing file. Reorganizations include common block splitting, 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.f, 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 procedures that are likely to be called infrequently. These are typically error handling, trace, or initialization procedures. The compiler may be able to make other parts of the program run faster by doing less optimization for calls to these procedures.

missing

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

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 procedures, 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 procedures that are not compiled with -qipa. Any procedure specified as pure must be isolated and safe, and must not alter the internal state or have side-effects, defined as potentially altering any data visible to the caller.

safe

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

stdexits | nostdexits

Specifies that certain predefined routines can be optimized as with the exits suboption. The procedures are: abort, exit, _exit, and _assert.

threads | nothreads

Runs portions of the IPA optimization process during pass 2 in parallel threads, which can speed up the compilation process on multi-processor systems. Valid suboptions for the threads suboption are as follows:

auto | noauto: When auto is in effect, the compiler selects a number of threads heuristically based on machine load. When noauto is in effect, the compiler creates one thread per machine processor.
number: Instructs the compiler to use a specific number of threads. number can be any integer value in the range of 1 to 32 767. However, number is effectively limited to the number of processors available on your system.

Specifying threads with no suboptions implies -qipa=threads=auto.

unknown

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

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

Note:

-qipa=inline and all of its associated suboptions are deprecated, -qinline replaces them all. For details, see -qinline and Deprecated options.
As of the V11.1 release of the compiler, the pdfname suboption is deprecated; you should use -qpdf1=pdfname or -qpdf2=pdfname in your new applications. See -qpdf1, -qpdf2 for details.

Usage

Specifying -qipa automatically sets the optimization level to -O2. For additional performance benefits, you can also specify the -qinline option. The -qipa option extends the area that is examined during optimization and inlining from a single procedure to multiple procedures (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.

Examples

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

xlf -c *.f -qipa
xlf -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:

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