2 PGHPF Compiler Options

This chapter describes the syntax and operation of each option to the pghpf command. Platform-specific node compiler options are not listed - refer to the node compiler manual page on your system for a list of these options. The options are arranged in alphabetical order. On a command line, options need to be preceded by a hyphen (-). This chapter uses the following notation:

[item]

Square brackets indicate that the enclosed item is optional.

{item | item}

Braces indicate that you must select one and only one of the enclosed items. A vertical bar (|) separates the choices.

...

Horizontal ellipses indicate that zero or more instances of the preceding item are valid.

Many of the compiler options and arguments have default settings. Some option defaults are affected by environment variables and can be set using the .pghpfrc driver configuration file. Refer to Appendix C, Driver Customization, for details on setting and altering defaults with the driver initialization file.

On systems where an underlying node compiler is coupled to PGHPF, most Fortran node compiler options are also valid as options to the pghpf command. Refer to the documentation for the Fortran node compiler supplied with your system for a list of valid Fortran node compiler command-line options. The PGHPF compiler uses the options -O1 and -O2 for optimization. If you select these options, varying levels of optimization will be applied to your HPF program. If the compiler does not recognize an option, it passes the option to the linker.

In general, the pghpf command accepts de facto standard UNIX compiler command-line options and responds with the expected behavior (that is, for options such as -c, -S, -o, etc). Some command-line options, such as -O1 and -O2, have meaning to both pghpf and the underlying Fortran node compiler, if applicable. In such cases, pghpf interprets the option and also passes it on to the underlying Fortran node compiler. On systems with slightly different spellings (for example, level 2 optimization is specified using -Oscalar2 when invoking the CRAY T3E Fortran node compiler directly), PGHPF passes the appropriate system-specific option along to the Fortran node compiler in the presence of -O<n> options.

Table 2-1 provides a list of pghpf command-line options that are valid on most systems. As noted in the table, some systems do not support all of these options. In addition, most Fortran node compiler options (options to the underlying F77 or F90 compiler) are accepted and passed through to the node compiler as part of the HPF compilation process.

Table 2-2 lists and briefly describes the HPF-specific options to the pghpf command. Full descriptions follow the table.

Options of the form -M<pghpf_flag> are used to specify PGHPF-specific compilation options. Detailed descriptions of these options are given below.

-M[no]autopar[=option [,option,...]]

PGHPF automatically parallelizes DO-loops that operate on distributed arrays. Loop interchange and distribution may be performed to increase the number of parallelizable loops. Information about parallelization is displayed with the -Minfo command-line switch. The optional arguments for autopar are as follows:

noassoc | assoc

noassoc prevents recognition of reductions. Programs in which results are sensitive to the order in which operations are performed will require this switch. The argument assoc allows recognition of reductions and is the default.

levels:n
specifies the maximum nesting depth of loops that get auto-parallelized. By default, the maximum nesting depth is 3.

-Mbyteswapio

Swap bytes from big-endian to little-endian or vice-versa on input and output of unformatted data. This could be useful when, for instance, reading data that was created on an SGI system but is being read from an Intel IA32 system.

-M[no]backslash

With -Mbackslash the compiler treats a backlash in quoted strings as a normal character rather than as an escape character. With -Mnobackslash, the compiler recognizes a backslash as an escape character in quoted strings (in accordance with standard C usage). The default is -Mnobackslash.

-Mcmf

