ipa(5)

IPA - Inter-Procedural Analysis

As shipped in IRIX 6.5. First release of IRIX 6.5.

NAME
IPA - Inter-Procedural Analysis

TOPIC
This man page describes the function of IPA (Inter-Procedural Analysis)
in the MIPSpro compilers and how to get maximal benefit from using it.
It is divided into 3 sections:

What Is IPA?

How Does IPA Affect the Compilation Process?

IPA Options

What Is IPA?
Most compiler optimizations work within a single procedure (function,
subroutine, etc.) at a time. This helps keep the problems manageable,
and is a key aspect of supporting separate compilation, because it allows
the compiler to restrict attention to the current source file.

However, this intra-procedural focus also presents serious restrictions.
By avoiding dependence on information from other procedures, an optimizer
is forced to make worst-case assumptions about the possible effects of
those procedures. For instance, at boundary points including all
procedure calls, it must typically save (and/or restore) the state of all
variables to (from) memory.

By contrast, inter-procedural analysis algorithms analyze more than a
single procedure - preferably the entire program - at once. The
optimizations performed by the MIPSpro compilers' IPA facility include:

Inlining: Calls to a procedure are replaced by a suitably modified
copy of the called procedure's body inline, even if the callee is in
a different source file.

Common block array padding: Global arrays in Fortran may be padded,
i.e. their size increased in order to reduce cache conflicts

Constant propagation: Formal parameters which always have a
particular constant value can be replaced by the constant, allowing
additional optimization. Global variables which are initialized to
constant values and never modified can be replaced by the constant.

Dead function elimination: Functions which are never called can be
removed from the program image, improving memory utilization.

Dead variable elimination: Variables which are never actually used
can be eliminated, along with any code that initializes them.

Global name optimizations: Global names in shared code must normally
be referenced via addresses in a global table, in case they are
defined or preempted by another DSO (see dso(5)). If the compiler
knows it is compiling a main program and that the name is defined in
another of the source files comprising the main program, an absolute
reference can be substituted, eliminating a memory reference. For
example, code to load X which looked like
lw $4,%got_disp(X),$gp
ld $5,0,$4
might turn into
lui $4,%hi(X)
ld $5,%lo(X),$4
Similarly, IPA can optimize the data items which can be referenced by
simple offsets from the GP register instead of depending on the user
to provide an ideal value of the -G option (see cc(1) or f77(1)).

How Does IPA Affect the Compilation?
Because IPA must usually deal with code from multiple source files to be
effective, it has significant effects on compilation. These can be
classified as affecting either the program build process itself, or the
attributes of the resulting program.

The Build Process
The standard Unix C or Fortran compilation model involves two steps.
First, each source file comprising a program is compiled independently of
the others, producing a relocatable object file with the ".o" extension.
Then, the resulting object files are linked, along with any standard
libraries, by ld(1).

IPA works by postponing much of the compilation process until the link
step, when all of the program components can be analyzed together.
Specifically:

The compile step does initial processing of the source file, placing
an intermediate representation of the procedures it contains into the
output .o file instead of normal relocatable code. Such object files
are called WHIRL objects to distinguish them from normal relocatable
object files. This choice is invoked by the -IPA: option group.
This processing is really two phases: the normal front end language
processing, plus an IPA summary phase which collects local
information which will be used by IPA later. Since most back end
(optimization and code generation) options are transmitted via the
IPA summary phase, they must be present on the command line for the
compile step.

The link step, although it is still invoked by a single ld(1)
command, becomes several steps. First, the linker invokes IPA, which
analyzes and transforms all of the input WHIRL objects together,
writing modified versions of the objects. Then it invokes the
compiler back end on each of the modified objects, producing a normal
relocatable object. Finally, it invokes the linker again for a
normal linkage step, producing an executable program or DSO.

The temporary files created during this expanded link step are all
created in a temporary subdirectory of the output program's
directory, unless the environment variable TMPDIR is specified, then
the temporary subdirectory will be created under MPDIR; like other
temporary files produced by the compilation process, they are
normally removed on completion (unless the -keep option is
specified).

