-qpdf1, -qpdf2

Pragma equivalent

None.

Purpose

Tunes optimizations through profile-directed feedback (PDF), where results from sample program execution are used to improve optimization near conditional branches and in frequently executed code sections.

Optimizes an application for a typical usage scenario based on an analysis of how often branches are taken and blocks of code are run.

Syntax


        .-nopdf2-----------------------------.   
        +-nopdf1-----------------------------+   
>>- -q--+-pdf1--+--------------------------+-+-----------------><
        |       +-=--pdfname--=--file_path-+ |   
        |       +-=--unique----------------+ |   
        |       +-=--nounique--------------+ |   
        |       +-=--exename---------------+ |   
        |       +-=--defname---------------+ |   
        |       '-=--level--=--+-0-+-------' |   
        |                      +-1-+         |   
        |                      '-2-'         |   
        '-pdf2--+--------------------------+-'   
                +-=--pdfname--=--file_path-+     
                +-=--exename---------------+     
                '-=--defname---------------'

Defaults

-qnopdf1, -qnopdf2

Parameters

defname

Reverts a PDF file to its default file name if the -qpdf1=exename option is also specified.

exename

Specifies the name of the generated PDF file according to the output file name specified by the -o option. For example, you can use -qpdf1=exename -o func func.c to generate a PDF file called .func_pdf.

level=0 | 1 | 2

Specifies different levels of profiling information to be generated by the resulting application. The following table shows the type of profiling information supported on each level. The plus sign (+) indicates that the profiling type is supported.

Table 1. Profiling type supported on each -qpdf1 level
Profiling type	Level
Profiling type	0	1	2
Block-counter profiling	+	+	+
Call-counter profiling	+	+	+
Value profiling		+	+
Cache-miss profiling			+

-qpdf1=level=1 is the default level. It is equivalent to -qpdf1. Higher PDF levels profile more optimization opportunities but have a larger overhead.

Notes:

Only one application compiled with the -qpdf1=level=2 option can be run at a time on a particular processor.
Cache-miss profiling information has several levels. If you want to gather different levels of cache-miss profiling information, set the PDF_PM_EVENT environment variable to L1MISS, L2MISS, or L3MISS (if applicable) accordingly. Only one level of cache-miss profiling information can be instrumented at a time. L2 cache-miss profiling is the default level.
If you want to bind your application to a specified processor for cache-miss profiling, set the PDF_BIND_PROCESSOR environment variable equal to the processor number.

pdfname= file_path

Specifies the directories and names for the PDF files and any existing PDF map files. By default, 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. The name of the PDF map file follows the name of the PDF file if the -qpdf1=unique option is not specified. For example, if you specify the -qpdf1=pdfname=/home/joe/func option, the generated PDF file is called func, and the PDF map file is called func_map. Both of the files are placed in the /home/joe directory. You can use the pdfname suboption to do simultaneous runs of multiple executable applications using the same directory. This is especially useful when you are tuning dynamic libraries with PDF.

unique | nounique

You can use the -qpdf1=unique option to avoid locking a single PDF file when multiple processes are writing to the same PDF file in the PDF training step. This option specifies whether a unique PDF file is created for each process during run time. The PDF file name is <pdf_file_name>.<pid>. <pdf_file_name> is ._pdf by default or specified by other -qpdf1 suboptions, which include pdfname, exename, and defname. <pid> is the ID of the running process in the PDF training step. For example, if you specify the -qpdf1=unique:pdfname=abc option, and there are two processes for PDF training with the IDs 12345678 and 87654321, two PDF files abc.12345678 and abc.87654321 are generated.

Note: When -qpdf1=unique is specified, multiple PDF files with process IDs as suffixes are generated. You must use the mergepdf program to merge all these PDF files into one after the PDF training step.

Usage

The PDF process consists of the following three steps:

Compile your program with the -qpdf1 option and a minimum optimization level of -O2. By default, a PDF map file named ._pdf_map and a resulting application are generated.
Run the resulting application with a typical data set. Profiling information is written to a PDF file named ._pdf by default. This step is called the PDF training step.
Recompile and link or just relink the program with the -qpdf2 option and the optimization level used with the -qpdf1 option. The -qpdf2 process fine-tunes the optimizations according to the profiling information collected when the resulting application is run.

