Compaq KAP C/OpenMP
for Tru64 UNIX

Order Number: AA--PXEFK--TE

This document provides information about how to run and use Compaq KAP C/OpenMP on Compaq Tru64 UNIX systems.

Revision/Update Information: This is a revised document.

Operating System and Version: Compaq Tru64 UNIX Versions 4.0F, 5.0, and 5.0A

Software Versions: Version 4.1
Compaq C Version 6.1

Compaq Computer Corporation
Houston, Texas

© 1993 Compaq Computer Corporation

© 1993 Kuck & Associates, Inc.

Compaq, the Compaq logo, Compaq C, and Compaq Fortran, Registered in U.S. Patent and Trademark Office.

KAP is a trademark of Kuck & Associates, Inc.

UNIX is a registered trademark of The Open Group.

All other product names mentioned herein may be trademarks or registered trademarks of their respective companies.

Compaq shall not be liable for technical or editorial errors or omissions contained herein. The information in this document is subject to change without notice. This document is available on CD-ROM.

Contents

Index

This document describes how to use Compaq KAP C/OpenMP software on Compaq Tru64 UNIX systems.

Intended Audience

This document is a guide for KAP users working with Compaq C on Compaq Tru64 UNIX systems.

Structure of This Document

This document is organized into the following chapters and appendixes:

• Chapter 1 provides an overview of KAP for C software.
• Chapter 2 presents general information on how to run KAP on Tru64 UNIX systems. The sections describing how to compile and run programs with KAP are specific to single-processor systems.
• Chapter 3 presents information on how to compile and run programs with KAP on symmetric multiprocessor (SMP) systems.
• Chapter 4 describes the command-line switches used at run time to alter KAP default activities, such as causing KAP to set optimization levels or enable/disable classes of transformations.
• Chapter 5 describes KAP assertions and directives. Assertions provide KAP with additional information about the input program that would normally be unknown at compile time. Directives are in-line instructions to KAP and function in many ways like command-line switches.
• Chapter 6 contains more information about inlining, Interprocedural Analysis (IPA), and the KAP command-line switches and directives that control them.
• Chapter 7 offers examples of KAP transformations from ordinary C code into more efficient forms. Users just becoming acquainted with KAP may want to begin by browsing in this chapter.
• Chapter 8 describes the KAP optional listing file and messages to users.
• Appendix A describes data dependence analysis and explains how KAP uses this information to determine if a given loop can be optimized.

Associated Documents

This document is part of the KAP document set that also includes:

• Compaq KAP C/OpenMP for Tru64 UNIX Installation Guide
• Compaq KAP C/OpenMP for Tru64 UNIX Quick Reference
• Compaq KAP C/OpenMP for Tru64 UNIX Cover Letter

Conventions

The following are equivalent terms used in this document:

• KAP, KAP C/OpenMP, Compaq KAP
• C, Compaq C
• Pragmas, directives

The following table lists the other conventions used in this guide.

Convention	Description
< >	Angle brackets denote command input you replace with the appropriate value.
( )	Parentheses containing a single command value denote the default value. For example, (-optimize=5) denotes 5 is the default value. Parentheses containing hyphenated value ranges denote that you choose a value from the range.
[ ]	Square brackets indicate optional syntax. For example: #pragma _KAP [no]inline [(name)]
UPPERCASE and lowercase	The Tru64 UNIX system differentiates between lowercase and uppercase characters. Literal strings that appear in text, examples, syntax descriptions, and function descriptions must be typed exactly as shown.
italic type	Italic type indicates complete titles of manuals and keywords, as well as product names.

KAP for C is a source-to-source preprocessor that restructures C code for improved performance and better utilization of the memory hierarchy of Tru64 UNIX systems. Additionally, KAP performs parallel decomposition to take advantage of shared memory and symmetric multiprocessors. By eliminating inefficiencies and bottlenecks, KAP enables you to get your answers faster without time-consuming, hand-recoding of applications programs.

Because KAP makes it possible to run serial C programs efficiently on advanced architecture computers without hand-recoding, the original programs remain portable and users need not concern themselves with the details of each machine.

KAP optimizations include:

• Memory Management (Data Locality)
• Function Inlining
• Interprocedural Analysis (IPA)
• Dead-Code Elimination
• Local Variable Identification
• Loop Reordering
• Induction Variable Recognition
• Global Forward Substitution
• Variable Lifetime Analysis
• Loop Peeling

The KAP conversion process is designed to operate effectively without intervention from you. KAP provides a large set of command-line switches and inline assertions and directives that the advanced user can use for even better performance on specific codes. The optional KAP listing file includes information that identifies the parts of the source program that could benefit from such attention.

This chapter gives general information about KAP syntax, file-naming conventions, and optimizing programs with KAP. Sections describing how to compile and run programs with KAP are specific to single-processor Tru64 UNIX systems. For information on how to compile and run programs with KAP on multiprocessor systems, see Chapter 3.

Compaq KAP C/OpenMP for Tru64 UNIX can be run in either of two modes:

• The recommended mode is to invoke KAP with the kcc command. The kcc command accepts C source code as input, calls KAP to preprocess and optimize that input, calls the C compiler and linker, and produces compiled object code as output. Thus, kcc executes both KAP and the C compiler.
• KAP can also act as a standalone preprocessor with the kapc command that does not call the compiler or the linker.

The following command-line switches provide maximum general optimization: -optimize=5, -roundoff=3, and -scalaropt=3. These are the default settings for these switches.

See Section 2.3 for an explanation of how to pass command-line switches to KAP and Chapter 4 for details about what is controlled by each switch's levels.

2.2 Installing KAP

KAP is installed on the Tru64 UNIX system with the system command setld. See the Compaq KAP C/OpenMP for Tru64 UNIX Installation Guide for details.

The directory that contains the executable KAP file must be in your path; or a command such as kapc must be aliased to point to the executable file.

If you are a frequent user of KAP, you may find it convenient to add an alias to your .cshrc files so that a kapc command with preferred switches is available. Contact your system manager for the directory location of the executable KAP file.

2.3 Compiling a Program Using the kcc Driver

The kcc command invokes a driver program that automatically calls KAP, the C compiler, and the linker. The following examples show how to use kcc:

• Using kcc default KAP and C compiler switch settings
  To use kcc to compile myprog.c with the default C compiler and KAP switch settings, enter the command:

  kcc myprog.c

  
  The kcc command uses the KAP preprocessor on myprog.c, compiles the result with the Compaq C compiler, links the object code into an executable image, and produces the following files:

  • myprog.cmp.c --- the optimized source file
  • myprog.out --- the annotated source file showing default KAP switch settings
  • a.out --- the executable file
  
  The kcc command sets the following C compiler switches by default:
  • -D__KAP --- defines the name __KAP.
  • -U_INLINE_INTRINSICS --- stops the compiler from inlining intrinsic functions. KAP currently does not support the inlining of intrinsic functions by the compiler.
  • -tune host --- determines whether the host architecture is ev4 or ev5 and adjusts the compiler accordingly.
  • -migrate --- uses the Compaq C compiler instead of the acc compiler.
  • -non_shared --- instructs the linker to use the archive libraries.
  • -fast --- provides a single method for turning on a collection of compiler optimizations.
  
  To see a list of the KAP switches and Compaq C compiler switches passed by kcc, use the -verbose switch as follows:

  kcc myprog.c -v

  
  An example of the output:

  oursmp>kcc -v sin.c timing.o -lm /usr/bin/cc -C -E -D__KAP -U_INLINE_INTRINSICS sin.c > ./ktmpa24807.c /usr/bin/kapc -cmp=./sin.cmp.c -nolist ./ktmpa24807.c -tune=EV4 KAP/Tru64_U_C 4.0 k010710 990730 02-Sep-1999 16:48:52 0 errors in file ./ktmpa24807.c /usr/bin/cc -migrate -fast -v ./sin.cmp.c timing.o -lm -tune host -non_shared -lkio /usr/lib/cmplrs/cc.dtk/gemc_cc -D__LANGUAGE_C__ -D__unix__ -D__osf__ -D__alpha -D_SYSTYPE_BSD -D_LONGLONG -D__digital__ -D__arch64__ -g0 -O3 -std -intrinsics -ansi_alias -ansi_args -assume nomath_errno -assume trusted_short_alignment -D_INTRINSICS -D_INLINE_INTRINSICS -D_FASTMATH -float -fp_reorder -ifo -readonly_strings -v -tune ev4 -I/usr/include.dtk -o /tmp/deccobjAAAaayhca ./sin.cmp.c These macros are in effect at the start of the compilation. ----- ------ --- -- ------ -- --- ----- -- --- ------------ -D__DECC -D__osf__ -D__arch64__ -D__PRAGMA_ENVIRONMENT -D_LONGLONG -D__digital__ -D__X_FLOAT=0 -D__DATE__="Sep 2 1999" -D__DECC_MODE_RELAXED -D__DECC_VER=60160104 -D_SYSTYPE_BSD -D__ALPHA -D__IEEE_FLOAT -D_FASTMATH -D__unix__ -D_INLINE_INTRINSICS -D__TIME__="16:48:53" -D__Alpha_AXP -D__INITIAL_POINTER_SIZE=0 -D_INTRINSICS -D__STDC__=0 -D__LANGUAGE_C__ -D__alpha /usr/lib/cmplrs/cc.dtk/gemc_cc: 0.18u 0.07s 0:00 92% 0+9k 0+11io 0pf+0w 9stk+1328mem /usr/lib/cmplrs/cc.dtk/ld -g0 -O3 /usr/lib/cmplrs/cc.dtk/crt0.o /tmp/deccobjAAAaayhca timing.o -lm -non_shared -lkio -qlots -lc /usr/lib/cmplrs/cc.dtk/ld: 0.15u 0.13s 0:00 23% 0+13k 45+58io 14pf+0w 13stk+2024mem rm ./ktmpa24807.c mv sin.cmp.o sin.o

