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
 116 ``Content configuration``
 117
 118     .. option:: -pass-remarks-filter=<regex>
 119
 120       Only passes whose name match the given (POSIX) regular expression will be
 121       serialized to the final output.
 122
 123     .. option:: -pass-remarks-with-hotness
 124
 125       With PGO, include profile count in optimization remarks.
 126
 127     .. option:: -pass-remarks-hotness-threshold
 128
 129       The minimum profile count required for an optimization remark to be
 130       emitted.
 131
 132 Other tools that support remarks:
 133
 134 :program:`llvm-lto`
 135
 136     .. option:: -lto-pass-remarks-output=<filename>
 137     .. option:: -lto-pass-remarks-filter=<regex>
 138     .. option:: -lto-pass-remarks-format=<format>
 139     .. option:: -lto-pass-remarks-with-hotness
 140     .. option:: -lto-pass-remarks-hotness-threshold
 141
 142 :program:`gold-plugin` and :program:`lld`
 143
 144     .. option:: -opt-remarks-filename=<filename>
 145     .. option:: -opt-remarks-filter=<regex>
 146     .. option:: -opt-remarks-format=<format>
 147     .. option:: -opt-remarks-with-hotness
 148
 149 .. _yamlremarks:
 150
 151 YAML remarks
 152 ============
 153
 154 A typical remark serialized to YAML looks like this:
 155
 156 .. code-block:: yaml
 157
 158     --- !<TYPE>
 159     Pass: <pass>
 160     Name: <name>
 161     DebugLoc: { File: <file>, Line: <line>, Column: <column> }
 162     Function: <function>
 163     Hotness: <hotness>
 164     Args:
 165       - <key>: <value>
 166         DebugLoc: { File: <arg-file>, Line: <arg-line>, Column: <arg-column> }
 167
 168 The following entries are mandatory:
 169
 170 * ``<TYPE>``: can be ``Passed``, ``Missed``, ``Analysis``,
 171   ``AnalysisFPCommute``, ``AnalysisAliasing``, ``Failure``.
 172 * ``<pass>``: the name of the pass that emitted this remark.
 173 * ``<name>``: the name of the remark coming from ``<pass>``.
 174 * ``<function>``: the mangled name of the function.
 175
 176 If a ``DebugLoc`` entry is specified, the following fields are required:
 177
 178 * ``<file>``
 179 * ``<line>``
 180 * ``<column>``
 181
 182 If an ``arg`` entry is specified, the following fields are required:
 183
 184 * ``<key>``
 185 * ``<value>``
 186
 187 If a ``DebugLoc`` entry is specified within an ``arg`` entry, the following
 188 fields are required:
 189
 190 * ``<arg-file>``
 191 * ``<arg-line>``
 192 * ``<arg-column>``
 193
 194 opt-viewer
 195 ==========
 196
 197 The ``opt-viewer`` directory contains a collection of tools that visualize and
 198 summarize serialized remarks.
 199
 200 .. _optviewerpy:
 201
 202 opt-viewer.py
 203 -------------
 204
 205 Output a HTML page which gives visual feedback on compiler interactions with
 206 your program.
 207
 208     :Examples:
 209
 210     ::
 211
 212         $ opt-viewer.py my_yaml_file.opt.yaml
 213
 214     ::
 215
 216         $ opt-viewer.py my_build_dir/
 217
 218
 219 opt-stats.py
 220 ------------
 221
 222 Output statistics about the optimization remarks in the input set.
 223
 224     :Example:
 225
 226     ::
 227
 228         $ opt-stats.py my_yaml_file.opt.yaml
 229
 230         Total number of remarks           3
 231
 232
 233         Top 10 remarks by pass:
 234           inline                         33%
 235           asm-printer                    33%
 236           prologepilog                   33%
 237
 238         Top 10 remarks:
 239           asm-printer/InstructionCount   33%
 240           inline/NoDefinition            33%
 241           prologepilog/StackSize         33%
 242
 243 opt-diff.py
 244 -----------
 245
 246 Produce a new YAML file which contains all of the changes in optimizations
 247 between two YAML files.
 248
 249 Typically, this tool should be used to do diffs between:
 250
 251 * new compiler + fixed source vs old compiler + fixed source
 252 * fixed compiler + new source vs fixed compiler + old source
 253
 254 This diff file can be displayed using :ref:`opt-viewer.py <optviewerpy>`.
 255
 256     :Example:
 257
 258     ::
 259
 260         $ opt-diff.py my_opt_yaml1.opt.yaml my_opt_yaml2.opt.yaml -o my_opt_diff.opt.yaml
 261         $ opt-viewer.py my_opt_diff.opt.yaml
 262
 263 .. _remarkssection:
 264
 265 Emitting remark diagnostics in the object file
 266 ==============================================
 267
 268 A section containing metadata on remark diagnostics will be emitted when
 269 -remarks-section is passed. The section contains:
 270
 271 * a magic number: "REMARKS\\0"
 272 * the version number: a little-endian uint64_t
 273 * the total size of the string table (the size itself excluded):
 274   little-endian uint64_t
 275 * a list of null-terminated strings
 276 * the absolute file path to the serialized remark diagnostics: a
 277   null-terminated string.
 278
 279 The section is named:
 280
 281 * ``__LLVM,__remarks`` (MachO)
 282 * ``.remarks`` (ELF)
 283
 284 C API
 285 =====
 286
 287 LLVM provides a library that can be used to parse remarks through a shared
 288 library named ``libRemarks``.
 289
 290 The typical usage through the C API is like the following:
 291
 292 .. code-block:: c
 293
 294     LLVMRemarkParserRef Parser = LLVMRemarkParserCreateYAML(Buf, Size);
 295     LLVMRemarkEntryRef Remark = NULL;
 296     while ((Remark = LLVMRemarkParserGetNext(Parser))) {
 297        // use Remark
 298        LLVMRemarkEntryDispose(Remark); // Release memory.
 299     }
 300     bool HasError = LLVMRemarkParserHasError(Parser);
 301     LLVMRemarkParserDispose(Parser);
 302
 303 .. FIXME: add documentation for llvm-opt-report.
 304 .. FIXME: add documentation for Passes supporting optimization remarks
 305 .. FIXME: add documentation for IR Passes
 306 .. FIXME: add documentation for CodeGen Passes