Viewing profiling information with showpdf

With the showpdf utility, you can view the following types of profiling information that is gathered from your application:

Block-counter profiling
Call-counter profiling
Value profiling
Cache-miss profiling, if you specified the -qpdf1=level=2 option during the -qpdf1 phase.

You can view the first two types of profiling information in either text or XML format. However, you can view value profiling and cache-miss profiling information only in XML format.

Syntax


>>-showpdf--+--------+--+--------------+--+----------------+--+-------+-><
            '-pdfdir-'  '- -f--pdfname-'  '- -m--pdfmapdir-'  '- -xml-'

Parameters

pdfdir: Is the directory that contains the profile-directed feedback (PDF) file. If the PDFDIR environment variable is not changed after the -qpdf1 phase, the PDF map file is also contained in this directory. If this parameter is not specified, the compiler uses the value of the PDFDIR environment variable as the name of the directory.
pdfname: Is the name of the PDF file. If this parameter is not specified, the compiler uses ._pdf as the name of the PDF file.
pdfmapdir: Is the directory that contains the PDF map file. If this parameter is not specified, the compiler uses the value of the PDFDIR environment variable as the name of the directory.
-xml: Determines the display format of the PDF information. If this parameter is specified, the PDF information is displayed in XML format; otherwise it is displayed in text format. Because value profiling and cache-miss profiling information can be displayed only in XML format, the PDF report in XML format contains more information than the report in text format.

Usage

A PDF map file that contains static information is generated during the -qpdf1 phase, and a PDF file is generated during the execution of the resulting application. The showpdf utility needs both the PDF and PDF map files to display PDF information in either text or XML format.

If the -qpdf1=level=2 option is specified during the -qpdf1 phase, several PDF and PDF map files might be generated. Then if you want to view the profiling information, you need to run the showpdf utility for each pair of PDF and PDF map files.

By default, the PDF file is named ._pdf, and the PDF map file is named ._pdf_map. If the PDFDIR environment variable is set, the compiler places the PDF and PDF map files in the directory specified by PDFDIR. Otherwise, if the PDFDIR environment variable is not set, the compiler places these files in the current working directory. If the PDFDIR environment variable is set but the specified directory does not exist, the compiler issues a warning message. To override the defaults, use the -qpdf1=pdfname option to specify the paths and names for the PDF and PDF map files. For example, if you specify the -qpdf1=pdfname=/home/joe/func option, the resulting PDF file is named func, and the PDF map file is named func_map. Both of the files are placed in the /home/joe directory.

If the PDFDIR environment variable is changed between the -qpdf1 phase and the execution of the resulting application, the PDF and PDF map files are generated in separate directories. In this case, you must specify the directories for both of these files to the showpdf utility.

Notes:

PDF and PDF map files must be generated from the same compilation instance. Otherwise, the compiler issues an error.
PDF and PDF map files must be generated during the same profiling process. It means that you cannot mix and match PDF and PDF map files that are generated from different profiling processes.
You must use the same version and PTF level of the compiler to generate the PDF file and the PDF map file.
The showpdf utility accepts only PDF files that are in binary format.
You can use the PDF_WL_ID environment variable to distinguish the multiple sets of PDF counters that are generated by multiple training runs of the user program.

The following example shows how to use the showpdf utility to view the profiling information for a Hello World application:

The source for the program file hello.c is as follows:

#include <stdio.h>  
void HelloWorld()
{
   printf("Hello World");
}
main()
{
   HelloWorld();
   return 0;
}

Compile the source file.
```
xlc -qpdf1 -O hello.c
```
Run the resulting executable program a.out using a typical data set or several typical data sets.

If you want to view the profiling information for the executable file in text format, run the showpdf utility without any parameters.

showpdf

The result is as follows:

HelloWorld(67):  1 (hello.c)

Call Counters:
4 | 1  printf(69)

Call coverage = 100% ( 1/1 )

Block Counters:
2-4 | 1
5 |
5 | 1

Block coverage = 100% ( 2/2 )
  
-----------------------------------
main(68):  1 (hello.c)

Call Counters:
8 | 1  HelloWorld(67)

Call coverage = 100% ( 1/1 )

Block Counters:
6-9 | 1
10 |

Block coverage = 100% ( 1/1 )

Total Call coverage = 100% ( 2/2 )
Total Block coverage = 100% ( 3/3 )

If you want to view the profiling information in XML format, run the showpdf utility with the -xml parameter.

showpdf -xml

The result is as follows:

  <?xml version="1.0" encoding="UTF-8" ?> 
- <XLTransformationReport xmlns="http://www.ibm.com/2010/04/CompilerTransformation" version="1.0">
  - <CompilationStep name="showpdf">
    - <ProgramHierarchy>
      - <FileList>
        - <File id="1" name="hello.c">
          - <RegionList>
              <Region id="67" name="HelloWorld" startLineNumber="2" /> 
              <Region id="68" name="main" startLineNumber="6" /> 
            </RegionList>
          </File>
        </FileList>
      </ProgramHierarchy>
      <TransformationHierarchy /> 
    - <ProfilingReports>
      - <BlockCounterList>
        - <BlockCounter regionId="67" execCount="1" coveredBlock="2" totalBlock="2">
          - <BlockList>
              <Block index="3" execCount="1" startLineNumber="2" endLineNumber="4" /> 
              <Block index="2" execCount="0" startLineNumber="5" endLineNumber="5" /> 
              <Block index="4" execCount="1" startLineNumber="5" endLineNumber="5" /> 
            </BlockList>
          </BlockCounter>
        - <BlockCounter regionId="68" execCount="1" coveredBlock="1" totalBlock="1">
          - <BlockList>
              <Block index="3" execCount="1" startLineNumber="6" endLineNumber="9" /> 
              <Block index="2" execCount="0" startLineNumber="10" endLineNumber="10" /> 
            </BlockList>
          </BlockCounter>
        </BlockCounterList>
      - <CallCounterList>
        - <CallCounter regionId="67" execCount="1" coveredCall="0" totalCall="0">
          - <CallList>
              <Call name="printf" execCount="1" lineNumber="4" /> 
            </CallList>
          </CallCounter>
        - <CallCounter regionId="68" execCount="1" coveredCall="0" totalCall="0">
          - <CallList>
              <Call name="HelloWorld" execCount="1" lineNumber="8" /> 
            </CallList>
          </CallCounter>
        </CallCounterList>
        <ValueProfileList /> 
        <CacheMissList /> 
      </ProfilingReports>
    </CompilationStep>
  </XLTransformationReport>

Voice your opinion on getting help information

Ask IBM compiler experts a technical question in the IBM XL compilers forum