KAPC(V1.4) KAP for IBM C (Kuck & Associates) KAPC(V1.4)
NAME
kapc - optimizing C preprocessor
SYNOPSIS
kapc filename [ options ]
DESCRIPTION
kapc is a source-to-source optimizing C preprocessor that
discovers opportunities to optimize the code. kapc can
produce two files with the following extensions where
filename is the name of the source file:
filename.cmp
Contains the optimized C source code that is
accepted by the compiler. The default is standard
output.
filename.out
Contains the kapc listing file. The contents of
this file varies depending on the value of the
listoptions command line option. The default is
no listing file.
The names can be set with the cmp and list options.
kapc optimizes C by restructuring certain portions of code
and then adding directives where possible. The amount of
code that is optimized varies depending on the value of
certain kapc command line options, directives, and
assertions. For further information, refer to the KAP for
IBM C 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
-address_resolution=<integer>
Short name: -arl=<integer>
Default name: arl=1
The address_resolution option informs kapc what
level of data aliasing (the use of multiple names
for the same memory location) may be present in
the program. When there might be multiple ways
for the same variable to be referenced, kapc is
more cautious about transforming the code in ways
that might change the order in which variables and
arrays are used.
The associated pragma #pragma _KAP arl=<n> has the
same meaning. The command line option is
equivalent to a pragma at the beginning of the
file and is thus overridden by other pragmas later
in the file.
The meanings of the individual levels are:
0 kapc makes no assumptions about data aliasing
1 A pointer will not contain its own address
2 No objects represented by function parameters
overlap in memory
kapc assumes no parameter aliasing
Equivalent to #pragma _KAP distinct for all
parameters
3 Globals, parameters, and locals form distinct
groups
4 No aliases for objects
-arclimit=<integer>
Short name: -arclm=<integer>
Default value: -arclm=5000
The arclimit option sets the size of the
dependence arc data structure that kapc uses to
perform data dependence analysis. This data
structure is dynamically allocated on a loop nest
by loop nest basis. By default this data
structure is allocated with a size = max (# of
statements * 4, arclimit value). If a loop
contains too many dependence relationships and
cannot be represented in the dependence data
structure, kapc will give up optimization of the
loop.
The user may use the arclimit option to increase
the size of the data structure to enable kapc to
perform more optimizations. Most users do NOT
need to change this value.
-cacheline=<integer>
Short name: -chl=<integer>
Default value: -chl=128 bytes
The cacheline option informs kapc 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 kapc of the size in
kilobytes of the cache memory.
-cmp[=<file>]
Short name: -cmp[=<file>]
-nocmp Short name: -ncmp
Default value: standard output
The cmp compilable option instructs kapc to place
the optimized C program in a specified transformed
program file. If -cmp=file is specified, the
transformed C is written to that file.
On UNIX systems, the default file for the
transformed code is standard output. If -cmp is
given without a filename, the transformed code is
written to <file>.cmp, where <file> is the input
filename with any trailing .c stripped off.
To disable generation of the C output file, enter
-nocmp on the command line.
-cmpoptions=<list>
Short name: -cp=<list>
-nocmpoptions
Short name: -ncp
Default value: off
The cmpoptions option specifies optional
additional information for inclusion in the
transformed code file, .cmp. The only information
currently selectable is special line number
comment cmpoptions=i.
Special line numbers are # line comments which may
appear in the transformed program file in order to
reference line numbers of the original code. The
line in the transformed code that immediately
follows a # line comment is either the transformed
version of the line in the original code that is
referenced or a line which kapc inserted before
the referenced line. The name of the source file
from the command line is included in the form it
had on the kapc command line.
i Insert special numbers that reference the
original code
-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. 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]fuse Short name: -[n]fuse
Default value: -nfuse
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.
-inline[=<names>]
Short name: -inl[=<names>]
Default value: off
-noinline=<names>
Short name: -ninl=<names>
Default value: off
-ipa[=<names>]
Short name: -ipa[=<names>]
Default value: off
-noipa=<names>
Short name: -nipa=<names>
Default value: off
The inline and ipa options provide kapc lists of
routines to inline or analyze. If the option is
given without an argument list, kapc will try to
inline/analyze all the called functions in the
inlining universe specified by the
inline_from../ipa_from.. options below. If a list
of names is included, for example,
-inline=mkcoef,yval, then just the routines named
will be inlined/analyzed.
The inline and ipa command line options are
overridden by the #pragma _KAP inline and #pragma
_KAP ipa directives.
The no forms enable inlining and interprocedural
analysis but provide lists of routines that are
NOT to be inlined or analyzed. The lists of
routine names are required.
-inline_and_copy[=<names>]
Short name: -inlc[=<names>]
Default value: off
The inline_and_copy option functions like the
inline option except that if all CALLs or
references to a subprogram are inlined, the text
of the routine is not optimized but is copied
unchanged to the transformed code file. This is
intended for use when inlining routines from the
same file as the call. Inline_and_copy has no
special effect when the routines being inlined are
taken from a library or another source file.
After 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 still be
available in case one of the other source files
contains a reference to 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 kapc 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 kapc will attempt to
inline. Higher values instruct kapc to trace
CALLs and function references further. The values
and their meanings are:
1-10 Inline routines to this depth.
0 Use the default value.
-1 Inline only routines which do not contain
subroutine CALLs or function references.
The #pragma _KAP [no]inline and #pragma _KAP [no]ipa
directives, when enabled, are not affected by the
inline_depth restrictions.
-inline_from_files=<files>
Short name: -inff=<files>
Default value: primary source file
-ipa_from_files=<files>
Short name: -ipaff=<files>
Default value: primary source file
-inline_from_libraries=<files>
Short name: -infl=<files>
Default value: off
-ipa_from_libraries=<files>
Short name: -ipafl=<files>
Default value: off
The .._from_.. options provide kapc 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 kapc libraries are identified by
the extension .klib.
Multiple files/libraries or directories may be
given in one .._from_.. option separated by
commas or colons. Multiple .._from_.. options may
be specified on the command line.
Note that for C, the files specified must have
already been preprocessed and prefereably kapped.
-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. -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 inline and ipa pragmas, 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
kapc to recognize the #pragma _KAP [no]inline and
#pragma _KAP [no]ipa directives. This allows
manual control over which functions are
inlined/analyzed at which call sites.
The default is to ignore these pragmas. They are
enabled when any inlining or ipa option,
respectively, is given on the command line. The
..manual options enable the directives without
activating the automatic inlining algorithms.
Since #pragma _KAP [no]inline and #pragma _KAP
[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.
-input=<file>
Short name: -i=<file>
Default value: whatever filename is given on the
command line.
On most systems, the kapc user can simply place
the source file name on the kapc command line.
The -input=<filename> option is included for
compatibility with other KAP products and certain
main frame operating systems.
On UNIX systems, specifying -input without a file
name will instruct kapc to read the source file
from standard input. If this is done, the
transformed code and optional listing file will be
written to standard output unless explicit file
names are given with the cmp and list options.
-[no]interleave
Short name: -[no]interleave
Default value: -interleave
The interleave option asks KAP/C to do interleaved
unrolling. Interleaved unrolling can help the
compiler recognize quad-word loads and stores
which are more efficient than ordinary loads and
stores.
-limit=<integer>
Short name: -lm=<integer>
Default value: -lm=21000
In order to reduce the compilation time, kapc
estimates how long it spends analyzing each loop
nest construct. If a loop is too deeply nested,
kapc ignores the outer loop and recursively visits
the inner loops. The loop nest limit is a rough
dial to control what kapc considers too deeply
nested. For further information, refer to the KAP
for IBM C User's Guide .
-lines=<integer>
Short name: -ln=<integer>
Default value: -ln=55
The lines option enables kapc's listing to be
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 kapc to paginate only at subroutine
boundaries.
-list=<file>
Short name: -l=<file>
Default: -nl
-nolist Short name: -nl
The list option allows kapc to generate an
annotated listing of the user's program. If
-list=file is specified, the listing is written to
the specified file. If -list is specified without
a filename, the listing file is written to
filename.out, where filename is the input file
name with any trailing .c stripped off. To
disable generation of the listing file, enter
-nolist on the command line.
-listoptions=<list>
Short name: -lo=<list>
Default: off
The listoptions option tells kapc what information
to include in the listing file. listoptions can
enable the following optional information to be
included in the listing:
c Calling tree at end of program listing
k kapc options used, printed at end of each
program unit
l Loop-by-loop optimization table
n Program unit names as processed to standard
error
o Annotated listing of original program
p Compilation performance statistics
s Summary of the loop optimizations performed
t Annotated listingof the transformed program
-machine=<list>
Short name: -ma=<list>
Default: -ma=s
-nomachine
Short name: -nma
The default -machine=s instructs kapc to prefer to
optimize DO loops which generate stride-1 memory
references.
-machine=n tells kapc to prefer to optimize loops
which generate non-stride-1 memory references.
-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 number of additional lines of code
generated in each program unit through invariant-
IF restructuring.
The value of this option is the desired maximum
number of lines of code in a program unit (main
program or function). Invariant IF floating will
be performed only until it would cause the program
to exceed that limit, then it is disabled for the
rest of the program unit. Note that other kapc
transformations can add or delete lines so that
the final size of the program unit may differ from
what Invariant IF Floating alone would have left
it.
This can be controlled on a loop-by-loop basis
with the #pragma _KAP 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.
-mixed_loops
Short name: -mixed_loops
Default value:
The mixed_loops option tells kap how to handle
loop unrolling. (See the description of the
small_loops option for more detail.) The
mixed_loops option should be specified when loops
in the source file have variable numbers of
iterations.
This option will produce optimal code when the
loops in the source file that are the best
candidates for optimization have an indeterminate
number of iterations or are known to have both
large and small numbers of iterations. The
mixed_loops option should not be used with the
small_loops or nosmall_loops options.
-namepartitioning
Short name: -namepart
Default value: off
The namepartitioning option looks at distinct
array names and limits the number of arrays that
appear in a loop.
-optimize=<integer>
Short name: -o=<integer>
Default value: -o=5
The optimize option sets the optimization level
ranging from the integer 0, minimum optimization,
to the integer 5, maximum optimization. The user
should consult the KAP for IBM C User's Guide to
determine the correct optimization level for a
specific application.
0 No loop optimization
1 Only simple loop optimization
Induction variable recognition enabled
2 Perform lifetime analysis to determine last
value assignment of scalars
Perform more powerful data dependence tests
3 Special techniques used to break data
dependence cycles
Triangular loops recognized
Loop interchanging to improve memory
referencing
Wraparound variables recognized
Perform special case data dependence tests
4 Two versions of a loop generated to break
data dependence arc
Perform more exact data dependence
5 Array expansion enabled
-roundoff=<integer>
Short name: -r=<integer>
Default value: -r=3
The roundoff option allows the user to specify the
change from serial roundoff error that is
tolerable. If an arithmetic reduction is
accumulated in a different order than in the
scalar program, the roundoff error is accumulated
differently and the final result may differ from
that of the original program's output. While the
difference is usually insignificant for certain
algorithms, reordering the computations may
significantly change the results. Certain
restructuring transformations performed by kapc
must be disabled in order to obtain exactly the
same answers as the scalar program.
kapc 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 is allowable. The
meanings of the switch values are as follows:
0 No roundoff-changing transformations
Roundoff error same as unoptimized program
1 Roundoff error same or better than in
unoptimized program
Strength reduction enabled
Expression simplification from forward
substitution between binary and unary
operators
Code floating if scalaropt _> 1
Loop interchanging around serial arithmetic
reductions
Loop rerolling if scalaropt _> 2
2 Reciprocal substitution performed to move a
division outside a loop
Reciprocal subsitution causes slightly larger
roundoff error
3 Roundoff error may be significantly different
from unoptimized programs
Recognize real induction variables if
scalaropt _> 2 or optimize _> 1
Memory management enabled if -scalaropt = 3
-routine Short name: -rt
Default value: off
The routine option allows the user to specify
command line options that will apply only to
specific routines within the source code kap is
optimizing. The only command line options that
can be specified by routine are:
each_invariant_if_grouth, optimize, roundoff,
max_invariant_if_growth, scalaropt, unroll,
unroll2.
The syntax of the routine command line option is
the following:
kap <-options> -routine=<routinename>,<routinename>
<options for these routines> -routine=<routinename> <options for
these routines> source_code_filename
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.
For example, the following command line calls KAP,
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.
kap -scalaropt -routine=routine.1 -roundoff -optimize 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 KAP command line becomes
order-dependent to some extent. There are two
halves to the command line: the first half, which
looks like any other KAP 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.
-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
#pragma _KAP 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 Only simple scalar optimizations performed
Dead code elimination
Global forward substitution
Dusty deck IF transformations performed to
reduce number of IF statements
2 Full range of scalar optimizations performed
Invariant IFs floated out of loops
Induction variable recognition
Loop rerolling with roundoff >0
Loop unrolling, loop peeling
3 Memory management enabled if -roundoff = 3
Perform dead code elimination during output
conversion
-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, 1, says that
a datum in main memory can be placed in any of
four places in cache. If all four of these cache
pages are in use, one of them will have to be
reassigned in order to copy the newly accessed
page into cache.
-[no]small_loops
Short name: -[n]small_loops
Default value: -nosmall_loops
The small_loops option tells KAP how to handle
loop unrolling. (See the description of the
mixed_loops option for more information concerning
loop unrolling optimizations.)
When kap 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. kap 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 KAP to precalculate the beginning
index to be used in the remainder. The
nosmall_loops option, which is the default, tells
KAP 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
-stdio Short name: -stdio
Default value: off
The stdio qualifier instructs kapc to perform
strength reduction on calls to certain functions
in the standard I/O library. Programs which use
functions such as printf heavily will generally
have improved I/O performance when this is done.
-scalaropt=3 is required to enable this
transformation.
-syntax=<list>
Short name: -sy=<list>
Default value: off
The syntax option directs kapc to check for
compliance with certain syntactic rules for the C
programming language. The default is not to check
for strict ANSI-C compliance. The syntax options
are as follows:
a Checks for strict compliance with ANSI-C
standard
k Accepts Kernighan & Ritchie C
w Accepts Sun C
-unroll=<integer>
Short name: -ur=<integer>
Default name: -ur=4
The scalaropt _> 2 option must be in effect to
engage the unroll option.
The syntax for unroll is as follows:
Short forms: -unroll=<#it>
Short forms: -ur=<#it>
where <#it> is the maximum number of iterations to unroll
=0 use default values to unroll
=1 no unrolling
The default, 4, means at most 4 iterations.
-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 or 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/unrolled
iteration of 80.
FILES
/usr/bin/kapc the KAP program
file.c C source file
file.cmp C transformed file
file.out listing file
SEE ALSO
cc (1), cpp (1)
KAP for IBM C User's Guide
COMMENTS
This command runs kapc as a standalone product. It is
normally run as part of the C compilation stream. The KAP
for IBM C User's Guide contains information on directives
and assertions that you may want to include in your program
when running kapc.