-qpdf1, -qpdf2


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.


Read syntax diagramSkip visual syntax diagram        .-nopdf2-.
>>- -q--+-pdf1---+---------------------------------------------><


To use PDF, follow these steps:

  1. Compile some or all of the source files in a program with the -qpdf1 option. You need to specify at least the -O2 optimizing option and you also need to link with at least -O2 in effect. Pay special attention to the compiler options that you use to compile the files, because you will need to use the same options later.

    In a large application, concentrate on those areas of the code that can benefit most from optimization. You do not need to compile all of the application's code with the -qpdf1 option.

  2. 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.
    Use data that is representative of the data that will be used during a normal run of your finished program.
  3. Relink your program using the same compiler options as before, but change -qpdf1 to -qpdf2. Remember that -L, -l, and some others are linker options, and you can change them at this point. 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.

As an intermediate step, you can use -qpdf2 to link the object files created by the -qpdf1 pass without recompiling the source on the -qpdf2 pass. This can save considerable time and help fine tune large applications for optimization. You can create and test different flavors of PDF optimized binaries by using different options on the -qpdf2 pass.

For best performance, use the -O3, -O4, or -O5 option with all compilations when you use PDF.

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

To avoid wasting compilation and execution time, make sure that the PDFDIR environment variable is set to an absolute path. Otherwise, you might run the application from the wrong directory, and it will not be able to locate the profile data files. When 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.


The following utility programs, found in /usr/xlopt/bin, are available for managing the PDFDIR directory:

Read syntax diagramSkip visual syntax diagram>>-cleanpdf--+----------+--------------------------------------><

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 profiling information reduces runtime overhead if you change the program and then go through the PDF process again.

Run cleanpdf only when you are finished with the PDF process for a particular application. Otherwise, if you want to resume using PDF with that application, you will need to recompile all of the files again with -qpdf1.


Read syntax diagramSkip visual syntax diagram             .-------------------------.
             V                         |
>>-mergepdf----+--------------+--input-+-- -o--output--+-----+--+-----+-><
               '- -r--scaling-'                        '- -n-'  '- -v-'

Merges two or more PDF records into a single PDF output record.

-r scaling
Specifies the scaling ratio for the PDF record file. This value must be greater than zero and can be either an integer or floating point value. If not specified, a ratio of 1.0 is assumed.
Specifies the name of a PDF input record file, or a directory that contains PDF record files.
-o output
Specifies the name of the PDF output record file, or a directory to which the merged output will be written.
If specified, PDF record files are not normalized. If not specified, mergepdf normalizes records based on an internally-calculated ratio before applying any user-defined scaling factor.
Specifies verbose mode, and causes internal and user-specified scaling ratios to be displayed to the screen.
Read syntax diagramSkip visual syntax diagram>>-resetpdf--+----------+--------------------------------------><

Same as cleanpdf, described above.


Read syntax diagramSkip visual syntax diagram>>-showpdf-----------------------------------------------------><

Displays the call and block counts for all procedures executed in a program run. To use this command, you must first compile your application specifying both -qpdf1 and -qshowpdf compiler options on the command line.


Here is a simple example:

/* Set the PDFDIR variable.                     */
export PDFDIR=$HOME/project_dir

/* Compile all 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 files with -qpdf2.             */
xlc++ -qpdf2 -O3 file1.C file2.C file3.C

/* The program should now run faster than 
   without PDF if the sample data is typical.   */

Here is a more elaborate example.

/* Set the PDFDIR variable.                     */
export PDFDIR=$HOME/project_dir

/* Compile most of the files with -qpdf1.       */
xlc++ -qpdf1 -O3 -c file1.C file2.C file3.C

/* This file is not so important to optimize.
xlc++ -c file4.C

/* Non-PDF object files such as file4.o can be linked in.  */
xlc++ -qpdf1 -O3 file1.o file2.o file3.o file4.o

/* Run several times with different input data.            */
a.out <polar_orbit.data
a.out <elliptical_orbit.data
a.out <geosynchronous_orbit.data

/* No need to recompile the source of non-PDF object files (file4.C). */
xlc++ -qpdf2 -O3 file1.C file2.C file3.C

/* Link all the object files into the final application.   */
xlc++ -qpdf2 -O3 file1.o file2.o file3.o file4.o

Here is an example of using -qpdf1 and -qpdf2 objects.

/* Set the PDFDIR variable.                     */
export PDFDIR=$HOME/project_dir 

/* Compile source with -qpdf1.                  */
xlc++ -c -qpdf1 -O3 file1.C file2.C

/* Link in object files.                        */
xlc++ -qpdf1 -O3 file1.o file2.o 

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

/* Link in the mix of pdf1 and pdf2 objects.    */
xlc++ -qpdf2 -O3 file1.o file2.o

Related information