KAPF(V3.3.1) KAP for IBM Fortran (Kuck & Associates) KAPF(V3.3.1)
NAME
kapf - Fortran preprocessor
SYNOPSIS
xlf -Pk [ -Wp, option, ..., option ] filename
DESCRIPTION
kapf is a Fortran source-to-source preprocessor which
restructures Fortran code for improved scalar performance
and better utilization of the memory hierarchy of the IBM
RS/6000 workstations.
filename is the name of a file containing the Fortran
source code to be optimized. The name of the
listing file can be set with the list option. The
optimized Fortran program can be written to
P<filename>.f if -fortran or -cmp is used. The
user can direct the optimized code to a different
file or to stdout with either the fortran or cmp
option.
The amount of code that is optimized varies depending on the
value of certain command line options, kapf directives, and
kapf assertions. For further information on the available
options, refer to the KAP for IBM Fortran User's Guide.
NOTE: Some options including related inlining and ipa
options which are described in the same section list all the
subheadings first and then the descriptions.
COMMAND LINE OPTIONS
-aggressive=<list>
Short name: -ag=<list>
Default value: -nag
-noaggressive
Short name: -nag
This optimization is safe when these conditions
are satisfied:
All COMMON blocks will be visible to kapf in
the course of processing the source file.
If the same COMMON block has two different
layouts, the different layouts do not pass
data between them.
There are no bounds violations, i.e., no
arrays that may be adjusted are being
referenced outside of their declared bounds.
Changing the leading dimension of arrays does
not affect the behavior of the program.
Most Fortran programs satisfy these conditions, and
enabling this optimization can yield significant
performance gains. This option must take one of the
following options:
a kapf can pad COMMON blocks to avoid cache
line collisions.
b kapf can adjust the leading dimensions of
arrays in COMMON away from a power of 2 if
the arrays are not used as actual arguments
to any user procedure calls.
ab Both options may be specified at the same
time.
To explicitly disable this transformation, specify
-noaggressive. See also the natural command line
option.
-arclimit=<integer>
Short name: -arclm=<integer>
Default value: -arclm=5000
The arclimit option is used to increase the size
of the dependence arc data structure that kapf
uses to perform data dependence analysis. This
data structure is dynamically allocated on a
loop-nest by loop-nest basis.
The formula which is used to estimate the number
of dependence arcs for a given loop nest is:
dependence_array_size=max(#_of_statements * 4,
arclimit value)
This is an estimate because kapf is assuming that
each statement, in the worst case, would have 4
dependence arcs.
-assume=<list>
Short name: -a=<list>
Default value: -a=cel
-noassume Short name: -nas
<list> can contain the following characters:
a Allow multiple aliasing
b Allow array bounds violation
c Constant arguments are assigned to
temporaries in procedure and function calls
e Equivalenced variables do not refer to same
memory location inside one DO loop nest
l Last value assignments are necessary
-cache_prefetch_line_count=<integer[,integer]>
Short name: -cplc=<integer[,integer]>
Default value: -cplc=0
This command line option describes the number of
additional lines that are prefetched into the
cache during a cache miss.
-cacheline=<integer>
Short name: -chl=<integer>
Default value: -chl=128 bytes
The cacheline option informs kapf of the width of
the memory channel in bytes between cache and main
memory.
-cachesize=<integer>
Short name: -chs=<integer>
Default value: -chs=64 Kbytes
The cachesize option informs kapf of the size in
kilobytes of the cache memory.
-cmpoptions=<list>
Short name: -cp=<list>
Default value: -cp=in
-nocmpoptions
Short name: -ncp
The cmpoptions option specifies optional
additional information for inclusion in the
transformed code, Pfile.f, file. The only
information selectable is special line number
comments -cmpoptions=i.
Specifying -cmpoptions=i instructs kapf to create
the transformed code from its internal data
structures. (The i stands for internal.)
Specifying -nocmpoptions will instruct kapf to use
lines from the source file, where feasible. Using
the internal data structures for the code will
provide consistent indentation and formatting, but
also all new labels and other changes from the
source code. This may make relating source and
transformed code more difficult.
-complex=<integer>
Short name: -cx=<integer>
Default value: -cx=8
The complex option specifies a size in bytes, N,
for the default size of COMPLEX variables. When
N=0, use the ordinary default length for COMPLEX
variables.
-[no]datasave
Short name: -[n]ds
Default value: -nds
The datasave option instructs kapf to treat local
variables in a subroutine or function which appear
in DATA statements as if they were also in SAVE
statements. That is, their values will be
retained between invocations of the subroutine or
function. This is the practice of many commercial
Fortran compilers. This choice affects certain
optimizations performed by kapf. The nodatasave
option complies with the Fortran-77 standard.
-directives=<list>
Short name: -dr=<list>
Default value: -dr=ackv
-nodirectives
Short name: -ndr
The directives option tells kapf which directives
to accept. kapf directives and assertions use the
following syntax:
C*$* key word(s)
C*$* key word(s) (argument)
C*$* ASSERT key word(s) (argument)
Directives and assertions work regardless of whether
the initial C precedes the *$* string. In other words,
the initial C is optional. The initial C, the ASSERT,
and the key words are case-insensitive.
The directives switches are as follows:
a kapf assertions
c Cray CDIR$ and CMIC$ directives
k kapf C*$* or *$* directives
v VAST CVD$ directives
The kapf directives which kapf accepts are described in
Chapter 4 of the KAP for IBM Fortran User's Guide. kapf
assertions are described in Chapter 5 of the KAP for
IBM Fortran User's Guide.
For example, -directives=k enables kapf directives
only, whereas -directives=ka enables both kapf
directives and assertions. Any combination of the
above switches is acceptable. To disable all of the
above options, enter -nodirectives on the command line.
kapf assertions are similar in form to directives, but
they assert program characteristics that kapf may use
in its optimizations. (See Chapter 5.) The acceptance
of assertions can also be controlled with the C*$*
ASSERTIONS and C*$* NOASSERTIONS directives. In XLF,
the recognition of compiler directives can be activated
by compiler switches:
-qdirective=char-trigger-constant-list
-qnodirective [char-trigger-constant-list]
The equivalent kapf command line options are:
-directive=<directive type>
-[no]dlines
Short name: -[n]dl
Default value: -ndl
The dlines option allows a D in column 1 to be
treated like a character space. The rest of that
line is then parsed as a normal Fortran statement.
By default, kapf treats these lines like comments.
This option is useful for the inclusion or
exclusion of debugging lines. The nodlines
default instructs kapf to flag any D line
statements appearing in the user's source program
as being syntactically incorrect.
-dpregisters=<integer>
Short name: -dpr=<integer>
Default value: -dpr=16
The dpregisters option specifies the number of
DOUBLE PRECISION registers each processor has.
-each_invariant_if_growth=<integer>
Short name: -eiifg=<integer>
Default value: -eiifg=20
When a loop contains an IF statement whose
condition does not change from one iteration to
another, loop invariant, the same test must be
repeated for every iteration. The code can often
be made more efficient by floating the IF outside
the loop and putting the THEN and ELSE sections
into their own loops.
This gets more complicated when there is other
code in the loop since a copy of it must be
included in both the THEN and ELSE loops. eiifg
is the number of additional lines of code for each
IF floated outside a loop. The maximum value is
100. The total amount of additional code
generated in a program unit through invariant IF
floating can be limited with the
max_invariant_if_growth option.
-[no]escape
Short name: -[n]escape
Default value: off
The escape command line option causes the \
(backslash) character to be treated as an escape
character.
-fortran[=<file>]
Short name: -f[=<file>]
Default value: filename with .cmp extension
-nofortran
Short name: -nf
The fortran option directs kapf to place the
optimized Fortran program in a transformed program
file (the compile file). The default name of the
Fortran output file is derived from the input file
by inserting a P before the source filename. If
-fortran=file or -f=file is specified, the Fortran
output file is written to that file. The default
name of the Fortran output file is derived from
the input filename. If -fortran=file is specified,
the Fortran output file is written to that file.
If -nf is specified, the generation of a
transformed Fortran file is disabled.
-fpregisters=<integer>
Short name: -fpr=<integer>
Default value: -fpr=32
The fpregisters option specifies the number of
single precision, i.e., ordinary floating point,
registers each processor has.
-[no]freeformat
Short name: -[n]free
Default value: -nfree
The freeformat command line option removes the
standard column restrictions for Fortran source
code. (See your system's Fortran Language
Reference Manual for more information.)
Setting -freeformat=f90 or just -freeformat
allows kapf to accept Fortran 90 style free
format.
Setting -freeformat=ibm allows kapf to accept
IBM's old freeformat.
The freeformat option is off by default, and the
usual Fortran 77 conventions apply.
-fuse Short name: -fuse
Default value: -fuse
The fuse command line option enables loop fusion,
a conventional compiler optimization that
transforms two adjacent loops into a single loop.
The use of data-dependence tests allows fusion of
more loops than is possible with standard
techniques. The option scalaropt=2 or the option
optimize=5 is required to enable loop fusion.
-[no]generateh
Short name: -[n]genh
Default value: off
kapf needs two passes to resolve Fortran 90
forward declarations; the first pass, the
generateh pass, builds the information needed to
analyze the program; the second pass, the useh
pass, uses this information to resolve the forward
references. The generateh and useh command line
options control which of these passes is run.
If neither of these options is specified, which is
the default situation, the kapf driver invokes
kapf twice, first with generateh and then with
useh.
If, however, either of the options or either of
their NO forms is specified (nogenh or nouseh),
the kapf driver will perform only one kapf pass
and pass through the options specified. Note that
it is illegal to specify both [no]generateh and
[no]useh.
These command line options cause the following to
occur:
-generateh
causes kapf to perform only the first pass
and build the information needed to resolve
Fortran 90 forward references.
-useh
causes kapf to use the information built by
the first pass.
Advanced users can speed up kapf using these
options. For example, if the input to kapf
contains no Fortran 90 forward references
(such as internal procedures), kapf can be
invoked with nogenerateh or with useh to
eliminate the first pass.
Note that the -hdir=directoryname command
line option specifies the name of the
directory where the genh pass stores the
temporary files containing information about
forward references. The useh command line
option picks up the information from that
directory. The default is the current
directory.
-hdir=<directoryname>
Short name: -hdir=<directoryname>
Default value: current directory
The hdir=directoryname command line option
specifies the name of the directory where the genh
pass stores the temporary files containing
information about forward references. The useh
command line option picks up the information from
that directory. The default is the current
directory.
-hoist_loop_invariants=<list>
Short name: -hli=<list>
Default value: -hli=1
This command line option controls code hoisting of
loop-invariant expressions from loops.
-[no]ignoreoptions
Short name: -[n]ig
Default value: -nig
The ignoreoptions option allows the user to direct
kapf to ignore a C*$*OPTIONS or *$*OPTIONS card at
the beginning of a file thereby having the command
line options override the options card.
-include=<path-name>
Short name: -inc=<path-name>
Default value: off
The include option allows the user to specify
alternate directories for locating the files
specified in INCLUDE directives. An INCLUDE file
whose name does not begin with a slash (/) is
sought first in the directory containing the file
containing the INCLUDE statement or directive,
then in the directory named in the include option.
-inline[=<names>]
Short name: -inl[=<names>]
Default value: off
-noinline=<names>
Short name: -ninl=<names>
-ipa[=<names>]
Short name: -ipa[=<names>]
Default value: off
-noipa=<names>
Short name: -nipa=<names>
The inline option provides kapf with a list of
routines to inline. The ipa option provides kapf
with a list of routines to analyze. Note that
inline and ipa are mutually exclusive; they cannot
both be specified on the same kapf run. If either
option is given without an argument list, kapf
will try to inline or analyze all the called
subroutines and functions in the inlining (or IPA)
universe specified by the inline_from../ipa_from..
options, subject to restrictions imposed by the
inline_depth and inline_looplevel/ipa_looplevel
options. If a list of names is included, for
example:
-inline=mkcoef,yval
then just the routines named will be inlined or
analyzed. In the optional list of routines, names
can be separated by commas or colons.
A list of routines must be included with noinline
or noipa. All routines in the inlining or ipa
universe are candidates for inlining or ipa
analysis except the listed ones. See the
description of inlining and interprocedural
analysis in Chapter 6.
The [no]inline and [no]ipa options can be
overridden by the C*$* [NO]INLINE and C*$* [NO]IPA
directives. (See Chapters 4 and 6 for more
information on these directives.)
-inline_and_copy=<names>
Short name: -inlc=<names>
Default value: off
The inline_and_copy command line option functions
like the inline option except in the case where
all CALLs or references in the source file that
kapf is processing to a subprogram are inlined. In
that case, the text of the routine is not
optimized but is copied unchanged to the
transformed code file. This option is intended
for use when inlining routines from the same file
as the call. This option has no special effect
when the routines being inlined are being taken
from a library or another source file.
When a subprogram has been inlined everywhere it
is used, leaving it unoptimized saves compilation
time. When a program involves multiple source
files, the unoptimized routine will remain
available for other source files to reference it
so no errors will result.
NOTE: the inline_and_copy algorithm assumes that
all CALLs and references to the routine precede it
in the source file. If the routine is referenced
after the text of the routine and that particular
call site cannot be inlined, the unoptimized
version of the routine will be invoked.
-inline_create=<file>
Short name: -incr=<file>
Default value: off
-ipa_create=<file>
Short name: -ipacr=<file>
Default value: off
The inline_create and ipa_create options instruct
kapf to build a library file containing partially
analyzed routines for later inlining. The library
created is used with the inline_from_libraries or
ipa_from_libraries option. Libraries created with
inline_create can be used with either inlining or
interprocedural analysis since they contain
essentially complete descriptions of the functions
included. Libraries created with ipa_create can
be used only with interprocedural analysis since
they do not have the complete text of the
functions, just the data relationships
information.
Any filename can be used for the library name. An
extension .klib is preferred for maximum
compatibility with the ...from_libraries options.
-inline_depth=<integer>
Short name: -ind=<integer>
Default value: -ind=10
The inline_depth option sets the maximum level of
subprogram nesting which kapf will attempt to
inline. Higher values instruct kapf to trace
CALLs and function references further. The values
and their meanings are:
_>1 Inline routines to this depth.
0 Use the default value.
-1 Inline only routines which do not contain
subroutine CALLs or function references.
Note that there is no corresponding ipa_depth option.
Interprocedural analysis examines only the called
routine itself and does not attempt to trace CALLs
further.
-inline_from_files=<file>
Short name: -inff=<file>
Default value: current source file
-ipa_from_files=<file>
Short name: -ipaff=<file>
Default value: current source file
-inline_from_libraries=<file>
Short name: -infl=<file>
Default value: off
-ipa_from_libraries=<file>
Short name: -ipafl=<file>
Default value: off
The .._from_.. options provide kapf with the
locations of functions available for
inlining/interprocedural analysis. The total set
of available functions is called the inlining or
IPA universe.
The .._from_files options take the names of source
files and directories containing source files.
Including a directory, for example,
-ipaff=/usr/ipalib is equivalent to the UNIX
notation /usr/ipalib/*.c. Do not use shell wild
card characters in the list of files and
directories.
The .._from_libraries options take the names of
libraries created with the .._create options and
directories containing such libraries. In
directories, the kapf libraries are identified by
the extension .klib.
Multiple files/libraries or directories may be
given in one .._from_.. option, separated by
commas. Multiple .._from_.. options may be
specified on the command line.
-inline_looplevel=<integer>
Short name: -inll=<integer>
Default value: -inll=2
-ipa_looplevel=<integer>
Short name: -ipall=<integer>
Default value: -ipall=2
The .._looplevel options enable the user to limit
inlining to just functions which are referenced in
nested loops where the effects of reduced function
call overhead or enhanced optimizations will be
multiplied.
The parameter is defined from the most deeply
nested function reference. For example, -inll=1
restricts inlining to functions referenced in the
deepest loop nest. -inll=3 restricts inlining to
those routines referenced at the three deepest
levels. The FOR loop nest level of each function
reference is included in the optional calling tree
section of the listing files.
The C*$*INLINE and C*$*IPA directives, when
enabled, are not affected by the looplevel
restrictions.
-inline_manual
Short name: -inm
Default value: off
-ipa_manual
Short name: -ipam
Default value: off
The inline_manual and ipa_manual options instruct
kapf to recognize the C*$* [NO]INLINE and C*$*
[NO]IPA directives. This allows manual control
over which functions are inlined/analyzed at which
call sites.
The default is to ignore these directives. They
are enabled when any inlining or IPA option,
respectively, is given on the command line. When
inline_manual or ipa_manual is included on the
command line, the corresponding directives are
enabled without activating the automatic inlining
algorithms. Since C*$* [NO]INLINE and C*$*
[NO]IPA are not otherwise affected by the
inline=/ipa, inline_depth, and .._looplevel
command line options, they can be used along with
command line control to select functions or call
sites which the regular selection algorithm would
reject.
-integer=<integer>
Short name: -int=<integer>
Default value: -int=4
The integer option specifies a size in bytes, N,
for the default size of INTEGER variables. When
-integer=2 or 4, take INTEGER*N as the default
INTEGER type. When -integer=0, kapf uses the
ordinary default length for INTEGER variables.
-[no]interleave
Short name: -[n]intl
Default value: -intl
The interleave switch controls loop unrolling and
rescheduling. Interleaved unrolling can help the
compiler recognize quad-word loads and stores,
which are more efficient than ordinary loads and
stores. It does this by first unrolling the loop
as in ordinary loop unrolling. Second, the
statements in the loop are interchanged where
possible to make references to the same array
adjacent to each other.
-library_calls=<name>
Short name: -lc=<name>
Default value: off
The library_calls option directs kapf to replace
sections of code with calls to standard numerical
library routines which have the same
functionality. This can simplify the source code,
and if a version of the library which has been
highly tuned for the target machine is available,
the use of the standard package will improve
performance of the application program.
The argument for library_calls identifies which
library to create CALLs for. It is one of
blas Basic Linear Algebra Subroutines
essl Engineering and Scientific Subroutine Library
-limit=<integer>
Short name: -lm=<integer>
Default value: -lm=21000
In order to reduce the compile time, kapf
estimates how long it spends analyzing each loop
nest construct. If a loop is too deeply nested,
kapf ignores the outer loop and recursively visits
the inner loops. The loop nest limit is a rough
dial to control what kapf considers too deeply
nested. For further information, refer to the KAP
for IBM Fortran User's Guide.
-lines=<integer>
Short name: -ln=<integer>
Default value: -ln=55
The listing generated by kapf is paginated for
printing on a line printer. The number of lines
per page on the listing may be changed using the
-lines=
option. The -lines=0 option directs kapf to
paginate at subroutine boundaries.
-list=<file>
Short name: -l=<file>
Default value: -nl
-nolist Short name: -nl
The list option informs kapf where to place the
annotated listing of the user's program. If
-list=<file> is given, the listing is written to
the specified file. If the list option is not
specified, no listing file is generated.
-listingwidth=<integer>
Short name: -lw=<integer>
Default value: -lw=80
The listingwidth option sets the maximum line
length for the listing file produced by kapf. This
setting affects the format of the loop summary
table, -listoptions=l, and kapf options table,
-listoptions=k. The alternative, 80, is more
convenient for looking at the listing file on most
terminals. The default, 132, is optimal for most
line printers. At present, no other values are
allowed.
-listoptions=<list>
Short name: -lo=<list>
Default: -lo=k
The listoptions option tells kapf what optional
information to include in the listing file.
listoptions controls inclusion of the following
information:
c Calling tree at end of program listing
k kapf options used, printed at end of each
program unit
l Loop-by-loop optimization table
n Names of program unit
o Original program listing
p Performance statistics compilation
s Summary of optimizations performed
t Transformed program listing
The transformed program displayed by t is recorded in
the transformed code file regardless of whether the
user requests -listoptions=t.
To disable all of the above switches and produce no
listing file, enter -nolist on the command line.
-logical=<integer>
Short name: -log=<integer>
Default value: -log=4
The logical option specifies a size in bytes, N,
for the default size of LOGICAL variables. When
N=1, 2, or 4, take LOGICAL*N as the default
LOGICAL type. When -logical=0, kapf uses the
ordinary default length for LOGICAL variables.
-machine=<list>
Short name: -ma=<list>
Default value: -ma=s
-nomachine
Short name: -nma
n Prefer not stride-1 inner loops
s Prefer stride-1 inner loops
-max_invariant_if_growth=<integer>
Short name: -miifg=<integer>
Default value: -miifg=500
When a loop contains an IF statement whose
condition does not change from one iteration to
another, loop invariant, the same test must be
repeated for every iteration. The code can often
be made more efficient by floating the IF outside
the loop and putting the THEN and ELSE sections
into their own loops.
This gets more complicated when there is other
code in the loop since a copy of it must be
included in both the THEN and ELSE loops. The
max_invariant_if_growth option allows the user to
limit the total size in non-comment lines of code
for each program unit beyond which invariant IF
restructuring will not add more.
This can be controlled on a loop-by-loop basis
with the C*$* MAX_INVARIANT_IF_GROWTH (<integer>)
directive. The maximum amount of additional code
generated in a single loop through invariant IF
floating can be limited with the
each_invariant_if_growth option and directive.
-minvector=<integer>
Short name: -mv=<integer>
Default value: -mv=2
The minvector option sets the minimum vector
length. Loops with constant loop bounds that are
less than this number are not vectorized. For
most applications, very short vectors are less
efficient than the equivalent scalar loops.
-[no]namepartitioning=<integer>,<integer>
Short name: -[n]namepart=<integer>,<integer>
Default value: -nnamepart
namepartitioning looks at distinct array names and
limits the number of arrays that appear in a loop.
-[no]onetrip=<list>
Short name: -[n]1=<list>
Default value: -n1
The onetrip option allows the user to specify
onetrip DO loops. Many pre-Fortran 77 compilers
implemented DO loops that would always have at
least one iteration even if the initial value of
the loop control variable were higher than the
final value. This option informs kapf that the
program being processed contains loops which need
the onetrip feature.
-optimize=<integer>
Short name: -o=<integer>
Default value: -o=5
The optimize option sets the optimization level
ranging from 0 to 5. The meanings of levels are
as follows:
0 No loop optimization
1 Only simple analysis and optimization
Induction variable recognition enabled
Interchange DO loops
2 Perform lifetime analysis
Perform more powerful data dependence tests
3 Perform more loop interchanging
Special case data dependence tests used
Wraparound variables recognized
4 Loop interchanging around reductions if
roundoff _> 1
Perform more exact data dependence tests
5 Array expansion enabled
-real=<integer>
Short name: -rl=<integer>
Default value: -rl=4
The real option specifies a size in bytes, N, for
the default size of REAL variables. When N=4, or
8, take REAL*N as the default REAL type. When
-real=0, kapf uses the ordinary default length for
REAL variables.
-roundoff=<integer>
Short name: -r=<integer>
Default value: -r=3
The roundoff option allows the user to specify the
potential change in roundoff error that is
acceptable. For instance, if an arithmetic
reduction is accumulated in a different order than
in the original program, the roundoff error is
built up differently and the final result may
differ from that of the original program. While
the difference is usually insignificant, certain
restructuring transformations performed by kapf
must be disabled in order to obtain exactly the
same answers as the original program.
kapf classifies its transformations by the amount
of difference in roundoff error that can
accumulate so the user can decide what level of
roundoff error differences to allow. The roundoff
command line option has the values 0 to 3.
The meanings of the roundoff levels are below.
Each roundoff level is cumulative, performing what
is listed below for that level in addition to what
is listed for lower levels.
0 No roundoff-changing transformations
1 Expression simplification and code floating
enabled
Arithmetic reductions recognized
Loop interchanging around arithmetic
reductions is allowed if optimize _> 4
Loop rerolling when scalaropt _> 2
2 Reciprocal substitution performed to move a
division outside a loop
3 Recognize real induction variables if
scalaropt _> 2 or optimize _> 1
Multiple INTEGER divisions such as L/M/N can
be rotated to L/(M*N)
Memory management enabled if -scalaropt=3
-routine Short name: -rt
Default value: off
The routine command line option allows the user to
specify command line options that will apply only
to specific routines within the source code kapf
is optimizing. The only command line options that
can be specified by routine are:
each_invariant_if_growth, max_invariant_if_growth,
optimize, roundoff, scalaropt, skip, unroll,
unroll2.
The syntax of the routine command line option is
the following:
xlf -Pk filename -Wp, options, -routine, options for routine
Note that command line options can be specified
that apply to all routines in the source code.
Note also that routinename must be a routine in
source_code_filename. Note finally that options
for these routines must be options from the list
directly above. The skip option indicates that
there will be no processing of the associated
routine.
For example, the following command line calls
kapf, passes the scalaropt command line to all
code in program.1 and passes the roundoff and
optimize command line options only to routine.1
which is part of program.1.
xlf -Pk -Wp -scalaropt=3, -routine=routine.1, -roundoff=0, -optimize=0 program.1
The use of the routine command line option implies
that directives equivalent to the specified
command line options are to be asserted only while
processing particular routines. The effect is as
if the implied directives were inserted at the top
of the associated routines.
The option -skip can be specified as one of the
options for these routines, which indicates that
there is to be no processing of the associated
routine(s).
Note that with the introduction of the routine
command line option, the kapf command line becomes
order-dependent to some extent. There are two
halves to the command line: the first half which
looks like any other kapf command line and the
second half which is a series of invocations of
-routine and the options associated with them.
The usual rules for matching option names also
apply for invocations of -routine, i.e., opt
matches optimize and unr matches unroll.
-save=<list>
Short name: -sv=<list>
Default value: -sv=aa
The save option instructs kapf on how to handle
the storage class of local scalar variables.
In particular, kapf can be instructed to perform
live variable analysis to help kapf decide whether
to save the value of a local scalar variable
between invocations of a function or a routine by
generating a SAVE statement. kapf can also be
instructed to treat the default storage class of
all local scalar variables as either AUTOMATIC or
STATIC. In any case, kapf will not delete or
ignore a SAVE statement coded by the user.
There are four possible settings for the -save
option:
Specifying -save=all (-save=a) tells kapf not
to perform live variable analysis. However,
all variables local to a function or a routine
and COMMON blocks will be treated as if they
are SAVEd.
Specifying -save=manual (-save=m) tells kapf
not to perform live variable analysis. kapf
assumes that the user has inserted the
necessary SAVE statements into the code and
performs no corresponding analysis of its own.
The user-written SAVE statements are assumed to
be correct and sufficient.
Specifying -save=manual_adjust (-save=ma)
instructs kapf to perform live variable
analysis. SAVE statements will be added for
variables which are used before being defined
on at least one path from one entry point to
the routine.
Specifying -save=all_adjust (-save=aa)
instructs kapf to perform live variable
analysis and to treat all local variables as
SAVEd, except those which are defined before
use in all paths from all entry points and
which are not in user-written SAVE statements.
Saving local variables may be required for
correct execution of the program, but can
restrict kapf optimizations. Accordingly,
-save=ma should be used with caution.
-scalaropt=<integer>
Short name: -so=<integer>
Default value: -so=3
The scalaropt option sets the level of dusty deck
and other serial transformations performed.
Unlike the scalaropt command line option, the C*$*
SCALAROPT directive sets the level of loop-based
optimizations only, e.g., unrolling, and not
straight-code optimizations, e.g., dead code
elimination.
0 No scalar optimizations performed
1 IF loops changed into DO loops
Simple code floating out of loops performed
Inaccessible or unused code removed (dead
code elimination)
Forward substitution of variables performed
Dusty deck IF transformations enabled to
reduce the number of IF statements
2 Full range of scalar optimizations performed
Invariant IFs floated out of loops
Induction variable recognition
Loop rerolling if roundoff _> 1
Loop unrolling, loop peeling
3 Memory management performed if -roundoff=3
Additional dead code elimination performed
during output conversion
-scan=<integer>
Short name: -scan=<integer>
Default value: -scan=72
The scan option allows the user to set the length
of the Fortran input lines. kapf will ignore or
treat as a comment characters on columns beyond
the value of the scan option. The values must be
in the range 72-132.
-setassociativity=<integer>
Short name: -sasc=<integer>
Default value: -sasc=4
The setassociativity option provides information
on the mapping of physical addresses in main
memory to cache pages. The default says that a
datum in main memory can be placed in one place in
cache.
-[no]skip Short name: -[n]sk
Default value: off
The skip command line option allows the user to
specify that there is to be no processing of the
associated routine(s).
-[no]small_loops
Short name: -[n]small_loops
Default value: -nsmall_loops
The small_loops option tells kapf how to handle
loop unrolling. (See the description of the
mixed_loops option for more information concerning
loop unrolling optimizations.)
When kapf unrolls a loop, it usually splits the
loop into two parts--the primary unrolled loop and
a cleanup or remainder loop to ensure that the
number of iterations in the main loop is a
multiple of the unrolling factor. kapf usually
precalculates the beginning index for the
remainder, but it is inefficient to precalculate
this index for a small loop. The small_loops
option tells kapf to precalculate the beginning
index to be used in the remainder. The
nosmall_loops option, which is the default, tells
kapf to use the original first index for the
remainder.
The [no]small_loops option should not be used with
the mixed_loops option. You can choose which of
these options to use by applying the guidelines in
the following table.
Iterations in loops Recommended KAP option
fewer than 15 -small_loops
more than 30 -nosmall_loops
unknown or variable -mixed_loops
-suppress=<list>
Short name: -su=<list>
Default value: no suppression
kapf produces several types of messages that range
from syntax warning and error messages to messages
about the optimizations performed. Use the
options below to disable the following classes of
messages:
d Data dependence messages
e Syntax error messages
i Informational messages
n Not optimized messages
q Questions
s Standardized messages
w Syntax warning messages
-syntax=<list>
Short name: -sy=<list>
Default value: accepts standard F90
The syntax option directs kapf as to whether or
not to check for compliance with certain syntactic
rules. The allowed values for the syntax option
are as follows:
a Checks for strict compliance with ANSI F90
standard
-[no]translate
Short name: -[n]translate
Default value: -notranslate
This switch translates VAX structures into Fortran
90 derived types. The syntax for this switch is
-translate=v.
-[no]type Short name: -[n]ty
Default value: -nty
The type option instructs kapf to issue warning
messages for variables not explicitly typed. This
is as if there were an IMPLICIT NONE at the top of
each program unit. The notype default suppresses
this checking.
-unroll=<integer>
Short name: -ur=<integer>
Default value: -ur=1
The -scalaropt _> 2 option must be in effect to
engage the unroll option.
The syntax for unroll is as follows:
Long form: -unroll=<#it>
Short form: -ur=<#it>
where <#it> is the maximum number of iterations to unroll
=0 use default values to unroll
=1 no unrolling
The default, 1, means at most 1 iteration.
-unroll2=<integer>
Short name: -ur2=<integer>
Default value: -ur2=80
The -scalaropt _> 2 option must be in effect to
engage the unroll2 option.
The syntax for unroll2 is as follows:
Long form: -unroll2=<weight>
Short form: -ur2=<weight>
where <weight> is the maximum weight, estimate of work, in
an unrolled loop. Work is estimated by counting
operands and operators in a loop.
The default, 80, means a maximum work of 80 in an
unrolled iteration.
-unroll3=<integer>
Short name: -ur3=<integer>
Default value: -ur3=1
The -scalaropt _> 2 option must be in effect to
engage the unroll2 option.
The syntax for unroll3 is as follows:
Long form: -unroll3=<weight>
Short form: -ur3=<weight>
where <weight> is the maximum weight, estimate of work, in
an unrolled loop. Work is estimated by counting
operands and operators in a loop.
The default, 1, means that a loop must have a
minimum weight of 1 for kap to unroll it.
-useh Short name: -useh
Default value: off
See description for -generateh.
FILES
/usr/lpp/kapf/bin/fppkthe KAP program
file.f or file.for or file.f90Fortran source file
Pfile.f optimized Fortran file
SEE ALSO
In addition, the KAP for IBM Fortran User's Guide contains
information on directives and assertions that you may want
to include in your program when running kapf.