1 ===========================
2 LLVM Branch Weight Metadata
3 ===========================
11 Branch Weight Metadata represents branch weights as its likeliness to be taken
12 (see :doc:`BlockFrequencyTerminology`). Metadata is assigned to the
13 ``TerminatorInst`` as a ``MDNode`` of the ``MD_prof`` kind. The first operator
14 is always a ``MDString`` node with the string "branch_weights". Number of
15 operators depends on the terminator type.
17 Branch weights might be fetch from the profiling file, or generated based on
18 `__builtin_expect`_ instruction.
20 All weights are represented as an unsigned 32-bit values, where higher value
21 indicates greater chance to be taken.
23 Supported Instructions
24 ======================
29 Metadata is only assigned to the conditional branches. There are two extra
30 operarands for the true and the false branch.
35 metadata !"branch_weights",
36 i32 <TRUE_BRANCH_WEIGHT>,
37 i32 <FALSE_BRANCH_WEIGHT>
43 Branch weights are assigned to every case (including the ``default`` case which
49 metadata !"branch_weights",
50 i32 <DEFAULT_BRANCH_WEIGHT>
51 [ , i32 <CASE_BRANCH_WEIGHT> ... ]
57 Branch weights are assigned to every destination.
62 metadata !"branch_weights",
63 i32 <LABEL_BRANCH_WEIGHT>
64 [ , i32 <LABEL_BRANCH_WEIGHT> ... ]
70 Other terminator instructions are not allowed to contain Branch Weight Metadata.
72 .. _\__builtin_expect:
74 Built-in ``expect`` Instructions
75 ================================
77 ``__builtin_expect(long exp, long c)`` instruction provides branch prediction
78 information. The return value is the value of ``exp``.
80 It is especially useful in conditional statements. Currently Clang supports two
81 conditional statements:
86 The ``exp`` parameter is the condition. The ``c`` parameter is the expected
87 comparison value. If it is equal to 1 (true), the condition is likely to be
88 true, in other case condition is likely to be false. For example:
92 if (__builtin_expect(x > 0, 1)) {
93 // This block is likely to be taken.
99 The ``exp`` parameter is the value. The ``c`` parameter is the expected
100 value. If the expected value doesn't show on the cases list, the ``default``
101 case is assumed to be likely taken.
105 switch (__builtin_expect(x, 5)) {
109 case 5: // This case is likely to be taken.
115 Branch Weight Metatada is not proof against CFG changes. If terminator operands'
116 are changed some action should be taken. In other case some misoptimizations may
117 occur due to incorrent branch prediction information.