# Compaq KAP C/OpenMP
for Tru64 UNIX
User Guide

Previous | Contents | Index

# Chapter 8
KAP Listing

This chapter describes the types of information available in the optional KAP listing. To determine KAP status and effectiveness, and to help you locate trouble spots where assertions or special transformations could help, KAP can list the optimizations it performed on each loop in the program.

For example, in some cases KAP might communicate to the user that any of three loops could have been concurrentized, but KAP concurrentized only the one it considered most profitable. In other cases, a concurrentizable loop is left serial, because it will execute faster in that form. Because KAP optimizations can produce correct but unexpected code, KAP puts a note in the loop table explaining the action.

KAP does not produce a listing file unless requested. See Chapter 4 for a description of the `-list` command-line switch.

The following section describes the listing information that you can specify with the `-listoptions` command-line switch. Then, an example of KAP output for syntax errors is presented. The last section of the chapter explains the descriptive messages in the loop table section of the listing.

See the `-cmpoptions` switch for the optional information available in the transformed code file.

# 8.1 Listing Information Available with -listoptions Switch

The `-listoptions` command-line switch tells KAP what optional information to include in the listing and error files. The listing file can contain any combination of the following messages about the optimizations performed, indicated by these values:

> `c` --- Calling tree of the entire program
> `k` --- KAP switches used presented at end of listing
> `l` --- Loop table
> `n` --- Print function names in error file
> `p` --- Compilation performance statistics
> `s` --- Summary table

The format of these listings follows. The source code used for the examples in this section was the transformed code from the `-inline=setup` example in Section 6.5.1. Information pertaining to just one function is for the first function of the source file. Default switches were used, except for `-list` , `-cmp` , and `-listoptions` .

## 8.1.1 Calling Tree (c)

The calling tree is listed after all functions have been compiled. Each function's calling tree information consists of the functions it calls, the loop nest level calls within that function, the total loop nest depth of the calls in that function (including the nesting level of calls to the unit itself), and the routines where that function itself is called.

When the calling tree is selected, a table of the variables used in each function is printed after that function is processed.

For example, the following table appears after the main function:

     CROSS REFERENCE TABLE

    Name              Type     Class       Storage
    ------------------------------------------------
    signgam           s.INT    Var         Static
    size_t            s.INT    Var         Automatic
    wchar_t           s.INT    Var         Automatic
    div_t              Struc   Var         Automatic
    ldiv_t             Struc   Var         Automatic
    optarg             Holl    Array       Static
    optind            s.INT    Var         Static
    optopt            s.INT    Var         Static
    opterr            s.INT    Var         Static
    ptrdiff_t         s.INT    Var         Automatic
       .
       .
       .
    _Kii1             s.INT    Var         Automatic
    _Kii2             s.INT    Var         Automatic
    _Kii3             s.INT    Var         Automatic
    _Kii4             s.INT    Var         Automatic
    _Kii5             s.INT    Var         Automatic
    _Kii6             s.INT    Var         Automatic
    _Kii7             s.INT    Var         Automatic
    _Kii8             s.INT    Var         Automatic
    _Kii9             s.INT    Var         Automatic
    _Kii10            s.INT    Var         Automatic
       .
       .
       .

    Abbreviations used in Source Program References

     A = used as actual argument
     D = Declared or Defined
     M = Contents may get modified
     U = Its value is used

                  Calling Tree

    line#         routines       at nest   max. aggregate nest

    1629          program main

    Calling Tree

    main

    Code Modules

    main      called from

## 8.1.2 KAP Switches (k)

The KAP switches table lists the settings of the command switches related to optimization. When the values are changed inside the function with directives, the values from the directives will not appear in this table.

Some of these switches cannot be set and are fixed for this version of KAP. See Chapter 4, KAP Command-Line Switches.

