pdf1, pdf2

Option Type	Default Value	#pragma options	C	C++
-qoption	nopdf1 nopdf2	-	x	x

Syntax

    -qpdf1 | -qpdf2 | -qnopdf1 | -qnopdf2

Purpose
Tunes optimizations through Profile-Directed Feedback (PDF), where results from one or more sample program executions are used to improve optimization near conditional branches and in frequently executed code sections.

Notes
To use PDF:

Compile some or all of the source files in a program with the -qpdf1 option. main must be compiled. The -lpdf option is required during the link step, the -O3 option is recommended for optimization. Pay special attention to the compiler options used to compile the files, because you will need to use the same options later.
Run the program all the way through, using a typical data set. The program records profiling information when it finishes. You can run the program multiple times with different data sets, and the profiling information is accumulated to provide an accurate count of how often branches are taken and blocks of code are executed.
Important: Use data that is representative of the data that will be used during a normal run of your finished program.
Recompile your program, using the same compiler options as before but changing -qpdf1 to -qpdf2. Remember that -L, -l, and some others are linker options, and you can change them at this point. In particular, leave the -lpdf option out. In this second compilation, the accumulated profiling information is used to fine-tune the optimizations. The resulting program contains no profiling overhead and runs at full speed.

For optimum performance, use the -O3 option with all compilations when you use PDF (as in the example above). With -O2 optimization, one of the most important PDF optimizations (moving code before branches to fill delay slots) is not done.

The profile is placed in the current working directory, or the directory named by the PDFDIR environment variable if that variable is set.

To avoid wasting compilation and execution time, make sure the PDFDIR environment variable is set to an absolute path; otherwise, you might run the application from the wrong directory so that it cannot locate the profile data files. If that happens, the program may not be optimized correctly or may be stopped by a segmentation fault. A segmentation fault might also happen if you change the value of the PDFDIR variable and execute the application before finishing the PDF process.

Because this option requires compiling the entire application twice, it is intended to be used after other debugging and tuning is finished, as one of the last steps before putting the application into production.

Restrictions

Do not mix PDF files created by the current version of IBM C and C++ Compilers with PDF files created by previous versions.
PDF optimizations also require at least level 2 of -O.
The main program must be compiled with PDF for profiling to work properly. If you want to use this option to optimize a library or other code that does not usually incorporate a main program, supply a main program for the first PDF compilation, then omit the main program for the second PDF compilation.
Do not compile or run two different applications that use the same PDFDIR directory at the same time.
You must use the same set of compiler options at all compilation steps for a particular program; otherwise, PDF cannot optimize your program correctly, and may even slow it down. All compiler settings must be the same, including any supplied by configuration files.
If you do compile a program with -qpdf1, remember that it will generate profiling information when it runs, which involves some performance overhead. This overhead goes away when you recompile with -qpdf2 or with no PDF at all.

The following commands are available for managing the PDFDIR directory:

resetpdf [pathname]

Zeros out all profiling information (but does not remove the data files) from the pathname directory; or if pathname is not specified, from the PDFDIR directory; or if PDFDIR is not set, from the current directory.

When you make changes to the application and recompile some files, the profiling information for those files is automatically reset, because the changes may alter the program flow. Run resetpdf to reset the profiling information for the entire application, after making significant changes that may affect execution counts for parts of the program that were not recompiled.

cleanpdf [pathname]

Removes all profiling information from the pathname directory; or if pathname is not specified, from the PDFDIR directory; or if PDFDIR is not set, from the current directory.

Removing the profiling information reduces the runtime overhead if you change the program and then go through the PDF process again.

Run this program after compiling with -qpdf2, or after finishing with the PDF process for a particular application. If you continue using PDF with an application after running cleanpdf, you must recompile all the files with -qpdf1.

Example 1
Here are the steps for a simple example:

first, set the PDFDIR environment variable:

export PDFDIR=/home/user
Compile all files with -qpdf1 and -O3, and link with -lpdf.

xlC -qpdf1 -lpdf -O3 file1.c file2.c file3.c -L/usr/ibmcxx/lib
Run with one set of input data:

a.out < sample.data
Recompile all files with -qpdf2 and -O3:

xlC -qpdf2 -O3 file1.c file2.c file3.c

The program should now run faster than without PDF, if the sample used data was typical of actual program data.

Note: When using -qpdf1, specify the search location for its libraries with the -L compiler option, as shown in step 2 above.

Example 2
Here are the steps for a more elaborate example.

Set the PDFDIR environment variable:

export PDFDIR=/home/user
Compile most of the files with -qpdf1.

xlC -qpdf1 -O3 -c file1.c file2.c file3.c -L/usr/ibmcxx/lib
This file is not so important to optimize:

xlC -c file4.c
Non-PDF object files like file4.o can be linked in:

xlC -qpdf1 -lpdf file1.o file2.o file3.o file4.o -L/usr/ibmcxx/lib
Run several times with different input data:

a.out < polar_orbit.data
a.out < elliptical_orbit.data
a.out < geosynchronous_orbit.data
You do not need to recompile the source of non-PDF object files:

xlC -qpdf2 -O3 file1.c file2.c file3.c
Link all the object files into the final application:

xlC file1.o file2.o file3.o file4.o

List of Compiler Options and Their Defaults
Options that Define the Compiler Object Code Produced