IPA does increase program build time in two ways. First, although the
IPA step may not be very expensive itself, it usually increases the size
of the code by inlining, and therefore expands the time required by the
rest of the compiler. More importantly, since IPA analysis can propagate
information from one module into optimization decisions in arbitrary
other modules, even minor changes to a single component module will cause
most of the program compilation to be redone. As a result, IPA is best
suited for use on programs with a stable source base.

Because full IPA is not always suitable, the MIPSpro compilers also
support inlining without IPA in cases where both the call and the called
subprogram are in the same file. This feature, called the standalone
inliner, is invoked by default when inlining is specified in C++, or may
be explicitly invoked using the -INLINE group options below.

Program Attributes
Like most optimization performed by the compiler, IPA should not change
the program's behavior. Nevertheless, it can affect the resulting
program in subtle ways.

The most important involve external symbols and DSOs (see dso(5)).
Unlike other IPA implementations, the MIPSpro compiler does not require
that all of the components of a program be subjected to IPA analysis.
The ld(1) command which invokes IPA may include object files (.o) and
archives (.a) which have been compiled normally without IPA analysis, as
well as referencing DSOs which, however they were compiled, cannot
contribute detailed information because the DSO may be replaced with a
different implementation after the program is built.

In order to analyze the program's use (and non-use) of variables, IPA
must determine what those unanalyzed objects might reference. It does so
by looking at their external symbol references. If an external symbol is
never referenced by one of the unanalyzed objects, and its address is
never taken in the code being analyzed, IPA can assume that the only
possible way for the unanalyzed code to access the named object is if it
passed as a parameter to an unanalyzed subprogram. Otherwise, it must
make worst-case assumptions.

This approach is safe for normal relocatable objects and archives, since
they cannot be changed without rebuilding (and reanalyzing) the program.
For DSOs, however, there is a danger that a modified version will make
additional references. To prevent this from causing changed program
behavior, IPA changes all of the external symbols which it assumes to be
unreferenced to export class HIDDEN or INTERNAL, which prevents them from
being referenced inadvertently by a future version of the DSO. So the
DSO case is safe as well.

The DSO treatment does have an important side effect, though. All
referenced DSOs should be referenced on the ld(1) command line.
Otherwise, their external references will not be seen by IPA, and the
symbols they require may not be visible at runtime, causing failure. If
you cannot give references to all DSOs used (for example because you will
be accessing them with dlopen(3) and don't want them automatically loaded
with your program), then you must provide an explicit exported symbol
list with the ld(1) options -exported_symbol or -exports_file. Please
read the dso(5) man page for a better understanding of DSO issues.

IPA Options
IPA is controlled from the command line with two option groups.
-INLINE:... controls inlining by the standalone inliner. It should be
used on your compile command line. -IPA:... controls general IPA
choices. If you use separate compile and link steps (i.e. using -c when
you compile and then linking the .o files produced with a separate cc(1),
f77(1), or ld(1) command), then you need to use -IPA for the compile
step, with or without individual options described below, and also for
the link step with any of the following options desired.

As described in the cc(1) and f77(1) man pages, the command line format
used for group options is

-groupname:option[=value][:opt2[=val2]]...

Thus, the group name is followed by a colon-separated list of options,
each of which is an option name possibly followed by an equal sign and a
value. The option names may generally be abbreviated by truncating them
to a unique prefix (which may change when new options are added to the
group).

The IPA option groups are:

-INLINE:...
Standalone inliner option group: control the application of
subroutine inlining done by the standalone inliner, or by the
main inliner if -IPA options are enabled. Normally, the calls to
be replaced by an inlined copy of the called subprogram are
chosen by heuristics internal to the inliner. Most of the
options in this group provide control over those choices. The
individual controls in this group are:

=(ON|OFF)
Enable/disable inlining (e.g. -INLINE:=OFF disables
inlining). Forcibly turn on or off stand-alone inline
processing; ignored with a warning for compiles which invoke
main IPA processing. When both are seen in the command line
(for a compile which will not invoke main IPA processing),
"=OFF" is processed and "=ON" is overridden with a warning.
If used within a specfile read by the stand-alone inliner,
"=OFF" will skip inline processing within the stand-alone
inliner and "=ON" is ignored with a warning.