The following example shows the switch settings KAP used to optimize the source code. In this example, the `-tune` switch appears as the `-architecture` switch.

    KAP/Tru64_U_C   4.2 k010737s 010515 main Transformed  21-Aug-2001 15:16:02

    Switches Used for this Program Unit

               addressresolution=1            limit=50
               architecture=EV4
               arclimit=5000                  lines=55
                                              list=matmulc.out
               cacheline=32,32                listingwidth=132
               cache_prefetch_line_count=0    listoptions=kl
               cachesize=8
               chunk=1
               cmp=matmulc.cmp                machine=s
            no cmpoptions                     miifg=500
            no concurrentize                  minconcurrent=1000

                                           no namepartitioning
                                              natural
               dpregisters=32
                                              optimize=5
               eiifg=20
                                              processors=1
               fpregisters=32
            no fuse                           recursion
               fuselevel=0
               heaplimit=100                  roundoff=3
               hli=1                          scalaroptimize=3
                                              scheduling=e
            no inline                         setassociativity=1
            no inline_and_copy                signed
            no inline_create               no skip
               inline_depth=2              no stdio
            no inline_from_files           no suppress
            no inline_from_libraries       no syntax

               inline_looplevel=2             tablesize=24000000

            no inline_manual
               inline_optimize=0
               input=matmulc.i                unroll=4
               interchange                    unroll2=160
            no ipa                            unroll3=1
            no ipa_create
               ipa_depth=10
            no ipa_from_files
            no ipa_from_libraries
               ipa_looplevel=2
            no ipa_manual
               ipa_optimize=0

## 8.1.3 Loop Table (l)

The loop table is printed after each program unit (function) and shows what KAP did with each `for` loop in the function. If the loop could not be optimized, a reason is given. The loop table is the primary listing tool for understanding what KAP did with the program. Loop table messages that refer to do loops apply to C `for` loops.

The line messages are summaries of KAP actions for each loop (both loops in the original source code and loops that KAP generated). The loop to which each refers can be identified from the main loop table. The abbreviations used are explained after the main table.

    KAP/Tru64_U_C   4.2 k010737s 010515
                                    main  Loop Table 21-Aug-2001 15:16:02

    --------------------------------  Loop Table  --------------------------------

                             Nest
    Loop     Message         Level  Contains Lines
    ==============================================================================

    for j                    1      1637-1644 "matmul.i"

        1. Enhanced Scalar   2      1637, 1640, 1644 "matmul.i"

    for i                    2      1639-1642 "matmul.i"

        1. Enhanced Scalar   1      1637, 1639-1640, 1642, 1644 "matmul.i"

             Line:1639  NV   Not an inner loop.

    for j                    1      1646-1653 "matmul.i"

        1. Enhanced Scalar   2      1646, 1649, 1653 "matmul.i"

    for i                    2      1648-1651 "matmul.i"

        1. Enhanced Scalar   1      1646, 1648-1649, 1651, 1653 "matmul.i"

             Line:1648  NV   Not an inner loop.

    for j                    1      1658-1670 "matmul.i"

             Line:1658  NO   Loop was asserted serial by directive.
             Line:1658  I    Do loop was inserted here.
             Line:1658  SO   Strip loop for strip mining with block size 24.
             Line:1658  SO   Block loop for strip mining with block size 24.
             Line:1658  SO   Loop unrolled 3 times to improve scalar performance.
             Line:1658  SO   Cleanup-loop for loop unrolling added.
             Line:1660  NV   Not an inner loop.
             Line:1660  I    Do loop was inserted here.
             Line:1660  SO   Strip loop for strip mining with block size 24.
       .
       .
       .

    Abbreviations Used
     NO       not optimized
     DD       data dependence
     SO       scalar optimization
     I        inserted
     INF      informational

## 8.1.4 Name (n)

The function names, as processed, are printed in the error file. The first line gives the name of the source file, as shown in the following example:

    KAP/Tru64_U_C   4.2 k010737s 010515   21-Aug-2001 15:16:02
    matmul.i:
       main:
    0 errors in file matmul.i

## 8.1.5 Compilation Performance Statistics (p)

The compilation performance statistics list the number of lines in the function, the compilation time in seconds, and the compilation rate in lines per minute. This information is also summarized after all functions have been compiled.

    KAP/Tru64_U_C   4.2 k010737s 010515    main Compilation Statistics
    21-Aug-2001 15:16:02

    Compilation Statistics For the Routine main
        1670  Lines in Program Unit
        1.48  CPU Time
    67702  Lines Per Minute
        0  Symbol Cache File Writes
        0  Symbol Cache File Reads
        0  Name Table File Writes
        0  Name Table File Reads

    Cumulative Compilation Statistics
        1670  Lines in Source File << includes definitions and blank lines
           1  Program Units in Source File
        1.48  CPU Time
       67702  Lines Per Minute
           0  Symbol Cache File Writes << for functions with many symbols
           0  Symbol Cache File Reads
           0  Name Table File Writes << for functions with many symbols
           0  Name Table File Reads
         575  Lines in Compile File

