1=================== 2Misexpect 3=================== 4.. contents:: 5 6.. toctree:: 7 :maxdepth: 1 8 9When developers use ``llvm.expect`` intrinsics, i.e., through use of 10``__builtin_expect(...)``, they are trying to communicate how their code is 11expected to behave at runtime to the optimizer. These annotations, however, can 12be incorrect for a variety of reasons: changes to the code base invalidate them 13silently, the developer mis-annotated them (e.g., using ``LIKELY`` instead of 14``UNLIKELY``), or perhaps they assumed something incorrectly when they wrote 15the annotation. Regardless of why, it is useful to detect these situations so 16that the optimizer can make more useful decisions about the code. MisExpect 17diagnostics are intended to help developers identify and address these 18situations, by comparing the use of the ``llvm.expect`` intrinsic to the ground 19truth provided by a profiling input. 20 21The MisExpect checks in the LLVM backend follow a simple procedure: if there is 22a mismatch between the branch weights collected during profiling and those 23supplied by an ``llvm.expect`` intrinsic, then it will emit a diagnostic 24message to the user. 25 26The most natural place to perform the verification is just prior to when 27branch weights are assigned to the target instruction in the form of 28branch weight metadata. 29 30There are 3 key places in the LLVM backend where branch weights are 31created and assigned based on profiling information or the use of the 32``llvm.expect`` intrinsic, and our implementation focuses on these 33places to perform the verification. 34 35We calculate the threshold for emitting MisExpect related diagnostics 36based on the values the compiler assigns to ``llvm.expect`` intrinsics, 37which can be set through the ``-likely-branch-weight`` and 38``-unlikely-branch-weight`` LLVM options. During verification, if the 39profile weights mismatch the calculated threshold, then we will emit a 40remark or warning detailing a potential performance regression. The 41diagnostic also reports the percentage of the time the annotation was 42correct during profiling to help developers reason about how to proceed. 43 44The diagnostics are also available in the form of optimization remarks, 45which can be serialized and processed through the ``opt-viewer.py`` 46scripts 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 59LLVM supports 4 types of profile formats: Frontend, IR, CS-IR, and 60Sampling. 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 74