-qlistfmt

@PROCESS

None.

Purpose

Creates an XML or HTML report to assist with finding optimization opportunities.

Syntax


                  .-xml--.                                            
>>- -q--listfmt=--+-html-+--+-------------------------------------+-><
                            |    .-:----------------------------. |   
                            |    V                              | |   
                            '-=----+-contentSelectionList-----+-+-'   
                                   +-filename=--filename------+       
                                   +-version=--version number-+       
                                   '-stylesheet=--filename----'

Defaults

This option is off by default. If no contentSelectionList options are selected in their positive form, all available report information is produced. For example, specifying -qlistfmt=xml is equivalent to -qlistfmt=xml=all.

Parameters

The following list describes -qlistfmt parameters:

xml | html

Indicates that the report should be generated in XML or HTML format. If an XML report has been generated before, you can convert the report to the HTML format using the genhtml command. For more information about this command, see genhtml command.

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 or .html is generated in a way that is consistent with the rules of name generation for the given platform. For example, if compiling foo.f 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,

xlf -qlistfmt=xml=all:filename=abc.xml -O3 myfile1.f myfile2.f myfile3.f

will result in only one report, abc.xml based on the compilation of the last file myfile3.f

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 Fortran 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-locale.xml where locale 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-locale.xml must be in 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 /opt/IBM/xlf/15.1.0/listings/ directory.

version

Specifies the major version of the content that is emitted. If you have written a tool that requires a certain version of this report, you should specify the version. IBM® XL Fortran for AIX®, V15.1 creates reports at XML v1.1, so if you have written a tool to consume these reports, specify version=v1.

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:
- -qsmp
- -O5
- -qipa=level=2
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, all available report information is produced.

Examples

If you want to compile myprogram.f to produce an XML report that shows how loops are optimized, enter:

xlf -qhot -O3 -qlistfmt=xml=transforms myprogram.f

If you want to compile myprogram.f to produce an XML report that shows which functions are inlined, enter:

xlf -qinline -qlistfmt=xml=inlines myprogram.f

genhtml command

To view the HTML version of an XML report that has already been generated, you can use the genhtml tool.

Use the following command to view the existing XML report in HTML format. This command generates the HTML content to standard output.

genhtml xml_file

Use the following command to generate the HTML content into a defined HTML file. You can use a web browser to view the generated HTML file.

genhtml xml_file > target_html_file

Note: The suffix of the HTML file name must be compliant with the static HTML page standard, for example, .html or .htm. Otherwise, the web browser might not be able to open the file.