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. 17 18MisExpect diagnostics are intended to help developers identify and address 19these situations, by comparing the branch weights added by the ``llvm.expect`` 20intrinsic to those collected through profiling. Whenever these values are 21mismatched, a diagnostic is surfaced to the user. Details on how the checks 22operate in the LLVM backed can be found in LLVM's documentation. 23 24By default MisExpect checking is quite strict, because the use of the 25``llvm.expect`` intrinsic is designed for specialized cases, where the outcome 26of a condition is severely skewed. As a result, the optimizer can be extremely 27aggressive, which can result in performance degradation if the outcome is less 28predictable than the annotation suggests. Even when the annotation is correct 2990% of the time, it may be beneficial to either remove the annotation or to use 30a different intrinsic that can communicate the probability more directly. 31 32Because this may be too strict, MisExpect diagnostics are not enabled by 33default, and support an additional flag to tolerate some deviation from the 34exact thresholds. The ``-fdiagnostic-misexpect-tolerance=N`` accepts 35deviations when comparing branch weights within ``N%`` of the expected values. 36So passing ``-fdiagnostic-misexpect-tolerance=5`` will not report diagnostic messages 37if the branch weight from the profile is within 5% of the weight added by 38the ``llvm.expect`` intrinsic. 39 40MisExpect diagnostics are also available in the form of optimization remarks, 41which can be serialized and processed through the ``opt-viewer.py`` 42scripts in LLVM. 43 44.. option:: -Rpass=misexpect 45 46 Enables optimization remarks for misexpect when profiling data conflicts with 47 use of ``llvm.expect`` intrinsics. 48 49 50.. option:: -Wmisexpect 51 52 Enables misexpect warnings when profiling data conflicts with use of 53 ``llvm.expect`` intrinsics. 54 55.. option:: -fdiagnostic-misexpect-tolerance=N 56 57 Relaxes misexpect checking to tolerate profiling values within N% of the 58 expected branch weight. e.g., a value of ``N=5`` allows misexpect to check against 59 ``0.95 * Threshold`` 60 61LLVM supports 4 types of profile formats: Frontend, IR, CS-IR, and 62Sampling. MisExpect Diagnostics are compatible with all Profiling formats. 63 64+----------------+--------------------------------------------------------------------------------------+ 65| Profile Type | Description | 66+================+======================================================================================+ 67| Frontend | Profiling instrumentation added during compilation by the frontend, i.e. ``clang`` | 68+----------------+--------------------------------------------------------------------------------------+ 69| IR | Profiling instrumentation added during by the LLVM backend | 70+----------------+--------------------------------------------------------------------------------------+ 71| CS-IR | Context Sensitive IR based profiles | 72+----------------+--------------------------------------------------------------------------------------+ 73| Sampling | Profiles collected through sampling with external tools, such as ``perf`` on Linux | 74+----------------+--------------------------------------------------------------------------------------+ 75 76