Purpose
Creates a report to assist with finding optimization
opportunities.
Syntax
.-:----------------------------.
.-xml=-. V |
>>- -q----listfmt=----+------+----+-contentSelectionList-----+-+-><
+-filename=--filename------+
+-version=--version number-+
'-stylesheet=--filename----'
Defaults
This option is not on by default.
If no contentSelectionList options are selected
in their positive form, no report is produced. The default is -qlistfmt=xml=none.
Parameters
The following list describes
-qlistfmt parameters:
- xml
- Indicates that the report should be generated in XML format.
- contentSelectionList
- The following suboptions provide a filter to limit the type and
quantity of information in the report:
- data | nodata
- Produces data reorganization information.
- inlines | noinlines
- Produces inlining information.
- pdf | nopdf
- Produce profile-directed feedback information.
- transforms | notransforms
- Produces loop transformation information.
- all
- Produces all available report information.
- none
- Does not produce a report.
- filename
- Specifies the name of the report file. One file is produced during
the compile phase, and one file is produced during the IPA link phase.
If no filename is specified, a file with the suffix .xml is
generated in a way that is consistent with the rules of name generation
for the given platform. For example, if compiling foo.c the
generated XML files are foo.xml from the compile
step and a.xml from the link step.
Note: If you compile
and link in one step and use this suboption to specify a file name
for the report, the information from the IPA link step will overwrite
the information generated during the compile step.
The
same will be true if you compile multiple files using the
filename suboption.
The compiler creates an report for each file so the report of the
last file compiled will overwrite the previous reports. For example,
xlc -qlistfmt=xml=all:filename=abc.xml -O3 myfile1.c myfile2.c myfile3.c
will
result in only one report,
abc.xml based on the compilation
of the last file
myfile3.c
- stylesheet
- Specifies the name of an existing XML stylesheet for which an xml-stylesheet directive
is embedded in the resulting report. The default behavior
is to not include a stylesheet. The stylesheet shipped with XL C/C++ is xlstyle.xsl.
This stylesheet renders the XML to an easily read format when viewed
using a browser that supports XSLT.
To
view the XML report created with the stylesheet suboption,
you must place the actual stylesheet (xlstyle.xsl)
and the XML message catalogue (XMLMessages-lang.xml where lang refers
to the locale set on the compilation machine) in the path specified
by the stylesheet suboption. For example, if a.xml is
generated with stylesheet=xlstyle.xsl, xlstyle.xsl and XMLMessages-lang.xml must
be placed into the same directory as a.xml, before
you can properly view a.xml with a browser. The
message catalogs and stylesheet are installed in the /usr/vacpp/listings/ directory.
- version
- If you have written a tool that requires a certain version of
this report, you should specify the version. IBM® XL C/C++ for AIX®, V11.1 creates
reports at v1.0 so if you have written a tool to
consume these reports, you should specify version=v1.0.
Usage
The information produced
in the report by the
-qlistfmt option depends on
which optimization options are used to compiler the program.
- When used with an option that enables inlining such as -qinline,
the report shows which functions were inlined and why others were
not inlined.
- When used with an option that enables loop unrolling, the report
contains a summary of how program loops are optimized. The report
also includes diagnostic information to show why specific loops cannot
be vectorized. For -qlistfmt to generate information
about loop transformations, you must also specify at least one of
the following options:
- -qsimd=auto
- -qsmp
- -O5
- -qipa=level=2
- When used with an option that enables parallel transformations,
the report contains information about parallel transformations. For -qlistfmt to
generate information about parallel transformations or parallel performance
messages, you must also specify at least one of the following options:
- When used with the option that enables profiling, -qpdf,
the report contains information about call and block counts and cache
misses.
- When used with an option that produces data reorganizations such
as -qipa=level=2, the report contains information about those
reorganizations.
If no contentSelectionList options
are selected in their positive form, no report is produced.
Examples
If you want to compile
myprogram.c to
produce an XML 1.0 report that shows how loops are optimized, enter:
xlc -qhot -O3 -qlistfmt=xml=transforms myprogram.c
If you want to compile
myprogram.c to
have the XML report show which functions were inlined, enter:
xlc -qinline -qlistfmt=xml=inlines myprogram.c