The -apo option invokes APO. When this option is enabled, the compiler automatically converts sequential code into parallel code by inserting parallel directives where it is safe and beneficial to do so. Specifying -apo also enables the -mp option, which enables recognition of the parallel directives inserted into your code.

The -apokeep and -apolist options control output files. Both options generate file.list , which is a listing file that contains information on the loops that were parallelized and explains why others were not parallelized.

When -apokeep is specified, the compiler writes file.list, and in addition, it retains file.anl and file.m . The ProMP tools use file.anl . For more information on ProMP, see the ProDev ProMP User's Guide. file.m is an annotated version of your source code that shows the insertion of multiprocessing directives.

When -IPA is specified with the -apokeep option, the default settings for IPA suboptions are used, with the exception of -IPA:inline, which is set to OFF.

For more information on the content of file.list , file.anl, and file.m, see “Files”.

---

Note: Because of data conflicts, do not specify the -mplist or -CLIST options when -apokeep is specified.

---

This option generates a C/C++ listing and directs the compiler to write an equivalent parallelized program in file.w2c.c . For more information on the content of file.w2c.c, see “Files”.

Interprocedural analysis (IPA) is invoked by the -ipa or -IPA command line option. It performs program optimizations that can only be done by examining the whole program, not parts of a program.

When APO is invoked with IPA, only those loops whose function calls were determined to be safe by the APO are optimized.

If IPA expands functions inline in a calling routine, the functions are compiled with the options of the calling routine. If the calling routine is not compiled with -apo, none of its inlined functions are parallelized. This is true even if the functions are compiled separately with -apo because with IPA, automatic parallelization is deferred until link time.

When -apokeep or -pcakeep are specified in conjunction with -ipa or -IPA, the default settings for IPA suboptions are used with the exception of the inline=setting suboption, which is set to OFF.

For more information on the effect of IPA, see “Loops Containing Function Calls”. For more information on IPA itself, see the ipa(5) man page.

The -LNO options control the Loop Nest Optimizer (LNO). LNO performs loop optimizations that better exploit caches and instruction-level parallelism. The following LNO options are of particular interest to APO users:

You can view the transformed code in the original source language after LNO performs its transformations. Two translators, integrated into the compiler, convert the compiler's internal representation into the original source language. You can invoke the desired translator by using the CC -CLIST:=on option. For example, the following command creates an a.out object file and the C/C++ file test.w2c.c:

CC -O3 -CLIST:=on test.c

Because it is generated at a later stage of the compilation, this .w2c.c file differs somewhat from the .w2c.c file generated by the -apokeep option (see “-apokeep and -apolist”). You can read the .w2c.c file, which is a compilable C/C++ representation of the original program after the LNO phase. Because the LNO is not a preprocessor, recompiling the file.w2c.c can result in an executable that differs from the original compilation of the .c file.

To obtain maximum performance, specify -O3 when compiling with APO enabled. The optimization at this level maximizes code quality even if it requires extensive compile time or relaxes the language rules. The -O3 option uses transformations that are usually beneficial but can sometimes hurt performance. This optimization may cause noticeable changes in floating-point results due to the relaxation of operation-ordering rules. Floating-point optimization is discussed further in “-OPT:...”.

The -OPT command line option controls general optimizations that are not associated with a distinct compiler phase.

The -OPT:roundoff=n option controls floating-point accuracy and the behavior of overflow and underflow exceptions relative to the source language rules.

When -O3 is in effect, the default rounding setting is -OPT:roundoff=2. This setting allows transformations with extensive effects on floating-point results. It allows associative rearrangement across loop iterations and the distribution of multiplication over addition and subtraction. It disallows only transformations known to cause overflow, underflow, or cumulative round-off errors for a wide range of floating-point operands.

At -OPT:roundoff=2 or 3, APO can change the sequence of a loop's floating-point operations in order to parallelize it. Because floating-point operations have finite precision, this change can cause slightly different results. If you want to avoid these differences by not having such loops parallelized, you must compile with -OPT:roundoff=0 or -OPT:roundoff=1.

Example. APO parallelizes the following loop when compiled with the default settings of -OPT:roundoff=2 and -O3:

float a, b[100];
for(i=0; i<100; i++)
    a = a + b[i];

At the start of the loop, each processor gets a private copy of a in which to hold a partial sum. At the end of the loop, the partial sum in each processor's copy is added to the total in the original, global copy. This value of a can be different from the value generated by a version of the loop that is not parallelized.

The -pca option invokes APO. For the O32 ABI, the -pca option invokes Power C. The -pcakeep and -pcalist options control output files.

When -IPA is specified with the -pcakeep option, the default settings for IPA suboptions are used, with the exception of -IPA:inline, which is set to OFF.

---

Note: These options are outmoded. The preferred way of invoking APO is through the -apo option, and the preferred way to obtain a listing is through the -apolist option. For more information on these options, see “-apo”, and “-apokeep and -apolist”.

