75 lines · plain
1===================2Misexpect3===================4.. contents::5 6.. toctree::7 :maxdepth: 18 9When developers use ``llvm.expect`` intrinsics, i.e., through use of10``__builtin_expect(...)``, they are trying to communicate how their code is11expected to behave at runtime to the optimizer. These annotations, however, can12be incorrect for a variety of reasons: changes to the code base invalidate them13silently, the developer mis-annotated them (e.g., using ``LIKELY`` instead of14``UNLIKELY``), or perhaps they assumed something incorrectly when they wrote15the annotation. Regardless of why, it is useful to detect these situations so16that the optimizer can make more useful decisions about the code.17 18MisExpect diagnostics are intended to help developers identify and address19these situations, by comparing the branch weights added by the ``llvm.expect``20intrinsic to those collected through profiling. Whenever these values are21mismatched, a diagnostic is surfaced to the user. Details on how the checks22operate in the LLVM backend can be found in LLVM's documentation.23 24By default MisExpect checking is quite strict, because the use of the25``llvm.expect`` intrinsic is designed for specialized cases, where the outcome26of a condition is severely skewed. As a result, the optimizer can be extremely27aggressive, which can result in performance degradation if the outcome is less28predictable than the annotation suggests. Even when the annotation is correct2990% of the time, it may be beneficial to either remove the annotation or to use30a different intrinsic that can communicate the probability more directly.31 32Because this may be too strict, MisExpect diagnostics are not enabled by33default, and support an additional flag to tolerate some deviation from the34exact thresholds. The ``-fdiagnostic-misexpect-tolerance=N`` accepts35deviations when comparing branch weights within ``N%`` of the expected values.36So passing ``-fdiagnostic-misexpect-tolerance=5`` will not report diagnostic messages37if the branch weight from the profile is within 5% of the weight added by38the ``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=misexpect45 46 Enables optimization remarks for misexpect when profiling data conflicts with47 use of ``llvm.expect`` intrinsics.48 49 50.. option:: -Wmisexpect51 52 Enables misexpect warnings when profiling data conflicts with use of53 ``llvm.expect`` intrinsics.54 55.. option:: -fdiagnostic-misexpect-tolerance=N56 57 Relaxes misexpect checking to tolerate profiling values within N% of the58 expected branch weight. e.g., a value of ``N=5`` allows misexpect to check against59 ``0.95 * Threshold``60 61LLVM supports 4 types of profile formats: Frontend, IR, CS-IR, and62Sampling. 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