docs/Remarks.rst

   1 =======
   2 Remarks
   3 =======
   4
   5 .. contents::
   6    :local:
   7
   8 Introduction to the LLVM remark diagnostics
   9 ===========================================
  10
  11 LLVM is able to emit diagnostics from passes describing whether an optimization
  12 has been performed or missed for a particular reason, which should give more
  13 insight to users about what the compiler did during the compilation pipeline.
  14
  15 There are three main remark types:
  16
  17 ``Passed``
  18
  19     Remarks that describe a successful optimization performed by the compiler.
  20
  21     :Example:
  22
  23     ::
  24
  25         foo inlined into bar with (cost=always): always inline attribute
  26
  27 ``Missed``
  28
  29     Remarks that describe an attempt to an optimization by the compiler that
  30     could not be performed.
  31
  32     :Example:
  33
  34     ::
  35
  36         foo not inlined into bar because it should never be inlined
  37         (cost=never): noinline function attribute
  38
  39 ``Analysis``
  40
  41     Remarks that describe the result of an analysis, that can bring more
  42     information to the user regarding the generated code.
  43
  44     :Example:
  45
  46     ::
  47
  48         16 stack bytes in function
  49
  50     ::
  51
  52         10 instructions in function
  53
  54 Enabling optimization remarks
  55 =============================
  56
  57 There are two modes that are supported for enabling optimization remarks in
  58 LLVM: through remark diagnostics, or through serialized remarks.
  59
  60 Remark diagnostics
  61 ------------------
  62
  63 Optimization remarks can be emitted as diagnostics. These diagnostics will be
  64 propagated to front-ends if desired, or emitted by tools like :doc:`llc
  65 <CommandGuide/llc>` or :doc:`opt <CommandGuide/opt>`.
  66
  67 .. option:: -pass-remarks=<regex>
  68
  69   Enables optimization remarks from passes whose name match the given (POSIX)
  70   regular expression.
  71
  72 .. option:: -pass-remarks-missed=<regex>
  73
  74   Enables missed optimization remarks from passes whose name match the given
  75   (POSIX) regular expression.
  76
  77 .. option:: -pass-remarks-analysis=<regex>
  78
  79   Enables optimization analysis remarks from passes whose name match the given
  80   (POSIX) regular expression.
  81
  82 Serialized remarks
  83 ------------------
  84
  85 While diagnostics are useful during development, it is often more useful to
  86 refer to optimization remarks post-compilation, typically during performance
  87 analysis.
  88
  89 For that, LLVM can serialize the remarks produced for each compilation unit to
  90 a file that can be consumed later.
  91
  92 By default, the format of the serialized remarks is :ref:`YAML
  93 <yamlremarks>`, and it can be accompanied by a :ref:`section <remarkssection>`
  94 in the object files to easily retrieve it.
  95
  96 :doc:`llc <CommandGuide/llc>` and :doc:`opt <CommandGuide/opt>` support the
  97 following options:
  98
  99
 100 ``Basic options``
 101
 102     .. option:: -pass-remarks-output=<filename>
 103
 104       Enables the serialization of remarks to a file specified in <filename>.
 105
 106       By default, the output is serialized to :ref:`YAML <yamlremarks>`.
 107
 108     .. option:: -pass-remarks-format=<format>
 109
 110       Specifies the output format of the serialized remarks.
 111
 112       Supported formats:
 113
 114       * :ref:`yaml <yamlremarks>` (default)
 115       * :ref:`yaml-strtab <yamlstrtabremarks>`
 116
 117 ``Content configuration``
 118
 119     .. option:: -pass-remarks-filter=<regex>
 120
 121       Only passes whose name match the given (POSIX) regular expression will be
 122       serialized to the final output.
 123
 124     .. option:: -pass-remarks-with-hotness
 125
 126       With PGO, include profile count in optimization remarks.
 127
 128     .. option:: -pass-remarks-hotness-threshold
 129
 130       The minimum profile count required for an optimization remark to be
 131       emitted.
 132
 133 Other tools that support remarks:
 134
 135 :program:`llvm-lto`
 136
 137     .. option:: -lto-pass-remarks-output=<filename>
 138     .. option:: -lto-pass-remarks-filter=<regex>
 139     .. option:: -lto-pass-remarks-format=<format>
 140     .. option:: -lto-pass-remarks-with-hotness
 141     .. option:: -lto-pass-remarks-hotness-threshold
 142
 143 :program:`gold-plugin` and :program:`lld`
 144
 145     .. option:: -opt-remarks-filename=<filename>
 146     .. option:: -opt-remarks-filter=<regex>
 147     .. option:: -opt-remarks-format=<format>
 148     .. option:: -opt-remarks-with-hotness
 149
 150 .. _yamlremarks:
 151
 152 YAML remarks
 153 ============
 154
 155 A typical remark serialized to YAML looks like this:
 156
 157 .. code-block:: yaml
 158
 159     --- !<TYPE>
 160     Pass: <pass>
 161     Name: <name>
 162     DebugLoc: { File: <file>, Line: <line>, Column: <column> }
 163     Function: <function>
 164     Hotness: <hotness>
 165     Args:
 166       - <key>: <value>
 167         DebugLoc: { File: <arg-file>, Line: <arg-line>, Column: <arg-column> }
 168
 169 The following entries are mandatory:
 170
 171 * ``<TYPE>``: can be ``Passed``, ``Missed``, ``Analysis``,
 172   ``AnalysisFPCommute``, ``AnalysisAliasing``, ``Failure``.
 173 * ``<pass>``: the name of the pass that emitted this remark.
 174 * ``<name>``: the name of the remark coming from ``<pass>``.
 175 * ``<function>``: the mangled name of the function.
 176
 177 If a ``DebugLoc`` entry is specified, the following fields are required:
 178
 179 * ``<file>``
 180 * ``<line>``
 181 * ``<column>``
 182
 183 If an ``arg`` entry is specified, the following fields are required:
 184
 185 * ``<key>``
 186 * ``<value>``
 187
 188 If a ``DebugLoc`` entry is specified within an ``arg`` entry, the following
 189 fields are required:
 190
 191 * ``<arg-file>``
 192 * ``<arg-line>``
 193 * ``<arg-column>``
 194
 195 .. _yamlstrtabremarks:
 196
 197 YAML with a string table
 198 ------------------------
 199
 200 The YAML serialization supports the usage of a string table by using the
 201 ``yaml-strtab`` format.
 202
 203 This format replaces strings in the YAML output with integers representing the
 204 index in the string table that can be provided separately through metadata.
 205
 206 The following entries can take advantage of the string table while respecting
 207 YAML rules:
 208
 209 * ``<pass>``
 210 * ``<name>``
 211 * ``<function>``
 212 * ``<file>``
 213 * ``<value>``
 214 * ``<arg-file>``
 215
 216 Currently, none of the tools in :ref:`the opt-viewer directory <optviewer>`
 217 support this format.
 218
 219 .. _optviewer:
 220
 221 YAML metadata
 222 -------------
 223
 224 The metadata used together with the YAML format is:
 225
 226 * a magic number: "REMARKS\\0"
 227 * the version number: a little-endian uint64_t
 228 * the total size of the string table (the size itself excluded):
 229   little-endian uint64_t
 230 * a list of null-terminated strings
 231
 232 Optional:
 233
 234 * the absolute file path to the serialized remark diagnostics: a
 235   null-terminated string.
 236
 237 When the metadata is serialized separately from the remarks, the file path
 238 should be present and point to the file where the remarks are serialized to.
 239
 240 In case the metadata only acts as a header to the remarks, the file path can be
 241 omitted.
 242
 243 opt-viewer
 244 ==========
 245
 246 The ``opt-viewer`` directory contains a collection of tools that visualize and
 247 summarize serialized remarks.
 248
 249 The tools only support the ``yaml`` format.
 250
 251 .. _optviewerpy:
 252
 253 opt-viewer.py
 254 -------------
 255
 256 Output a HTML page which gives visual feedback on compiler interactions with
 257 your program.
 258
 259     :Examples:
 260
 261     ::
 262
 263         $ opt-viewer.py my_yaml_file.opt.yaml
 264
 265     ::
 266
 267         $ opt-viewer.py my_build_dir/
 268
 269
 270 opt-stats.py
 271 ------------
 272
 273 Output statistics about the optimization remarks in the input set.
 274
 275     :Example:
 276
 277     ::
 278
 279         $ opt-stats.py my_yaml_file.opt.yaml
 280
 281         Total number of remarks           3
 282
 283
 284         Top 10 remarks by pass:
 285           inline                         33%
 286           asm-printer                    33%
 287           prologepilog                   33%
 288
 289         Top 10 remarks:
 290           asm-printer/InstructionCount   33%
 291           inline/NoDefinition            33%
 292           prologepilog/StackSize         33%
 293
 294 opt-diff.py
 295 -----------
 296
 297 Produce a new YAML file which contains all of the changes in optimizations
 298 between two YAML files.
 299
 300 Typically, this tool should be used to do diffs between:
 301
 302 * new compiler + fixed source vs old compiler + fixed source
 303 * fixed compiler + new source vs fixed compiler + old source
 304
 305 This diff file can be displayed using :ref:`opt-viewer.py <optviewerpy>`.
 306
 307     :Example:
 308
 309     ::
 310
 311         $ opt-diff.py my_opt_yaml1.opt.yaml my_opt_yaml2.opt.yaml -o my_opt_diff.opt.yaml
 312         $ opt-viewer.py my_opt_diff.opt.yaml
 313
 314 .. _remarkssection:
 315
 316 Emitting remark diagnostics in the object file
 317 ==============================================
 318
 319 A section containing metadata on remark diagnostics will be emitted when
 320 -remarks-section is passed. The section contains the metadata associated to the
 321 format used to serialize the remarks.
 322
 323 The section is named:
 324
 325 * ``__LLVM,__remarks`` (MachO)
 326 * ``.remarks`` (ELF)
 327
 328 C API
 329 =====
 330
 331 LLVM provides a library that can be used to parse remarks through a shared
 332 library named ``libRemarks``.
 333
 334 The typical usage through the C API is like the following:
 335
 336 .. code-block:: c
 337
 338     LLVMRemarkParserRef Parser = LLVMRemarkParserCreateYAML(Buf, Size);
 339     LLVMRemarkEntryRef Remark = NULL;
 340     while ((Remark = LLVMRemarkParserGetNext(Parser))) {
 341        // use Remark
 342        LLVMRemarkEntryDispose(Remark); // Release memory.
 343     }
 344     bool HasError = LLVMRemarkParserHasError(Parser);
 345     LLVMRemarkParserDispose(Parser);
 346
 347 .. FIXME: add documentation for llvm-opt-report.
 348 .. FIXME: add documentation for Passes supporting optimization remarks
 349 .. FIXME: add documentation for IR Passes
 350 .. FIXME: add documentation for CodeGen Passes