all Change the default inlining heuristic. Attempt to inline all
routines which are not excluded by a never option or a pragma
suppressing inlining, either for the routine or for a
specific callsite. This option conflicts with none; all
takes precedence if both are specified. Note, this option may
cause performance problems since the size of the procedures
may be very large after inlining. If the user must use this
option then s/he may want to increase the Olimit, by using
the option -OPT:Olimit=<number> (see cc(1) or f77(1) ) to
enable procedures to be optimized. This will however, be at
the cost of increased compilation speed.

dfe[=(ON|OFF)]
Perform dead function elimination in the standalone inliner.
Remove any functions that are inlined everywhere they are
called and are not visible outside the current module
(default TRUE for C++ not compiled with -g, FALSE otherwise).

static[=(ON|OFF)]
Perform inlining of static functions in the standalone
inliner. (default TRUE for C, C++ at
-O2andhigheroptimizationlevels, FALSE otherwise).

alloca[=(ON|OFF)]
Enable save/restore of stack when inlining calls with alloca.
If the callee has an alloca then inlining it would normally
remove the function boundary at which the dynamic space would
have been released. This option saves and restores the stack
pointer before and after the inlined code. Having the option
ON is essential for correctness eg in code where the callee
is inside a loop; (default TRUE).

keep_pu_order[=(ON|OFF)]
Preserve source subprogram ordering (default FALSE).

preempt[=(ON|OFF)]
Enable inlining of functions marked preemptible in the
standalone inliner (default FALSE). Such inlining prevents
another definition of such a function in another dso from
pre-empting the definition of the function being inlined.

list[=(ON|OFF)]
List inlining actions as they occur to stderr (default
FALSE).

must=name1{,name2...}
Independent of the default inlining heuristic, always attempt
to inline any routines with names name1, name2,... For C++,
the names given must be the mangled names (see NOTES below).
For Fortran, the name given may be either the original name,
or the external name with the '_' appended by the compiler.
In all cases, the option applies to any and all routines
encountered with the given name, whether static or extern. A
pragma suppressing inlining at a particular callsite takes
precedence over this option.

never=name1{,name2...}
Independent of the default inlining heuristic, never attempt
to inline any routines with names name1, name2,... For C++,
the names given must be the mangled names (see NOTES below).
For Fortran, the name given may be either the original name,
or the external name with the '_' appended by the compiler.
In all cases, the option applies to any and all routines
encountered with the given name, whether static or extern. A
pragma requesting inlining at a particular callsite takes
precedence over this option.

none
Change the default inlining heuristic. Do not attempt to
inline any routines which are not specified by a must option
or a pragma requesting inlining, either for the routine or
for a specific callsite. This option conflicts with all; all
takes precedence if both are specified.

file=filename
Provides cross-file inlining from within the standalone
inliner. The option searches for routines provided via a
-INLINE:must list option, in the file specified in the
-INLINE:file option. The file provided by this option must be
generated using the -IPA -c options. The file generated
contains information used to perform cross file inlining. For
example, suppose two files exist: foo.f and bar.f. The file,
foo.f looks like this:
program main
...
call bar()
end

the file, bar.f looks like:
subroutine bar()
...
end

To inline bar into main, using the standalone inliner,
compile bar.f in the following way:
f77 -n32 -IPA -c bar.f

This produces the file, bar.o. To inline bar into foo.f, use:
f77 -n32 foo.f -INLINE:must=bar_:file=bar.o

library=ArchiveLibraryName
Identify archive libraries where inliner should search for
subprograms. This option is similar to
-INLINE:file= option where the files (.o) in the archived
library (.a) must have been generated using the -IPA -c
options. For example, if function foo is defined in
foofile.f which has been compiled with -IPA -c and
transformed into an archive via
ar rv foolib.a foofile.o
cc -n32 -INLINE:must=foo:library=foolib.a bar.c would inline
the function foo from foofile.o (which is automatically
extracted from foolib.a) into bar.c via the crossfile
inlining mechanism described above.