Notes:

The showpdf utility uses the PDF map file to display part of the profiling information in text or XML format. For details, see Viewing profiling information with showpdf. If you do not need to view the profiling information, specify the -qnoshowpdf option during the -qpdf1 phase so that the PDF map file is not generated. For details of -qnoshowpdf, see -qshowpdf.
When option -O4, -O5, or any level of option -qipa is in effect, and you specify the -qpdf1 or -qpdf2 option at the link step but not at the compile step, the compiler issues a warning message. The message indicates that you must recompile your program to get all the profiling information.
When the -qpdf1=pdfname option is used during the -qpdf1 phase, you must use the -qpdf2=pdfname option during the -qpdf2 phase for the compiler to recognize the correct PDF file. This rule also applies to the -qpdf[1|2]=exename option.

The compiler issues an information message with a number in the range of 0 - 100 during the -qpdf2 phase. If you have not changed your program between the -qpdf1 and -qpdf2 phases, the number is 100, which means that all the profiling information can be used to optimize the program. If the number is 0, it means that the profiling information is completely outdated, and the compiler cannot take advantage of any information. When the number is less than 100, you can choose to recompile your program with the -qpdf1 option and regenerate the profiling information.

If you recompile your program with any -qpdf1 option, the compiler removes the existing PDF file or files whose names and locations are the same as the file or files that will be created in the training step before generating a new application.

Other related options

You can use the following option with the -qpdf1 option:

-qprefetch: When you run the -qprefetch=assistthread option to generate data prefetching assist threads, the compiler uses the delinquent load information to perform analysis and generate them. The delinquent load information can be gathered from dynamic profiling using the -qpdf1=level=2 option. For more information, see -qprefetch.
-qshowpdf: Uses the showpdf utility to view the PDF data that were collected. See -qshowpdf for more information.

For recommended procedures of using PDF, see Using profile-directed feedback.

The following utility programs, found in /opt/ibm/xlC/13.1.2/bin/, are available for managing the files to which profiling information is written:

cleanpdf


>>-cleanpdf--+--------+--+-----+--+--------------+-------------><
             '-pdfdir-'  '- -u-'  '- -f--pdfname-'

Removes all PDF files or the specified PDF files, including PDF files with process ID suffixes. Removing profiling information reduces runtime overhead if you change the program and then go through the PDF process again.

pdfdir: Specifies the directory that contains the PDF files to be removed. If pdfdir is not specified, the directory is set by the PDFDIR environment variable; if PDFDIR is not set, the directory is the current directory.
-f pdfname: Specifies the name of the PDF file to be removed. If -f pdfname is not specified, ._pdf is removed.
-u: Removes the PDF file that is specified by pdfname. Files with the naming convention pdfname.<pid>, if applicable, are also removed. <pid> is the ID of the running process in the PDF training step.
If -f pdfname is not specified, removes ._pdf. Files with the naming convention ._pdf.<pid>, if applicable, are also removed.

Run cleanpdf only when you finish the PDF process for a particular application. Otherwise, if you want to resume by using PDF process with that application, you must compile all of the files again with -qpdf1.

mergepdf


             .-------------------------.                                  
             V                         |                                  
>>-mergepdf----+--------------+--input-+-- -o--output--+-----+--+-----+-><
               '- -r--scaling-'                        '- -n-'  '- -v-'

Merges two or more PDF files into a single PDF file.

-r scaling: Specifies the scaling ratio for the PDF file. This value must be greater than zero and can be either an integer or a floating-point value. If not specified, a ratio of 1.0 is assumed.
input: Specifies the name of a PDF input file, or a directory that contains PDF files.
-o output: Specifies the name of the PDF output file, or a directory to which the merged output is written.
-n: If specified, PDF files are not normalized. If not specified, mergepdf normalizes files based on an internally calculated ratio before applying any user-defined scaling factor.
-v: Specifies verbose mode, and causes internal and user-specified scaling ratios to be displayed to standard output.

showpdf

