-.. _branch_weight:
-
===========================
LLVM Branch Weight Metadata
===========================
Introduction
============
-Branch Weight Metadata represents branch weights as its likeliness to be
-taken. Metadata is assigned to the ``TerminatorInst`` as a ``MDNode`` of the
-``MD_prof`` kind. The first operator is always a ``MDString`` node with the
-string "branch_weights". Number of operators depends on the terminator type.
+Branch Weight Metadata represents branch weights as its likeliness to be taken
+(see :doc:`BlockFrequencyTerminology`). Metadata is assigned to the
+``TerminatorInst`` as a ``MDNode`` of the ``MD_prof`` kind. The first operator
+is always a ``MDString`` node with the string "branch_weights". Number of
+operators depends on the terminator type.
Branch weights might be fetch from the profiling file, or generated based on
`__builtin_expect`_ instruction.
``BranchInst``
^^^^^^^^^^^^^^
-Metadata is only assign to the conditional branches. There are two extra
-operarands, for the true and the false branch.
+Metadata is only assigned to the conditional branches. There are two extra
+operands for the true and the false branch.
.. code-block:: llvm
``SwitchInst``
^^^^^^^^^^^^^^
-Branch weights are assign to every case (including ``default`` case which is
-always case #0).
+Branch weights are assigned to every case (including the ``default`` case which
+is always case #0).
.. code-block:: llvm
``IndirectBrInst``
^^^^^^^^^^^^^^^^^^
-Branch weights are assign to every destination.
+Branch weights are assigned to every destination.
.. code-block:: llvm
Branch Weight Metatada is not proof against CFG changes. If terminator operands'
are changed some action should be taken. In other case some misoptimizations may
-occur due to incorrent branch prediction information.
+occur due to incorrect branch prediction information.
+
+Function Entry Counts
+=====================
+
+To allow comparing different functions during inter-procedural analysis and
+optimization, ``MD_prof`` nodes can also be assigned to a function definition.
+The first operand is a string indicating the name of the associated counter.
+
+Currently, one counter is supported: "function_entry_count". This is a 64-bit
+counter that indicates the number of times that this function was invoked (in
+the case of instrumentation-based profiles). In the case of sampling-based
+profiles, this counter is an approximation of how many times the function was
+invoked.
+
+For example, in the code below, the instrumentation for function foo()
+indicates that it was called 2,590 times at runtime.
+
+.. code-block:: llvm
+
+ define i32 @foo() !prof !1 {
+ ret i32 0
+ }
+ !1 = !{!"function_entry_count", i64 2590}