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       * :ref:`bitstream <bitstreamremarks>`
 117
 118 ``Content configuration``
 119
 120     .. option:: -pass-remarks-filter=<regex>
 121
 122       Only passes whose name match the given (POSIX) regular expression will be
 123       serialized to the final output.
 124
 125     .. option:: -pass-remarks-with-hotness
 126
 127       With PGO, include profile count in optimization remarks.
 128
 129     .. option:: -pass-remarks-hotness-threshold
 130
 131       The minimum profile count required for an optimization remark to be
 132       emitted.
 133
 134 Other tools that support remarks:
 135
 136 :program:`llvm-lto`
 137
 138     .. option:: -lto-pass-remarks-output=<filename>
 139     .. option:: -lto-pass-remarks-filter=<regex>
 140     .. option:: -lto-pass-remarks-format=<format>
 141     .. option:: -lto-pass-remarks-with-hotness
 142     .. option:: -lto-pass-remarks-hotness-threshold
 143
 144 :program:`gold-plugin` and :program:`lld`
 145
 146     .. option:: -opt-remarks-filename=<filename>
 147     .. option:: -opt-remarks-filter=<regex>
 148     .. option:: -opt-remarks-format=<format>
 149     .. option:: -opt-remarks-with-hotness
 150
 151 Serialization modes
 152 ===================
 153
 154 There are two modes available for serializing remarks:
 155
 156 ``Separate``
 157
 158     In this mode, the remarks and the metadata are serialized separately. The
 159     client is responsible for parsing the metadata first, then use the metadata
 160     to correctly parse the remarks.
 161
 162 ``Standalone``
 163
 164     In this mode, the remarks and the metadata are serialized to the same
 165     stream. The metadata will always come before the remarks.
 166
 167     The compiler does not support emitting standalone remarks. This mode is
 168     more suited for post-processing tools like linkers, that can merge the
 169     remarks for one whole project.
 170
 171 .. _yamlremarks:
 172
 173 YAML remarks
 174 ============
 175
 176 A typical remark serialized to YAML looks like this:
 177
 178 .. code-block:: yaml
 179
 180     --- !<TYPE>
 181     Pass: <pass>
 182     Name: <name>
 183     DebugLoc: { File: <file>, Line: <line>, Column: <column> }
 184     Function: <function>
 185     Hotness: <hotness>
 186     Args:
 187       - <key>: <value>
 188         DebugLoc: { File: <arg-file>, Line: <arg-line>, Column: <arg-column> }
 189
 190 The following entries are mandatory:
 191
 192 * ``<TYPE>``: can be ``Passed``, ``Missed``, ``Analysis``,
 193   ``AnalysisFPCommute``, ``AnalysisAliasing``, ``Failure``.
 194 * ``<pass>``: the name of the pass that emitted this remark.
 195 * ``<name>``: the name of the remark coming from ``<pass>``.
 196 * ``<function>``: the mangled name of the function.
 197
 198 If a ``DebugLoc`` entry is specified, the following fields are required:
 199
 200 * ``<file>``
 201 * ``<line>``
 202 * ``<column>``
 203
 204 If an ``arg`` entry is specified, the following fields are required:
 205
 206 * ``<key>``
 207 * ``<value>``
 208
 209 If a ``DebugLoc`` entry is specified within an ``arg`` entry, the following
 210 fields are required:
 211
 212 * ``<arg-file>``
 213 * ``<arg-line>``
 214 * ``<arg-column>``
 215
 216 .. _yamlstrtabremarks:
 217
 218 YAML with a string table
 219 ------------------------
 220
 221 The YAML serialization supports the usage of a string table by using the
 222 ``yaml-strtab`` format.
 223
 224 This format replaces strings in the YAML output with integers representing the
 225 index in the string table that can be provided separately through metadata.
 226
 227 The following entries can take advantage of the string table while respecting
 228 YAML rules:
 229
 230 * ``<pass>``
 231 * ``<name>``
 232 * ``<function>``
 233 * ``<file>``
 234 * ``<value>``
 235 * ``<arg-file>``
 236
 237 Currently, none of the tools in :ref:`the opt-viewer directory <optviewer>`
 238 support this format.
 239
 240 .. _optviewer:
 241
 242 YAML metadata
 243 -------------
 244
 245 The metadata used together with the YAML format is:
 246
 247 * a magic number: "REMARKS\\0"
 248 * the version number: a little-endian uint64_t
 249 * the total size of the string table (the size itself excluded):
 250   little-endian uint64_t
 251 * a list of null-terminated strings
 252
 253 Optional:
 254
 255 * the absolute file path to the serialized remark diagnostics: a
 256   null-terminated string.
 257
 258 When the metadata is serialized separately from the remarks, the file path
 259 should be present and point to the file where the remarks are serialized to.
 260
 261 In case the metadata only acts as a header to the remarks, the file path can be
 262 omitted.
 263
 264 .. _bitstreamremarks:
 265
 266 LLVM bitstream remarks
 267 ======================
 268
 269 This format is using :doc:`LLVM bitstream <BitCodeFormat>` to serialize remarks
 270 and their associated metadata.
 271
 272 A bitstream remark stream can be identified by the magic number ``"RMRK"`` that
 273 is placed at the very beginning.
 274
 275 The format for serializing remarks is composed of two different block types:
 276
 277 .. _bitstreamremarksmetablock:
 278
 279 META_BLOCK
 280 ----------
 281
 282 The block providing information about the rest of the content in the stream.
 283
 284 Exactly one block is expected. Having multiple metadata blocks is an error.
 285
 286 This block can contain the following records:
 287
 288 .. _bitstreamremarksrecordmetacontainerinfo:
 289
 290 ``RECORD_META_CONTAINER_INFO``
 291
 292     The container version and type.
 293
 294     Version: u32
 295
 296     Type:    u2
 297
 298 .. _bitstreamremarksrecordmetaremarkversion:
 299
 300 ``RECORD_META_REMARK_VERSION``
 301
 302     The version of the remark entries. This can change independently from the
 303     container version.
 304
 305     Version: u32
 306
 307 .. _bitstreamremarksrecordmetastrtab:
 308
 309 ``RECORD_META_STRTAB``
 310
 311     The string table used by the remark entries. The format of the string table
 312     is a sequence of strings separated by ``\0``.
 313
 314 .. _bitstreamremarksrecordmetaexternalfile:
 315
 316 ``RECORD_META_EXTERNAL_FILE``
 317
 318     The external remark file path that contains the remark blocks associated
 319     with this metadata. This is an absolute path.
 320
 321 .. _bitstreamremarksremarkblock:
 322
 323 REMARK_BLOCK
 324 ------------
 325
 326 The block describing a remark entry.
 327
 328 0 or more blocks per file are allowed. Each block will depend on the
 329 :ref:`META_BLOCK <bitstreamremarksmetablock>` in order to be parsed correctly.
 330
 331 This block can contain the following records:
 332
 333 ``RECORD_REMARK_HEADER``
 334
 335     The header of the remark. This contains all the mandatory information about
 336     a remark.
 337
 338     +---------------+---------------------------+
 339     | Type          | u3                        |
 340     +---------------+---------------------------+
 341     | Remark name   | VBR6 (string table index) |
 342     +---------------+---------------------------+
 343     | Pass name     | VBR6 (string table index) |
 344     +---------------+---------------------------+
 345     | Function name | VBR6 (string table index) |
 346     +---------------+---------------------------+
 347
 348 ``RECORD_REMARK_DEBUG_LOC``
 349
 350     The source location for the corresponding remark. This record is optional.
 351
 352     +--------+---------------------------+
 353     | File   | VBR7 (string table index) |
 354     +--------+---------------------------+
 355     | Line   | u32                       |
 356     +--------+---------------------------+
 357     | Column | u32                       |
 358     +--------+---------------------------+
 359
 360 ``RECORD_REMARK_HOTNESS``
 361
 362     The hotness of the remark. This record is optional.
 363
 364     +---------------+---------------------+
 365     | Hotness | VBR8 (string table index) |
 366     +---------------+---------------------+
 367
 368 ``RECORD_REMARK_ARG_WITH_DEBUGLOC``
 369
 370     A remark argument with an associated debug location.
 371
 372     +--------+---------------------------+
 373     | Key    | VBR7 (string table index) |
 374     +--------+---------------------------+
 375     | Value  | VBR7 (string table index) |
 376     +--------+---------------------------+
 377     | File   | VBR7 (string table index) |
 378     +--------+---------------------------+
 379     | Line   | u32                       |
 380     +--------+---------------------------+
 381     | Column | u32                       |
 382     +--------+---------------------------+
 383
 384 ``RECORD_REMARK_ARG_WITHOUT_DEBUGLOC``
 385
 386     A remark argument with an associated debug location.
 387
 388     +--------+---------------------------+
 389     | Key    | VBR7 (string table index) |
 390     +--------+---------------------------+
 391     | Value  | VBR7 (string table index) |
 392     +--------+---------------------------+
 393
 394 The remark container
 395 --------------------
 396
 397 Bitstream remarks are designed to be used in two different modes:
 398
 399 ``The separate mode``
 400
 401     The separate mode is the mode that is typically used during compilation. It
 402     provides a way to serialize the remark entries to a stream while some
 403     metadata is kept in memory to be emitted in the product of the compilation
 404     (typically, an object file).
 405
 406 ``The standalone mode``
 407
 408     The standalone mode is typically stored and used after the distribution of
 409     a program. It contains all the information that allows the parsing of all
 410     the remarks without having any external dependencies.
 411
 412 In order to support multiple modes, the format introduces the concept of a
 413 bitstream remark container type.
 414
 415 .. _bitstreamremarksseparateremarksmeta:
 416
 417 ``SeparateRemarksMeta: the metadata emitted separately``
 418
 419     This container type expects only a :ref:`META_BLOCK <bitstreamremarksmetablock>` containing only:
 420
 421     * :ref:`RECORD_META_CONTAINER_INFO <bitstreamremarksrecordmetacontainerinfo>`
 422     * :ref:`RECORD_META_STRTAB <bitstreamremarksrecordmetastrtab>`
 423     * :ref:`RECORD_META_EXTERNAL_FILE <bitstreamremarksrecordmetaexternalfile>`
 424
 425     Typically, this is emitted in a section in the object files, allowing
 426     clients to retrieve remarks and their associated metadata directly from
 427     intermediate products.
 428
 429 ``SeparateRemarksFile: the remark entries emitted separately``
 430
 431     This container type expects only a :ref:`META_BLOCK <bitstreamremarksmetablock>` containing only:
 432
 433     * :ref:`RECORD_META_CONTAINER_INFO <bitstreamremarksrecordmetacontainerinfo>`
 434     * :ref:`RECORD_META_REMARK_VERSION <bitstreamremarksrecordmetaremarkversion>`
 435
 436     This container type expects 0 or more :ref:`REMARK_BLOCK <bitstreamremarksremarkblock>`.
 437
 438     Typically, this is emitted in a side-file alongside an object file, and is
 439     made to be able to stream to without increasing the memory consumption of
 440     the compiler. This is referenced by the :ref:`RECORD_META_EXTERNAL_FILE
 441     <bitstreamremarksrecordmetaexternalfile>` entry in the
 442     :ref:`SeparateRemarksMeta <bitstreamremarksseparateremarksmeta>` container.
 443
 444 When the parser tries to parse a container that contains the metadata for the
 445 separate remarks, it should parse the version and type, then keep the string
 446 table in memory while opening the external file, validating its metadata and
 447 parsing the remark entries.
 448
 449 The container versions from the separate container should match in order to
 450 have a well-formed file.
 451
 452 ``Standalone: the metadata and the remark entries emitted together``
 453
 454     This container type expects only a :ref:`META_BLOCK <bitstreamremarksmetablock>` containing only:
 455
 456     * :ref:`RECORD_META_CONTAINER_INFO <bitstreamremarksrecordmetacontainerinfo>`
 457     * :ref:`RECORD_META_REMARK_VERSION <bitstreamremarksrecordmetaremarkversion>`
 458     * :ref:`RECORD_META_STRTAB <bitstreamremarksrecordmetastrtab>`
 459
 460     This container type expects 0 or more :ref:`REMARK_BLOCK <bitstreamremarksremarkblock>`.
 461
 462 A complete output of :program:`llvm-bcanalyzer` on the different container types:
 463
 464 ``SeparateRemarksMeta``
 465
 466 .. code-block:: none
 467
 468     <BLOCKINFO_BLOCK/>
 469     <Meta BlockID=8 NumWords=13 BlockCodeSize=3>
 470       <Container info codeid=1 abbrevid=4 op0=5 op1=0/>
 471       <String table codeid=3 abbrevid=5/> blob data = 'pass\\x00key\\x00value\\x00'
 472       <External File codeid=4 abbrevid=6/> blob data = '/path/to/file/name'
 473     </Meta>
 474
 475 ``SeparateRemarksFile``
 476
 477 .. code-block:: none
 478
 479     <BLOCKINFO_BLOCK/>
 480     <Meta BlockID=8 NumWords=3 BlockCodeSize=3>
 481       <Container info codeid=1 abbrevid=4 op0=0 op1=1/>
 482       <Remark version codeid=2 abbrevid=5 op0=0/>
 483     </Meta>
 484     <Remark BlockID=9 NumWords=8 BlockCodeSize=4>
 485       <Remark header codeid=5 abbrevid=4 op0=2 op1=0 op2=1 op3=2/>
 486       <Remark debug location codeid=6 abbrevid=5 op0=3 op1=99 op2=55/>
 487       <Remark hotness codeid=7 abbrevid=6 op0=999999999/>
 488       <Argument with debug location codeid=8 abbrevid=7 op0=4 op1=5 op2=6 op3=11 op4=66/>
 489     </Remark>
 490
 491 ``Standalone``
 492
 493 .. code-block:: none
 494
 495     <BLOCKINFO_BLOCK/>
 496     <Meta BlockID=8 NumWords=15 BlockCodeSize=3>
 497       <Container info codeid=1 abbrevid=4 op0=5 op1=2/>
 498       <Remark version codeid=2 abbrevid=5 op0=30/>
 499       <String table codeid=3 abbrevid=6/> blob data = 'pass\\x00remark\\x00function\\x00path\\x00key\\x00value\\x00argpath\\x00'
 500     </Meta>
 501     <Remark BlockID=9 NumWords=8 BlockCodeSize=4>
 502       <Remark header codeid=5 abbrevid=4 op0=2 op1=1 op2=0 op3=2/>
 503       <Remark debug location codeid=6 abbrevid=5 op0=3 op1=99 op2=55/>
 504       <Remark hotness codeid=7 abbrevid=6 op0=999999999/>
 505       <Argument with debug location codeid=8 abbrevid=7 op0=4 op1=5 op2=6 op3=11 op4=66/>
 506     </Remark>
 507
 508 opt-viewer
 509 ==========
 510
 511 The ``opt-viewer`` directory contains a collection of tools that visualize and
 512 summarize serialized remarks.
 513
 514 The tools only support the ``yaml`` format.
 515
 516 .. _optviewerpy:
 517
 518 opt-viewer.py
 519 -------------
 520
 521 Output a HTML page which gives visual feedback on compiler interactions with
 522 your program.
 523
 524     :Examples:
 525
 526     ::
 527
 528         $ opt-viewer.py my_yaml_file.opt.yaml
 529
 530     ::
 531
 532         $ opt-viewer.py my_build_dir/
 533
 534
 535 opt-stats.py
 536 ------------
 537
 538 Output statistics about the optimization remarks in the input set.
 539
 540     :Example:
 541
 542     ::
 543
 544         $ opt-stats.py my_yaml_file.opt.yaml
 545
 546         Total number of remarks           3
 547
 548
 549         Top 10 remarks by pass:
 550           inline                         33%
 551           asm-printer                    33%
 552           prologepilog                   33%
 553
 554         Top 10 remarks:
 555           asm-printer/InstructionCount   33%
 556           inline/NoDefinition            33%
 557           prologepilog/StackSize         33%
 558
 559 opt-diff.py
 560 -----------
 561
 562 Produce a new YAML file which contains all of the changes in optimizations
 563 between two YAML files.
 564
 565 Typically, this tool should be used to do diffs between:
 566
 567 * new compiler + fixed source vs old compiler + fixed source
 568 * fixed compiler + new source vs fixed compiler + old source
 569
 570 This diff file can be displayed using :ref:`opt-viewer.py <optviewerpy>`.
 571
 572     :Example:
 573
 574     ::
 575
 576         $ opt-diff.py my_opt_yaml1.opt.yaml my_opt_yaml2.opt.yaml -o my_opt_diff.opt.yaml
 577         $ opt-viewer.py my_opt_diff.opt.yaml
 578
 579 .. _remarkssection:
 580
 581 Emitting remark diagnostics in the object file
 582 ==============================================
 583
 584 A section containing metadata on remark diagnostics will be emitted when
 585 -remarks-section is passed. The section contains the metadata associated to the
 586 format used to serialize the remarks.
 587
 588 The section is named:
 589
 590 * ``__LLVM,__remarks`` (MachO)
 591 * ``.remarks`` (ELF)
 592
 593 C API
 594 =====
 595
 596 LLVM provides a library that can be used to parse remarks through a shared
 597 library named ``libRemarks``.
 598
 599 The typical usage through the C API is like the following:
 600
 601 .. code-block:: c
 602
 603     LLVMRemarkParserRef Parser = LLVMRemarkParserCreateYAML(Buf, Size);
 604     LLVMRemarkEntryRef Remark = NULL;
 605     while ((Remark = LLVMRemarkParserGetNext(Parser))) {
 606        // use Remark
 607        LLVMRemarkEntryDispose(Remark); // Release memory.
 608     }
 609     bool HasError = LLVMRemarkParserHasError(Parser);
 610     LLVMRemarkParserDispose(Parser);
 611
 612 .. FIXME: add documentation for llvm-opt-report.
 613 .. FIXME: add documentation for Passes supporting optimization remarks
 614 .. FIXME: add documentation for IR Passes
 615 .. FIXME: add documentation for CodeGen Passes