Displays part of the profiling information written to PDF and PDF map files. To use this command, you must first compile your program with the -qpdf1 option. See Viewing profiling information with showpdf for more information.

Predefined macros

None.

Examples

The following example uses the -qpdf1=level=0 option to reduce possible runtime instrumentation overhead:

#Compile all the files with -qpdf1=level=0
xlc -qpdf1=level=0 -O3 file1.c file2.c file3.c

#Run with one set of input data
./a.out < sample.data 

#Recompile all the files with -qpdf2
xlc -qpdf2 -O3 file1.c file2.c file3.c

#If the sample data is typical, the program 
#can now run faster than without the PDF process

The following example uses the -qpdf1=level=1 option:

#Compile all the files with -qpdf1
xlc -qpdf1 -O3 file1.c file2.c file3.c

#Run with one set of input data             
./a.out < sample.data 

#Recompile all the files with -qpdf2
xlc -qpdf2 -O3 file1.c file2.c file3.c

#If the sample data is typical, the program 
#can now run faster than without the PDF process

The following example uses the -qpdf1=level=2 option to gather cache-miss profiling information:

#Compile all the files with -qpdf1=level=2
xlc -qpdf1=level=2 -O3 file1.c file2.c file3.c

#Set PM_EVENT=L2MISS to gather L2 cache-miss profiling 
#information
export PDF_PM_EVENT=L2MISS

#Run with one set of input data
./a.out < sample.data 

#Recompile all the files with -qpdf2
xlc -qpdf2 -O3 file1.c file2.c file3.c

#If the sample data is typical, the program 
#can now run faster than without the PDF process

The following example demonstrates the use of the PDF_BIND_PROCESSOR environment variable:

#Compile all the files with -qpdf1=level=1
xlc -qpdf1=level=1 -O3 file1.c file2.c file3.c

#Set PDF_BIND_PROCESSOR environment variable so that 
#all processes for this executable are run on Processor 1
export PDF_BIND_PROCESSOR=1

#Run executable with sample input data
./a.out < sample.data 

#Recompile all the files with -qpdf2
xlc -qpdf2 -O3 file1.c file2.c file3.c

#If the sample data is typical, the program 
#can now run faster than without the PDF process

The following example demonstrates the use of the -qpdf[1|2]=exename option:

#Compile all the files with -qpdf1=exename
xlc -qpdf1=exename -O3 -o final file1.c file2.c file3.c

#Run executable with sample input data
./final < typical.data 

#List the content of the directory
 >ls -lrta

 -rw-r--r-- 1 user staff 50 Dec 05 13:18 file1.c
 -rw-r--r-- 1 user staff 50 Dec 05 13:18 file2.c
 -rw-r--r-- 1 user staff 50 Dec 05 13:18 file3.c
 -rwxr-xr-x 1 user staff 12243 Dec 05 17:00 final
 -rwxr-Sr-- 1 user staff 762 Dec 05 17:03 .final_pdf

#Recompile all the files with -qpdf2=exename
xlc -qpdf2=exename -O3 -o final file1.c file2.c file3.c

#The program is now optimized using PDF information

The following example demonstrates the use of the -qpdf[1|2]=pdfname option:

#Compile all the files with -qpdf1=pdfname. The static profiling 
#information is recorded in a file named final_map
xlc -qpdf1=pdfname=final -O3 file1.c file2.c file3.c

#Run executable with sample input data. The profiling 
#information is recorded in a file named final
./a.out < typical.data 

#List the content of the directory
 >ls -lrta

 -rw-r--r-- 1 user staff 50 Dec 05 13:18 file1.c
 -rw-r--r-- 1 user staff 50 Dec 05 13:18 file2.c
 -rw-r--r-- 1 user staff 50 Dec 05 13:18 file3.c
 -rwxr-xr-x 1 user staff 12243 Dec 05 18:30 a.out
 -rwxr-Sr-- 1 user staff 762 Dec 05 18:32 final

#Recompile all the files with -qpdf2=pdfname
xlc -qpdf2=pdfname=final -O3 file1.c file2.c file3.c

#The program is now optimized using PDF information

Related information

Voice your opinion on getting help information

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