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 opt-viewer
 222 ==========
 223
 224 The ``opt-viewer`` directory contains a collection of tools that visualize and
 225 summarize serialized remarks.
 226
 227 The tools only support the ``yaml`` format.
 228
 229 .. _optviewerpy:
 230
 231 opt-viewer.py
 232 -------------
 233
 234 Output a HTML page which gives visual feedback on compiler interactions with
 235 your program.
 236
 237     :Examples:
 238
 239     ::
 240
 241         $ opt-viewer.py my_yaml_file.opt.yaml
 242
 243     ::
 244
 245         $ opt-viewer.py my_build_dir/
 246
 247
 248 opt-stats.py
 249 ------------
 250
 251 Output statistics about the optimization remarks in the input set.
 252
 253     :Example:
 254
 255     ::
 256
 257         $ opt-stats.py my_yaml_file.opt.yaml
 258
 259         Total number of remarks           3
 260
 261
 262         Top 10 remarks by pass:
 263           inline                         33%
 264           asm-printer                    33%
 265           prologepilog                   33%
 266
 267         Top 10 remarks:
 268           asm-printer/InstructionCount   33%
 269           inline/NoDefinition            33%
 270           prologepilog/StackSize         33%
 271
 272 opt-diff.py
 273 -----------
 274
 275 Produce a new YAML file which contains all of the changes in optimizations
 276 between two YAML files.
 277
 278 Typically, this tool should be used to do diffs between:
 279
 280 * new compiler + fixed source vs old compiler + fixed source
 281 * fixed compiler + new source vs fixed compiler + old source
 282
 283 This diff file can be displayed using :ref:`opt-viewer.py <optviewerpy>`.
 284
 285     :Example:
 286
 287     ::
 288
 289         $ opt-diff.py my_opt_yaml1.opt.yaml my_opt_yaml2.opt.yaml -o my_opt_diff.opt.yaml
 290         $ opt-viewer.py my_opt_diff.opt.yaml
 291
 292 .. _remarkssection:
 293
 294 Emitting remark diagnostics in the object file
 295 ==============================================
 296
 297 A section containing metadata on remark diagnostics will be emitted when
 298 -remarks-section is passed. The section contains:
 299
 300 * a magic number: "REMARKS\\0"
 301 * the version number: a little-endian uint64_t
 302 * the total size of the string table (the size itself excluded):
 303   little-endian uint64_t
 304 * a list of null-terminated strings
 305 * the absolute file path to the serialized remark diagnostics: a
 306   null-terminated string.
 307
 308 The section is named:
 309
 310 * ``__LLVM,__remarks`` (MachO)
 311 * ``.remarks`` (ELF)
 312
 313 C API
 314 =====
 315
 316 LLVM provides a library that can be used to parse remarks through a shared
 317 library named ``libRemarks``.
 318
 319 The typical usage through the C API is like the following:
 320
 321 .. code-block:: c
 322
 323     LLVMRemarkParserRef Parser = LLVMRemarkParserCreateYAML(Buf, Size);
 324     LLVMRemarkEntryRef Remark = NULL;
 325     while ((Remark = LLVMRemarkParserGetNext(Parser))) {
 326        // use Remark
 327        LLVMRemarkEntryDispose(Remark); // Release memory.
 328     }
 329     bool HasError = LLVMRemarkParserHasError(Parser);
 330     LLVMRemarkParserDispose(Parser);
 331
 332 .. FIXME: add documentation for llvm-opt-report.
 333 .. FIXME: add documentation for Passes supporting optimization remarks
 334 .. FIXME: add documentation for IR Passes
 335 .. FIXME: add documentation for CodeGen Passes