ipa

Option Type Default Values #pragma options C C++
Compile-time Link-time
-qoption object noipa - x  

Syntax

For compile-time use:

-qipa
-qipa=object|noobject

For link-time use:

-qipa
-qipa=suboption {, suboption}
-qnoipa

 

-qipa Compile-time Formats Description
-qipa Activates interprocedural analysis with the following -qipa suboption defaults:
  • inline=auto
  • level=1
  • missing=unknown
  • partition=medium
-qipa=object

-qipa=noobject

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

Specifying the noobject suboption can substantially reduce overall compile time by not generating object code during the first IPA phase.

If the -S compiler option is specified with noobject, noobject is ignored.

If compilation and linking are performed in the same step, and neither the -S nor any listing option is specified, -qipa=noobject is implied by default.

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.

 

-qipa Link-time Formats Description
-qnoipa Deactivates interprocedural analysis.
-qipa Activates interprocedural analysis with the following -qipa suboption defaults:
  • inline=auto
  • level=1
  • missing=unknown
  • partition=medium
suboption Suboptions can take any of the forms shown below. Separate multiple suboptions with commas.
Suboption Description
exits=name{,name} Specifies names of functions 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.
inline[=suboption] Same as specifying the -qinline compiler option, with suboption being any valid -qinline suboption.
inline=auto

inline=noauto

 Enables or disables automatic inlining only. The compiler still accepts user-specified functions as candidates for inlining.
inline=name{,name} Specifies a comma-separated list of functions to try to inline, where functions are identified by name.
noinline=name{,name} Specifies a comma-separated list of functions that must not be inlined, where functions are identified by name.
inline=limit=num Changes the size limits that the -Q option uses to determine how much inline expansion to do. This established limit is the size below which the calling procedure must remain. number is the optimizer's approximation of the number of bytes of code that will be generated. Larger values for this number allow the compiler to inline larger subprograms, more subprogram calls, or both. This argument is implemented only when inline=auto is on.
inline=threshold=size Specifies the upper size limit of functions to be inlined, where size is a value as defined under inline=limit. This argument is implemented only when inline=auto is on.
isolated=name,{name} Specifies a list of isolated functions that are not compiled with IPA. Neither isolated functions nor functions within their call chain can refer to global variables.
level=0

level=1

level=2

 Specifies the optimization level for interprocedural analysis. The default level is 1. Valid levels are as follows:
Level 0 Does only minimal interprocedural analysis and optimization.
Level 1 Turns on inlining, limited alias analysis, and limited call-site tailoring.
Level 2 Performs full interprocedural data flow and alias analysis.
list

list=[name] [short|long]

 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 generated by the back end for each partition. This option can also be used to specify the name of the listing file.

If listings have been requested (using either the -qlist or -qipa=list options), and name is not specified, the listing file name defaults to a.lst.

The long and short suboptions can be used to request more or less information in the listing file. The short suboption, which is the default, generates the Object File Map, Source File Map and Global Symbols Map sections of the listing. The long suboption causes the generation of all of the sections generated through the short suboption, as well as the Object Resolution Warnings, Object Reference Map, Inliner Report and Partition Map sections.

lowfreq=name{,name} Specifies names of functions which are likely to be called infrequently. These will typically be 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=attribute 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.

The following attributes may be used to refine this information:

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

partition=medium

partition=large

partition=size

 Specifies the size of each program partition created by IPA during pass 2.

The size of the partition is directly proportional to the time required to link and the quality of the generated code. When partition sizes are large, the time to complete linkage is longer but the quality of the generated code is generally better. An integer may be used to specify partition size for finer control. This integer is in terms of unspecified units and its meaning may change from release to release. Its use should be limited to very short term tuning efforts.

pure=name{,name} Specifies a list of 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=name{,name} Specifies a list of safe functions that are not compiled with -qipa. Safe functions can modify global variables, but may not call functions compiled with -qipa.
unknown=name{,name} Specifies a list of 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 and dummy arguments.
filename Gives the name of a file which contains suboption information in a special format.

The file format is the following: 

# ... comment 
attribute{, attribute} = name{, name}
missing = attribute}, attribute} 
exits = name{, name} 
lowfreq = name{, name} 
inline [ = auto | = noauto ] 
inline = name{, name} [ from name{, name}] 
inline-threshold = unsigned_integer
inline-limit = unsigned_integer
list [ = file-name | short | long ] 
noinline 
noinline = name{, name} [ from name{, name}]
level = 0 | 1 | 2 
partition = small | medium | large | unsigned_integer

where attribute is one of:

  • exits
  • lowfreq
  • unknown
  • safe
  • isolated
  • pure

Purpose
Turns on or customizes a class of optimizations known as interprocedural analysis (IPA).

Notes

  1. IPA can significantly increase compilation time, even with the -qipa=noobject option, so using IPA should be limited to the final performance tuning stage of development.
  2. Specify the -qipa option on both the compile and link steps of the entire application, or as much of it as possible. You should at least compile the file containing main, or at least one of the entry points if compiling a library.
  3. While IPA's interprocedural optimizations can significantly improve performance of a program, they can also cause previously incorrect but functioning programs to fail. Listed below are some programming practices that can work by accident without aggressive optimization, but are exposed with IPA:
    1. Relying on the allocation order or location of automatics. For example, taking the address of an automatic variable and then later comparing it with the address of another local to determine the growth direction of a stack. The C language does not guarantee where an automatic variable is allocated, or it's position relative to other automatics. Do not compile such a function with IPA(and expect it to work).
    2. Accessing an either invalid pointer or beyond an array's bounds. IPA can reorganize global data structures. A wayward pointer which may have previously modified unused memory may now trample upon user allocated storage.
  4. Ensure you have sufficient resources to compile with IPA. IPA can generate significantly larger object files than traditional compilers. As a result, the temporary storage used to hold these intermediate files (by convention /tmp on AIX) is sometimes too small. If a large application is being compiled, consider redirecting temporary storage with the TMPDIR environment variable.
  5. Ensure there is enough swap space to run IPA (at least 200Mb for large programs). Otherwise the operating system might kill IPA with a signal 9 , which cannot be trapped, and IPA will be unable to clean up its temporary files.

 

The necessary steps to use IPA are:

  1. Do preliminary performance analysis and tuning before compiling with the -qipa option, because the IPA analysis uses a two-pass mechanism that increases compile and link time. You can reduce some compile and link overhead by using the -qipa=noobject option.
  2. Specify the -qipa option on both the compile and the link steps of the entire application, or as much of it as possible. Use suboptions to indicate assumptions to be made about parts of the program not compiled with -qipa. During compilation, the compiler stores interprocedural analysis information in the .o file. During linking, the -qipa option causes a complete recompilation of the entire application.
Note: If a Severe error occurs during compilation, -qipa returns RC=1 and terminates. Performance analysis also terminates.

Example
To compile a set of files with interprocedural analysis, enter:

xlc -c -O3 *.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 there exists two functions, trace_error and debug_dump, which are rarely executed.

xlc -c -O3 *.c -qipa=noobject
xlc -c -O3 *.o -qipa=lowfreq=trace_error,debug_dump

If a given compiler option is specified at both compile- and link-time with differing settings, the link-time option settings will generally prevail. In the example below, the -O3 option used at link-time, along with other settings implied by -O3, overrides the -O2 option used at compile-time.

xlc -c -O2 *.c -qipa=noobject
xlc -c -O3 *.o -qipa=lowfreq=trace_error,debug_dump


List of Compiler Options and Their Defaults
Options that Define the Compiler Object Code Produced