## 8.1.6 Summary Table (s)

The summary table shows how many loops appeared in the function and how many loops were optimized in different ways:

    KAP/Tru64_U_C   4.2 k010737s 010515
                              main  Optimization Summary  25-Aug-2001  15:18:03

                 7 loops total

                 3 loops vectorized
                 2 with scalar directive
                 2 with inner loop

# 8.2 Syntax Error/Warning Messages

KAP tries to match the syntax error and warning messages of the compiler it runs with. A file that will cause the compiler to issue a syntax error will cause KAP to issue a syntax error.

When a syntax error is found, KAP stops reading the input file after the current function definition has been read. The function with the syntax error will not be sent to the output file, so only code without syntax errors is put into the KAP transformed code file.

When illegal syntax or any other error is found, KAP writes a message to the error file on Tru64 UNIX systems, as shown in the following example:

    Error: line 3: file 3_crlib.c: idx undefined.

KAP also may write syntax warning messages to the error file, but optimization proceeds. Syntax warning messages are issued for Tru64 UNIX constructs that are illegal, but whose intent is clear.

# 8.3 Loop Table Messages

The loop table ( `-listoptions=l` ) includes an entry for each loop indicating whether it was optimized, or why it was not. This section lists the possible messages and gives a brief explanation for each. The two most common reasons for a loop to be left serial are that the iterations were not independent and that the loop contained I/O statements.

Messages referring to do loops apply to C `for` loops:

- bad intrinsic call --- Loop optimization may give unpredictable results.
- bad operator --- Loop optimization may give unpredictable results.
- branches out of-into loop --- Code may be iteration-order dependent.
- cannot allocate temporary array --- Usually, a data dependence could have been lifted by expanding a scalar into an array, but there was a name conflict.
- concurrentized --- Should not appear. If it does, indicates miscellaneous optimization.
- distributed --- Loop divided into smaller loops, some of which may be further optimized.
- DO statement not optimizable --- For example, the iteration count of a while loop is not known.
- ELSE IF --- Some loops inside nested IFs require more information to optimize than KAP can deduce.
- empty loop --- Loop with no executable statements inside (nothing to optimize), or loop whose body will never be executed.
- fused with other loops --- Adjacent loops joined into a larger loop to reduce overhead.
- GOTO in loop --- Possible flow patterns are too complicated for KAP.
- I/O statement in loop --- Input/Output is assumed to be order-dependent.
- left as do loop --- Usually, a data dependence prevented concurrentization.
- left as DOALL --- Loop was already explicitly concurrent in the input dialect of C.
- left as a serial loop --- Usually, too much synchronization required.
- nested IFs --- The branching pattern was too complicated.
- no optimizable statements --- For example, no arithmetic in loop.
- not enough work --- Optimization overhead greater than the expected gain.
- optimization disabled --- By a directive or assertion.
- replaced by calls --- Some loop nests can be replaced by a call to a library routine.
- scalar directive --- A directive or assertion turned off optimization.
- scalar inner loop --- Inside a parallel loop already.
- scalar mode preferable --- Usually, too much synchronization needed.
- too many inner loops --- LIMIT > integer VERY complicated loop nest; KAP will try to optimize the inner loops. Try increasing `-limit` .
- too many stmts/DD arcs --- VERY complicated loop nest; try increasing `-arclimit` .
- too much synchronization --- Loop iterations depend on each other in a complicated way; the overhead from untangling them would be greater than expected gain.
- unoptimizable call --- Function with unknown side effects.
- unoptimizable operation --- Character string manipulation.
- unoptimizable statements in loop --- Usually I/O.
- unoptimizable symbol use --- Variable used in a complicated way.
- unoptimizable variable or operation type --- Only numerical work is easily concurrentized.
- unrolled --- Loop could not be concurrentized, so KAP unrolled it (see explanations of unrolling in Chapter 4 and Chapter 7).
- unrolled completely, fused or removed --- Loop has been turned into straight-line code, joined to another loop, or dropped entirely.
- unrolled; already in a parallel loop --- Loop could be concurrentized, but target machine does not support nested parallelism; KAP unrolled it.
- vectorized --- Can be used for optimizations that enhance the vectorization performed by the C compiler.

Previous | Next | Contents | Index