---

Your input file.

For information on files used and generated when APO is enabled, see “Files”.

The -apolist and -apokeep options generate files that list the original loops in the program along with messages indicating if the loops were parallelized. For loops that were not parallelized, an explanation is provided.

Example. The following function resides in file testl.c:

void sub(double arr[], int n)
{
  extern void foo(double);
  int i;
  for(i=1; i<n; i++) 
  {
    arr[i] += arr[i-1];
  }
  for(i=0; i<n; i++) 
  {
    arr[i] += 7.0;
    foo(arr[i]);
  }
  for(i=0; i<n; i++) 
  {
    arr[i] += 7.0;
  }
}

File testl.c is compiled with the following command:

cc -O3 -n32 -mips4 -apolist -c testl.c

APO produces file testl.list:

Parallelization Log for Subprogram sub
    5: Not Parallel
         Array dependence from arr on line 6 to arr on line 6.

    8: Not Parallel
         Call foo on line 10.

   12: PARALLEL (Auto) __mpdo_sub1

Note the message for line 12. Whenever a loop is run in parallel, the parallel version of the loop is put in its own function. The MIPSpro profiling tools attribute all the time spent in the loop to this function. The last line indicates that the name of the function is __mpdo_sub1.

File file.w2c.c contains code that mimics the behavior of programs after they undergo automatic parallelization. The representation is designed to be readable so that you can see what portions of the original code were not parallelized. You can use this information to change the original program.

The compiler creates file.w2c.c by invoking the appropriate translator to turn the compiler's internal representations into C/C++. In most cases, the files contain valid code that can be recompiled, although compiling file .w2c.c without APO enabled does not produce object code that is exactly the same as that generated when APO is enabled on the original source.

The -apolist option generates file.w2c.c. Because it is generated at an earlier stage of the compilation, file.w2c.c from -apolist is more easily understood than file.w2c.c generated from -CLIST:=on option. On the other hand, the -CLIST option shows more of the optimizations that were performed. The parallelized program in file.w2c.c uses OpenMP directives.

Example. File testw2.c is compiled with the following command:

cc -O3 -n32 -mips4 -c -apo -apolist -c testw2.c

void trivial(float a[])
{
    int i;
    for(i=0; i<10000; i++) {
      a[i] = 0.0;
    }
}

Compiling testw2.c generates an object file, testw2.o, and listing file testw2.w2c.c, which contains the following code:

/*******************************************************
 * C file translated from WHIRL Wed Oct 28 14:03:23 1998
 *******************************************************/
/* Include file-level type and variable decls */
#include "testw2.w2c.h"


void trivial(
  _IEEE32(*a0)[])
{
  register _INT32 i0;
  
  /* PARALLEL DO will be converted to SUBROUTINE __mpdo_trivial1 */;
#pragma parallel
  {
#pragma pfor
#pragma local(i0)
#pragma shared(a0)
    for(i0 = 0; i0 <= 9999; i0 = i0 + 1)
    {
      (*a0)[i0] = 0.0F;
    }
  }
  return;
} /* trivial */

---

Note: WHIRL is the name for the compiler's intermediate representation.

---

As explained in “The file.list File”, parallel versions of loops are put in their own functions. In this example, that function is __mpdo_trivial_1. #pragma omp parallel is an OpenMP directive that specifies a parallel region containing a single DO directive.

The -apokeep option generates file.list. It also generates file.m and file.anl , which are used by Workshop ProMP.

file.m is similar to the file.w2c.c file but is more like original source code; it is based on OpenMP and mimics the behavior of the program after automatic parallelization.

WorkShop ProMP is a Silicon Graphics product that provides a graphical interface to aid in both automatic and manual parallelization for C/C++. The WorkShop ProMP Parallel Analyzer View helps you understand the structure and parallelization of multiprocessing applications by providing an interactive, visual comparison of their original source with transformed, parallelized code. For more information, see the ProDev WorkShop: ProMP User's Guide and the ProDev WorkShop: Performance Analyzer User's Guide.

SpeedShop, another Silicon Graphics product, allows you to run experiments and generate reports to track down the sources of performance problems. SpeedShop includes a set of commands and a number of libraries to support the commands. For more information, see the SpeedShop User's Guide.

The #pragma concurrent call directive instructs APO to ignore the dependencies of function and function calls contained in the loop that follows the assertion. The directive applies to the loop that immediately follows it and to all loops nested inside that loop. Other points to be aware of are the following:

---

Note: The directive affects the compilation even when -apo is not specified.

---

APO ignores potential dependencies in function fred() when it analyzes the following loop:

#pragma concurrent call
for(i=0; i<n; i++) {
    fred();
    ...
}

To prevent incorrect parallelization, make sure the following conditions are met when using #pragma concurrent call:

Example. The following code shows an illegal use of the directive. Function fred() writes to variable x, which is also read from by wilma() during other iterations, and the directive instructs APO to ignore this dependence.