Provides limited support for CM Fortran compatibility. Where there is no chance for ambiguity, PGHPF supports both the CM Fortran and the HPF spellings of common Fortran 90 features. This includes support for the intrinsics DOTPRODUCT, DLBOUND, DUBOUND, and DSHAPE which have calling sequences identical to their Fortran 90 counterparts. It also includes support for the CM Fortran method of using square brackets in the definition of array constructors and the use of the ARRAY keyword in place of the Fortran 90 standard DIMENSION keyword. There are three CM Fortran intrinsics which have names identical to their Fortran 90 counterparts but whose calling sequences differ. These are CSHIFT, EOSHIFT, and RESHAPE. Using -Mcmf these intrinsics will be interpreted using the CM Fortran convention rather than the standard Fortran 90 convention. There are six additional non-standard intrinsics in CM Fortran: PROJECT, LASTLOC, FIRSTLOC, RANK, DIAGONAL, and REPLICATE. These non-standard intrinsics are not currently supported by PGHPF. Other features of CM Fortran that are not supported are the layout directives and the utility routines.

-Mcraft

(CRAY T3E only) Supports the HPF_CRAFT environment. The EXTRINSIC keyword HPF_CRAFT or the command line flag -Mcraft each specify this HPF_CRAFT environment. This command line option informs the compiler that the entire file is written in HPF_CRAFT.

-M[no]dclchk

Determines whether all program variables must be explicitly declared.

-M[no]depchk

With nodepchk the compiler does not check for potential data dependencies between ambiguous array references. Note, with nodepchk, if data dependencies exist, this option can produce incorrect code.

-M[no]dlines

The compiler treats lines containing "D" in column 1 as executable statements (ignoring the "D"). With -Mnodlines the compiler does not treat lines containing "D" in column 1 as executable statements (does not ignore the "D").

-Mextend

The compiler accepts 132-column source code; without this option lines must be less than or equal to 72 columns wide.

-Mextract[=lib:dir] [name[,...]] [-o dir]

This option extracts procedures from the file indicated on the command line and places the output in the directory (extract directory) specified with the -o dir on the command line. If you do not specify a function name the compiler extracts every function in the source text. Note that while the extract phase extracts all possible procedures, the inliner will only inline procedures in an INDEPENDENT loop. You must specify an extract output directory dir with either the -o option or the lib: option. The name option can be any of the following:

name
instructs the extractor to extract function name from the source file.

-Mf90

Generate code for a program running on a single processor using Fortran90 semantics. Performance sometimes improves considerably using this option when running on a single processor.

-Mfreeform

Instructs the compiler to read source using Fortran 90 free form.

-Mftn

Instructs the compiler to stop after HPF compilation and save the resulting Fortran or intermediate language output.

-Mg

Set the -Mkeepftn option, suppress HPF line numbers in the generated Fortran intermediate file and compile the intermediate file with -g. This option can be used to debug at the intermediate Fortran level using a standard serial debugger, such as gdb.

-Mhpf2

The -Mhpf2 command-line option causes the PGHPF compiler to generate code assuming HPF 2.0 semantics (HPF 2.0 is the latest revision of the HPF language standard). In particular, HPF 2.0 requires that if an array is to be re-distributed at a subroutine boundary (i.e. the distribution of the actual argument differs from that of the corresponding dummy argument), the calling subroutine must contain an INTERFACE block which specifies the new distribution. If no INTERFACE block exists, the results of such a call are undefined. This new requirement on the part of the HPF programmer allows for caller re-mapping, whereby all data re-mapping is performed in the calling routine rather than in the callee. If no re-mapping takes place, the HPF compiler can eliminate costly checks required to support HPF 1.1 semantics. It is recommended that you use -Mhpf2 whenever possible. In general, it should improve performance. -Mhpf2 will become the default mode of compilation in a future release of PGHPF.

-Minfo[=option [,option,...]]

Instructs the compiler to produce information on standard error, where option is one of the following:

all
instructs the compiler to produce all of the following info information.

autopar
instructs the compiler to produce information on autoparallelization and independent loop parallelization.

inline
instructs the compiler to produce information on function inlining.

loop
instructs the compiler to display information about loops, such as optimizations.

save
instructs the compiler to create a copy of the source code annotated with comments containing the information messages produced by -Minfo. For each source file, the annotated copy is saved in a file with the same name but with the suffix .info added.

stat | time
instructs the compiler to display compilation statistics.

