-qpdf1, -qpdf2
Description
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.
Syntax

.-nopdf2-.
+-nopdf1-+
>>- -q--+-pdf1---+---------------------------------------------><
'-pdf2---'
Notes
To use PDF, follow these steps:
- 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.
- 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.
- 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.
Restrictions
- PDF optimizations require at least the -O2 optimization
level.
- You must compile the main program with PDF for profiling information to
be collected at run time.
- Do not compile or run two different applications that use the same PDFDIR
directory at the same time, unless you have used the -qipa=pdfname suboption to distinguish the sets of profiling information.
- 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.
- Avoid mixing PDF files created by the current version level of XL C/C++ with
PDF files created by other version levels of the compiler.
- If -qipa is not invoked either directly or through
other options, -qpdf1 and -qpdf2 will
invoke the -qipa=level=0 option.
- If you 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 utility programs, found in /opt/ibmcmp/vacpp/8.0/bin/, are available for managing the PDFDIR directory:
cleanpdf |
 >>-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 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.
|
mergepdf |
 .-------------------------.
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.
- input
- 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.
- -n
- 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.
- -v
- Specifies verbose mode, and causes internal and user-specified scaling
ratios to be displayed to the screen.
|
resetpdf |
 >>-resetpdf--+----------+--------------------------------------><
'-pathname-'
Same as cleanpdf, described above.
|
showpdf |
 >>-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. |
Examples
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