• Passing KAP switches to kcc
  The -ckapargs switch specifies one or more KAP command switches to the KAP preprocessor. For example, to use kcc to optimize and compile the file myprog.c using KAP switches for general optimization, enter the command:

  kcc -ckapargs='-optimize=5 -roundoff=3 -scalaropt=3 \ -list=myprog_annotated.lis' myprog.c

  
  The following files result:

  • myprog.cmp.c --- the optimized source file
  • myprog_annotated.lis --- the annotated source file renamed with the KAP/C -list switch
  • a.out --- the executable file
  
  For descriptions of all KAP command switches, see Chapter 4.
• Passing Compaq C compiler switches to kcc
  Any command-line switch that is valid for the C compiler or the linker is valid for the kcc command. You can specify compiler switches, linker switches, and KAP switches on the same line. For example, to optimize and compile the file myprog.c using KAP switches for general optimization and to specify the name of the executable file with the Compaq C compiler switch -o, enter the following command:

  kcc -ckapargs='-optimize=5 -roundoff=3 -scalaropt=3' \ -o myprog.exe myprog.c

  
  The following files result:

  • myprog.cmp.c --- the optimized source file
  • myprog.out --- the annotated source file
  • myprog.exe --- the executable file renamed with the -o switch
  
  The kcc command specifies the compiler switches -fast and -tune host, and the linker switch -non_shared by default. The -non_shared switch causes the image to be linked with archive libraries instead of with shared libraries. To override the -non_shared default, specify -call_shared on the command line, for example:

  kcc -call_shared myprog.c

The kcc command saves the optimized version of your source program followed by the extension .cmp.c in the source directory for use in debugging and profiling. You can override the KAP default of adding .cmp.c to the source program name with the -cmp switch. See Section 4.7.1 for more information.

2.5 KAP Command Switches Determined by Compiler Switches

Some C compiler switches automatically set KAP command switches or alter the default switch settings.

Explicitly calling the compiler switch -std1 causes KAP to be called with the command switch -syntax=a.

Explicitly calling the compiler switch -standard=common causes KAP to be called with the command switch -syntax=k.

Calling the C compiler without any compiler switches or with the compiler switch -std0 causes KAP to be called with the command switch -syntax=d.

2.6 Invoking the C Preprocessor

The kcc command invokes the C preprocessor before transforming a file with KAP. The name __KAP is defined for the C preprocessor in order to include alternate code in some system include files. Commands with the preprocess-only switch will terminate after the C preprocessor phase.

2.7 Preprocessing a Program Using kapc

For C programs that do not contain C preprocessor commands such as #define, #include, #ifdef, or macro definitions, use the following command to execute KAP as a standalone preprocessor:

kapc [kap_switch_string] myprog.c -cmp=myprog.cmp.c

The [kap_switch_string] is a list of one or more KAP command switches, for example:

kapc -inm -roundoff=2 myprog.c -cmp=myprog.cmp.c

For C programs that contain C preprocessor commands, the input file must first be preprocessed with the C compiler. Use the following commands:

cc -P -D__KAP -U_INLINE_INTRINSICS myprog.c kapc -cmp=myprog.cmp.c myprog.i

After preprocessing your program, give the optimized source file myprog.cmp.c to the compiler, as follows:

• DIGITAL UNIX Version 3.2:

  cc -migrate myprog.cmp.c -tune host -lkio -O4

• Tru64 UNIX, and DIGITAL UNIX Versions 4.0 and above:

  cc -migrate myprog.cmp.c -tune host -lkio -fast

For an explanation of the -migrate, -tune host, -lkio, -fast, and -U_INLINE_INTRINSICS switches, see Section 2.3.

Specify switches in lowercase with the syntax -switch[=value]. Do not leave spaces between the switch name and the value. Switches can appear before or after the input file as follows:

kapc -inm myprog.c -roundoff=2

KAP recognizes standard abbreviations for switches. Switches that take a list of names must have the names separated by commas and without spaces, for example:

-inff=file1.c,file2.c

Enclose KAP command switches passed through kcc by using the -ckapargs switch with single quotation marks, as follows:

kcc -ckapargs='-optimize=5 -roundoff=3 -scalaropt=3' -list myprog.c

C compiler switches, for example, -list, do not require quotation marks.

2.9 Using File Naming Conventions

Any input file name is acceptable. Output file names are written to stdout unless the -cmp command switch is specified.

When KAP detects an error condition, KAP writes a message to standard error.

2.10 Introducing the Five-Minute KAP Guide

This section describes how you can get maximum performance in your application programs in the shortest time.

This information can be used with both multiprocessor and single-processor systems, and with both Fortran and C versions of all KAP products. Therefore, the information may contain references to command-line switches or settings that are unavailable or are different from those in the KAP that you are using.

This section provides separate protocols for small and large programs. Small programs are defined as those that can be compiled and run quickly. Because the cost of each iteration is small, you can take risks. The information presented here further assumes that small programs have a small number of program units.

Large programs are defined as those that take more time to compile and run than it takes for you to check the results. A program can be large either because the source code is very large or because the execution time is long.

2.10.1 Optimizing Small Programs with KAP

Follow these guidelines to optimize small programs:

1. Compile the program without KAP, with minimum compiler optimization, and with all compiler run-time checks enabled. Note the execution time and verify the results. If the program fails at this step, there is little optimization you can do.
   Some older programs use standard-violating techniques that KAP will not transform safely. If KAP fails because of this problem, you cannot do much optimization.
   If you have the time and you know what the program is supposed to do, you can try to isolate the incorrect code, correct it, and proceed. This action may not be feasible for handling problems in large programs, but it might work for isolated portability problems.
   If the problem code is isolated and runs without KAP optimization, you may be able to use KAP on the rest of the program and leave out any problematic sections.
   You can also refer to Section 2.13. You may be able to diagnose and correct some problems, and then run KAP on your program successfully.
2. Compile without KAP but with maximum compiler optimization. Note the execution time and verify the results. If the program fails, reduce compiler optimization and try again.
3. Compile the fastest or best run without using KAP and run it again with profiling enabled (for example, gprof) to identify the program units that take the most time to run.
   If some time-intensive units have many iterative loops and arrays, then those units are good candidates for KAP loop optimizations. Go to step 4.
   If the units are not good candidates, lower-payoff optimizations, such as inlining, may provide some performance improvement, especially where inlining inside loop nests may also allow KAP to perform vectorization optimizations. If this is the case, go to step 6.
4. If the program compiles with minimum compiler optimization enabled, then turn on all optimization except inlining by invoking -optimize=4 and full compiler optimization.
5. If step 2 succeeds and the results are correct, try the suggestions described in the Section 2.12.
6. If step 2 fails, try reducing one optimization at a time (-roundoff=0, -scalaropt=1, -optimize=3, and any compiler optimizations) until the program runs correctly. Use the -lo=k switch setting to create a listing of the KAP command-line switches and settings.