-Minform=level

Instructs the compiler to display error messages at the specified and higher levels, where level is one of the following:

fatal
instructs the compiler to display fatal error messages.

severe
instructs the compiler to display severe and fatal error messages.

warn
instructs the compiler to display warning, severe and fatal error messages.

inform
instructs the compiler to display all error messages (inform, warn, severe and fatal).

-Minline{=[lib:dir,][levels:number][name:fun,]}
Without options, this instructs the compiler to perform inlining within INDEPENDENT DO loops and to use a temporary directory for the extract phase. Note that while the extract phase extracts all possible procedures, the inliner will only inline procedures in DO loops.

name:func
instructs the inliner to inline the function func.

lib:dir
instructs the inliner to inline the functions within the library directory dir. Functions from the specified library are inlined if they are found in the source program.

levels:number
instructs the inliner to perform number levels of inlining. The default number is 1.

-Mipa=lib

Perform inter-procedural analysis.

lib
lib is the name of the IPA library directory to store the files generated and used in IPA program checking. The library directory is used to store information about procedure arguments and other data that is checked across routines. A lib directory must be specified.

-Mkeepftn

Instructs the compiler to keep the Fortran or intermediate language file as compilation continues. Normally the intermediate file is removed.

-Mkeepstatic

Instructs the compiler to keep the intermediate static initialization file that is normally removed during the compilation process. This option is used primarily for debugging purposes. Refer to the Static Data Initialization section for more information.

-Mmpi

Link a version of the HPF runtime libraries and startup routines that use MPI to perform interprocess communications (valid only on SGI IRIX, Solaris/SPARC, IBM, HP, Linux and Solaris86 platforms). This option must be used at both compile time and link time. PGHPF executables compiled and linked using -Mmpi must be run as standard MPI executables on your system, typically by using the mpirun command or whatever is appropriate for your MPI environment.

-M[no]list

Instructs the compiler to create a listing file. The listing file is filename.lst, where the name of the source file is filename.hpf.

-Mnofree[form]

Instructs the compiler to read source using fixed form formatting.

-Mnohpfc

Skip the HPF compilation step but compile using the Fortran compiler if a file with a .f or .F extension is supplied. Valid only on systems where PGHPF is coupled to an underlying Fortran node compiler.

-Mnoindependent

Instructs the compiler to disable parallelization of loops preceded by the INDEPENDENT directive.

-Mnoprelink

Skip the pre-link compilation phase. This phase handles static initialization for data initialized distributed data, and handles NAMELIST groups found in modules. Not using this option disables support for certain HPF/F90 features.

-Mnosequence

All variables are created as non-sequential variables unless an explicit SEQUENCE directive is supplied or the variable is an assumed size array.

-Moverlap[=size:n]

 

controls the size of the overlap area the compiler generates for certain expressions. The default size is 4. For most programs, the default handling for overlap areas is sufficient. However, in some cases, the default overlap area may result in a runtime memory allocation error such as the following:

 

0: ALLOCATE: xxxx bytes requested; not enough memory

 

In other cases, increasing or decreasing the size of the overlap area may improve a program's performance in cases where PGHPF generates overlap_shift communications. For example in the code:

 

!hpf$ distribute (block) :: a,b
forall(i=1:n) a(i) = b(i+10)

 

Using the default overlap size of 4, PGHPF does not use the overlap shift optimization, since the default size of 4 is too small. By increasing the overlap size to 10, PGHPF generates overlap shifts.

 

The compiler only optimizes overlap shift communications for BLOCK distributed dimensions where an array's shift amount is a compile time constant and is less than the overlap area allowances specified in an array index.

 

Reducing the overlap size may improve performance for some codes. For example, it can dramatically reduce memory usage in programs which include distributed arrays with many dimensions. Setting the size to 0 disables overlap shifts. Refer to the SHADOW directive for more information on how to control overlap areas.

