llvm/docs/MisExpect.rst

   1 ===================
   2 Misexpect
   3 ===================
   4 .. contents::
   5
   6 .. toctree::
   7    :maxdepth: 1
   8
   9 When developers use ``llvm.expect`` intrinsics, i.e., through use of
  10 ``__builtin_expect(...)``, they are trying to communicate how their code is
  11 expected to behave at runtime to the optimizer. These annotations, however, can
  12 be incorrect for a variety of reasons: changes to the code base invalidate them
  13 silently, the developer mis-annotated them (e.g., using ``LIKELY`` instead of
  14 ``UNLIKELY``), or perhaps they assumed something incorrectly when they wrote
  15 the annotation. Regardless of why, it is useful to detect these situations so
  16 that the optimizer can make more useful decisions about the code. MisExpect
  17 diagnostics are intended to help developers identify and address these
  18 situations, by comparing the use of the ``llvm.expect`` intrinsic to the ground
  19 truth provided by a profiling input.
  20
  21 The MisExpect checks in the LLVM backend follow a simple procedure: if there is
  22 a mismatch between the branch weights collected during profiling and those
  23 supplied by an ``llvm.expect`` intrinsic, then it will emit a diagnostic
  24 message to the user.
  25
  26 The most natural place to perform the verification is just prior to when
  27 branch weights are assigned to the target instruction in the form of
  28 branch weight metadata.
  29
  30 There are 3 key places in the LLVM backend where branch weights are
  31 created and assigned based on profiling information or the use of the
  32 ``llvm.expect`` intrinsic, and our implementation focuses on these
  33 places to perform the verification.
  34
  35 We calculate the threshold for emitting MisExpect related diagnostics
  36 based on the values the compiler assigns to ``llvm.expect`` intrinsics,
  37 which can be set through the ``-likely-branch-weight`` and
  38 ``-unlikely-branch-weight`` LLVM options. During verification, if the
  39 profile weights mismatch the calculated threshold, then we will emit a
  40 remark or warning detailing a potential performance regression. The
  41 diagnostic also reports the percentage of the time the annotation was
  42 correct during profiling to help developers reason about how to proceed.
  43
  44 The diagnostics are also available in the form of optimization remarks,
  45 which can be serialized and processed through the ``opt-viewer.py``
  46 scripts in LLVM.
  47
  48 .. option:: -pass-remarks=misexpect
  49
  50   Enables optimization remarks for misexpect when profiling data conflicts with
  51   use of ``llvm.expect`` intrinsics.
  52
  53
  54 .. option:: -pgo-warn-misexpect
  55
  56   Enables misexpect warnings when profiling data conflicts with use of
  57   ``llvm.expect`` intrinsics.
  58
  59 LLVM supports 4 types of profile formats: Frontend, IR, CS-IR, and
  60 Sampling. MisExpect Diagnostics are compatible with all Profiling formats.
  61
  62 +----------------+--------------------------------------------------------------------------------------+
  63 | Profile Type   | Description                                                                          |
  64 +================+======================================================================================+
  65 | Frontend       | Profiling instrumentation added during compilation by the frontend, i.e. ``clang``   |
  66 +----------------+--------------------------------------------------------------------------------------+
  67 | IR             | Profiling instrumentation added during by the LLVM backend                           |
  68 +----------------+--------------------------------------------------------------------------------------+
  69 | CS-IR          | Context Sensitive IR based profiles                                                  |
  70 +----------------+--------------------------------------------------------------------------------------+
  71 | Sampling       | Profiles collected through sampling with external tools, such as ``perf`` on Linux   |
  72 +----------------+--------------------------------------------------------------------------------------+
  73