void fred(float *b, int i, float *t) 
{
  *t = b[i];
}
void wilma(float *a, int i, float *t)
{
  a[i] = *t;
}

#pragma concurrent call
for(i=0; i<m; i++) 
{
  fred(b, i, &x);
  wilma(a, i, &x);
}

The following example shows how you can manually parallelize the preceding example safely by `localizing' variable x with a declaration float x; at the top of the loop body.

#pragma concurrent call
for (i=0, i<m, i++) {
   float x;
   fred(b, i, &x);
   wilma(a,i, &x);
}

The #pragma concurrent directive instructs APO, when analyzing the loop immediately following this directive, to ignore all dependencies between two references to the same array. If there are real dependencies between array references, the #pragma concurrent directive can cause APO to generate incorrect code.

---

Note: This directive affects the compilation even when -apo is not specified.

---

The following example shows correct use of this directive when m > n:

#pragma concurrent
for(i=0; i<n; i++)
    a[i] = a[i+m];

Be aware of the following points when using this directive:

The #pragma serial instructs APO not to parallelize the loop following the assertion; the loop is executed in serial mode. APO can, however, parallelize another loop in the same nest. The parallelized loop can be either inside or outside the designated sequential loop.

Example. The following code fragment contains a directive that requests that loop j be run serially:

for(i=0; i<m; i++) {
    #pragma serial
    for(j=0; j<n; j++)
        a[i][j] = b[i][j];
    ...
}

The directive applies only to the loop that immediately follows it. For example, APO still tries to parallelize loop i. This directive is useful in cases like this when the value of n is known to be very small.

The #pragma prefer concurrent directive instructs APO to parallelize the loop immediately following the directive if it is safe to do so.

Example. The following code fragment encourages APO to run loop i in parallel:

#pragma prefer concurrent
for(i=0; i<m; i++) {
    for(j=0; j<n; j++)
        a[i][j] = b[i][j];
    ...
}

When dealing with nested loops, APO follows these guidelines:

When placed inside a function, the #pragma permutation (array_name) directive informs APO that array_name is a permutation array. A permutation array is one in which every element of the array has a distinct value.

The directive does not require the permutation array to be dense. That is, within the array, every b[i] must have a distinct value, but there can be gaps between the values, such as b[1] = 1, b[2] = 4, b[3] = 9, and so on.

---

Note: This directive affects compilation even when -apo is not specified.

---

Example. In the following code fragment, array b is declared to be a permutation array for both loops in sub1():

void sub1(int n) 
{
  int i;
  extern int a[], b[];
  for(i=0; i<n; i++) 
  {
    a[b[i]] = i;
  }
  #pragma permutation (b)
  for(i=0; i<n; i++) 
  {
    a[b[i]] = i;
  }
}

Note the following points about this directive:

The #pragma no concurrentize directive inhibits parallelization. Its effect depends on its placement.

The #pragma concurrentize directive, when placed inside a function, overrides a #pragma no concurrentize directive that is placed outside of it. Thus, this directive allows you to selectively parallelize functions in a file that has been made sequential with a #pragma no concurrentize directive.

A program's performance can be severely constrained if APO cannot recognize that a loop is safe to parallelize. APO analyzes every loop in a program. If a loop does not appear safe, it does not parallelize that loop. The following sections describe constructs that can inhibit parallelization:

In many instances, loops containing the previous constructs can be parallelized after minor changes. Reviewing the information generated in program file.list, described in “The file.list File”, can show you if any of these constructs are in your code.

for(i=0; i<n; i++) {
    for(j=0; j<n; j++)
      tmp[j] = i+j;
    for(j=0; j<n; j++)
      a[i][j] = a[i][j] + tmp[j];
}

extern int t;
for(i=0; i<n; i++) {
    if(b[i]) {
        t = ...;
        a[i] += t;
    }
}
s2();

APO parallelizes a loop by distributing its iterations among the available processors. Loop nesting, loops with low trip counts, and other program characteristics can affect the efficiency of APO. The following subsections describe the effect that these and other programming constructs can have on APO's ability to parallelize:

for(i=0; i<n; i++)
    for(j=0; j<m; j++)
        for(k=0; k<l; k++)
           ...

void sub(int i, int n) {
   int j;
   #pragma serial
   for(j=0; j<n; j++) {
       ...
   }
}
void caller(int n) {
    int i;
    #pragma concurrent call
    for(i=0; i<n; i++) {
        sub(i, n);
    }
}

for(i=0; i<n; i++) {
    ...a[i]...
}
for(i=n-1; i>=0; i--) {
    ...a[i]...
}

for(i=0; i<n; i++)
    for(j=0; j<n; j++)
      a[i][j] = b[j][i] + ...;

for(i=0; i<n; i++)
    for(j=0; j<n; j++)
      b[i][j] = a[j][i] + ...;