-Mpreprocess

Run the preprocessor on the input source file.

-Mprof=option Set profile options. The option can be any of the following:

func
perform PGI-style function level profiling.

lines
insert calls to produce a pgprof.out file which contains both function and line level data.

Note that pgprof.out profile data files may often be input by PGPROF on systems other than the system that generated the profile data file. Also note that -p is generally not supported by PGHPF.

-Mr8

promotes REAL variables and constants to DOUBLE PRECISION and COMPLEX to DOUBLE COMPLEX. Constants specified with an exponent letter E are converted to constants with an exponent letter of type D.

-Mrecursive

instructs the compiler to produce code that will allow for recursion of the routines within the file. Local variables are placed on the stack instead of in static memory. Support for recursion usually depends on the underlying Fortran node compiler's support for recursion. Use of this option may adversely affect performance. Note that not all routines can be recursive. For example, routines that modify SAVEd variables or COMMON block variables as well as routines that perform I/O are generally not candidates for recursion. See release notes for information on platforms that support recursion.

-Mrpm

instructs the compiler to produce executable output to run under the PGI RPM homogeneous communications system (valid only on SGI IRIX, Solaris/SPARC, HP, Linux, Solaris86 and NT platforms). -Mrpm is a compile time and link time switch.

-Mrpm1

instructs the compiler to produce executable output to run under the PGI RPM1 communications system. This switch is useful for debugging. It causes PGHPF to generate all of the initialization required for RPM, but for execution on a single processor in a mode that makes it possible to debug the intermediate Fortran file using a standard serial debugger. -Mrpm1 is a compile time and link time switch.

-Msequence

All variables are created as SEQUENCE variables, where sequential storage is assumed.

-Msmp

Perform compilation for a shared-memory or logically shared-memory system, and perform inter-process communications using simple shared-memory references rather than calls to message-passing functions (valid only on CRAY T3E, SGI IRIX, Solaris/SPARC, HP, Linux, Solaris86 and NT platforms). This option must be used at both compile time and link time. When compiling with this option on any system other than the CRAY T3E, the execution run should include the runtime option: -pghpf -heapz <n>. See section 3.1.4, Running PGHPF
-Msmp programs, for more information on this runtime option.

-Mstandard

Causes PGHPF to flag source code that does not conform to the ANSI Fortran 90 standard (note, currently there is no ANSI standard for HPF).

-Mstats

Causes the compiler load the PGHPF runtime libraries that keep track of communications and message statistics for use with the PGHPF runtime -pghpf -stat options. See Chapter 3 for more information on these options.

-Mtotalview

Compile for debugging with the Etnus TotalView multiprocess debugger. Valid only for SGI, Sun, and IBM systems. To build a PGHPF program for debugging with Etnus TotalView, you must compile and link using the -g, -Mkeepftn and -Mtotalview switches to the pghpf compilation driver.

% pghpf -g -Mkeepftn -Mtotalview myprog.F

The commands used to start up TotalView vary from platform to platform. A typical invocation on 4 processors of an SGI Origin or Sun Ultra Enterprise for an HPF program compiled with shared-memory communications options (-Mrpm or -Msmp) would look as follows:

% totalview a.out -pghpf -np 4

A typical invocation on 4 processors of an IBM RS6000/SP for an HPF program compiled with default communications options (-Mmpi) would look as follows:

% mpirun -tv -np 4 a.out

For information on how to invoke TotalView on a specific platform and for a complete list of features and how to use them, refer to the TotalView Multiprocess Debugger User's Guide.

-M[no]upcase

The compiler allows uppercase letters in identifiers. With -Mupcase, the identifiers "X" and "x" are different, and keywords must be in lower case. This selection also affects the linking process: if you compile and link the same source code using -Mupcase on one occasion and -Mnoupcase on another, you may get two different executables (depending on whether the source contains uppercase letters). The standard libraries are compiled using the default -Mnoupcase.