max_pu_size_inline[=(nnnn)]
Limit size of inlined subprograms to nnnn (default is 5000).
Inlining is disabled if after inlining the caller exceeds
this size.

specfile=filename
Open filename to read additional options. The specification
file contains zero or more lines with inliner options in the
form expected on the command line. For instance, it might
contain a single line like:
-INLINE:never=errfunc:must=accessor,solver
or, multiple lines like:
-INLINE:all
-INLINE:never=errfunc
The specfile option cannot occur in a specification file, so
specification files cannot invoke other specification files.

-IPA:...
IPA option group: control the interprocedural analyses and
transformations performed. Note that giving just the group name
without any options, i.e. -IPA, will invoke IPA with the default
settings. The individual controls in this group are:

addressing[=(ON|OFF)]
Enable/disable the analysis of address operator usage.
-IPA:alias=ON is a prerequisite. (Default OFF.)

aggr_cprop[=(ON|OFF)]
Enable/disable aggressive interprocedural constant
propagation. Attempt to avoid passing constant parameters,
replacing the corresponding formal parameters by the constant
values. By default, less aggressive interprocedural constant
propagation is done (default OFF).

alias[=(ON|OFF)]
Enable/disable alias/mod/ref analysis (default OFF.

autognum[=(ON|OFF)]
Determine the optimal value of the -Gnum option, i.e.
identify a size bound below which data can be allocated
relative to the global pointer and accessed cheaply. This
optimization is turned off when -multigot is specified in the
linker command line. (default ON. See also -IPA:Gnum).

Gnum=n
User specified G num (default is no limit).

Gspace=n
User specified size (in bytes) for the area where IPA can
allocate data that can be referenced relative to the global
pointer. (default 64K bytes, which is the maximum valid
value).

cgi[=(ON|OFF)]
Enable/disable constant global variable identification, i.e.
mark non-scalar global variables which are never modified as
constant, and propagate their constant values to all files
(default ON).

cprop[=(ON|OFF)]
Enable/disable interprocedural constant propagation, i.e.
identify formal parameters which always have a specific
constant value (default ON - see also -IPA:aggr_cprop).

depth=n
Identical to maxdepth=n.

dfe[=(ON|OFF)]
Enable/disable dead function elimination, i.e. removal of
subprograms which are never called from the program (default
ON).

dve[=(ON|OFF)]
Enable/disable dead variable elimination, i.e. removal of
variables which are never referenced from the program
(default ON).

echo[=(ON|OFF)]
Echo (to stderr) the back end compile commands and the final
link command which are invoked from IPA. This can help
monitor progress of a large system build (default OFF).

forcedepth=n
Instead of the default inlining heuristics, attempt to inline
all functions at a depth of at most n in the callgraph, where
functions which make no calls are at depth 0, those which
call only depth 0 functions are at depth 1, and so on.
Ignore the default heuristic limits on inlining. (See also
maxdepth.)

linear[=(ON|OFF)]
When inlining Fortran subroutines, IPA tries to map formal
array parameters to the shape of the actual parameter.
However, it may not always be able to always map it. In the
case that it can not map the parameter, it linearizes the
array reference. By default, it will not inline such
callsites since they may cause performance problems (default
OFF).

Gfactor=n
n is the percentage used to multiply the estimated External
GOT entries with for estimating the total .got size. A n of
200 means that IPA will multiply the estimated External GOT
entries by 2 to get the estimated total .got size. (default
200).

gp_partition[=(ON|OFF)]
Enable partitioning for archiving different GP-groups, as
specified by the user externally or determined by IPA
internally. This option basically enables PICOPT in the
presence of -multigot. (default OFF).

inline[=(ON|OFF)]
Perform inter-file subprogram inlining during main IPA
processing (default ON - does not affect the standalone
inliner).

Intrinsics=n
n is the number of FORTRAN intrinsic functions that the
executable may have entries in the GOT area. This number is
added to the estimated External GOT entries to get the
estimated total FORTRAN intrinsic functions that will be
added by the Lowerer after the IPA phase.

keeplight[=(ON|OFF)]
IPA NOT to send down "-keep" to the BE. The purpose is to
save space. (default OFF).

map_limit=n
This controls when IPA should enable "sp_partition". n is
the maximum size (in bytes) of input files mapped before IPA
does "sp_partition".

maxdepth=n
In addition to the default inlining heuristics, don't attempt
to inline functions at a depth of more than n in the
callgraph, where functions which make no calls are at depth
0, those which call only depth 0 functions are at depth 1,
and so on. Inlining remains subject to overriding limits on
code expansion. (See also forcedepth, space and plimit.)

max_job=n
Limit the maximum parallelism when invoking the compiler back
end after IPA to at most n compilations running at once
(default 2 on a uniprocessor host, 4 on a multiprocessor
host).

picopt[=(ON|OFF)]
Perform PIC optimizations, e.g. identify names which cannot
be preempted (default ON).

partition_group={symbol_name[%{I|G}]|file_name%F}[,{symbol_name[%{I|G}]|file_name%F}]*
Specifying EXTERNAL symbols belonging to the same group. All
unspecified symbols will be considered by IPA as belonging to
the "COMMON" group, which has the properties of always being
in memory AND available for inlining. Following the
symbol_name, the user can specify the properties for that
symbol by adding a '%' follows by the property wanted:
I -- symbol is used ONLY within the partition.

G -- symbol should be marked as GP-relative, for DATA
symbols only.
Alternatively, the user can specify a gp_partition per file,
as in
partition_group=file_name%F
Then every defined EXTERNAL symbols exist in that file will
have the same group. file_name must be specified in the same
way that the file is specified in the link-line, e.g.

cc
-IPA:gp_partition=on:partition_group=/usr/tmp/p007.o%F:partition_group=./add.o%F
/usr/tmp/p007.o ./add.o

plimit=n
Stop inlining into a particular subprogram once it reaches
size n in the intermediate representation (default 2500).

relopt[=(ON|OFF)]
Enable optimizations similar to the Ucode -O3 -c, where
objects are built with the assumption that the compiled
objects will be linked into a call-shared executable later.
In effect, optimizations based on position-dependent code
(non-PIC) are performed on those objects. (default OFF.)

space=n
Stop inlining once the program size has increased by n%. For
example, n=20 will limit code expansion due to inlining to
approximately 20%. (Default is 100%.)

sp_partition=[=(ON|OFF)]
Enable partitioning for disk/address-saving purpose. Mainly
used for building huge programs, e.g. PTC. Partitioning
should normally be done by IPA internally. (default OFF).

specfile=file_name
Open file_name to read more options. A specfile contains
zero or more of the options allowed by -IPA. E.g. on the
command-line:
-IPA:specfile=option_file
and inside the file "option_file", the user can specify
anything for -IPA as if it is specified in the command line,
like:
-
IPA:gp_partition=on:partition_group=p007.o%F:partition_group=add.o%F
Since "specfile=..." is not legal within a specfile, a
specfile cannot point at other specfiles.

use_intrinsic[=(ON|OFF)]
Enable loading the intrinsic version of standard library
functions. (default OFF).

NOTES
Both IPA and standalone inlining are disabled when -g is specified on the
compile line.

For specifying routine names to the -INLINE:never=name and -
INLINE:must=name options for C++ programs, the "mangled" internal name
must be used. Because C++ allows overloading, i.e. the use of the same
name for multiple objects which can be distinguished by type, it uses
internal names which are constructed from the original name and an
encoded version of the object's type. To find this mangled name, do the
following (your input is in boldface):

1) Compile the source module where the name is defined, say:
> CC -c source.cxx -o source.o

2) Use the original name to find the mangled name in the object file
using nm(1) and grep(1). For example, if the original name was
mysub, use:
> nm -B source.o | grep mysub
0f89f950 T mysub__10yourclassFv
0f89facc T mysub__10myclassFv

3) Step (2) might produce several potential matches, particularly if
overloading is actually occurring. If so, use the filter c++filt to
determine which one is the one you want:
> /usr/lib/c++/c++filt
mysub__10myclassFv
myclass::mysub(void)
You can continue entering possible names from step (2) until one of
them matches the name you want.