From 23a6033104c5f3fde8fe3b359d25e57a728613aa Mon Sep 17 00:00:00 2001 From: "Duncan P. N. Exon Smith" Date: Fri, 11 Apr 2014 23:21:07 +0000 Subject: [PATCH] blockfreq: Document BlockFrequencyInfo terminology Documents terminology used in the forthcoming rewrite of BlockFrequencyInfo. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@206086 91177308-0d34-0410-b5e6-96231b3b80d8 --- docs/BlockFrequencyTerminology.rst | 130 +++++++++++++++++++++++++++++ docs/BranchWeightMetadata.rst | 9 +- docs/index.rst | 5 ++ 3 files changed, 140 insertions(+), 4 deletions(-) create mode 100644 docs/BlockFrequencyTerminology.rst diff --git a/docs/BlockFrequencyTerminology.rst b/docs/BlockFrequencyTerminology.rst new file mode 100644 index 00000000000..512dee18f18 --- /dev/null +++ b/docs/BlockFrequencyTerminology.rst @@ -0,0 +1,130 @@ +================================ +LLVM Block Frequency Terminology +================================ + +.. contents:: + :local: + +Introduction +============ + +Block Frequency is a metric for estimating the relative frequency of different +basic blocks. This document describes the terminology that the +``BlockFrequencyInfo`` and ``MachineBlockFrequencyInfo`` analysis passes use. + +Branch Probability +================== + +Blocks with multiple successors have probabilities associated with each +outgoing edge. These are called branch probabilities. For a given block, the +sum of its outgoing branch probabilities should be 1.0. + +Branch Weight +============= + +Rather than storing fractions on each edge, we store an integer weight. +Weights are relative to the other edges of a given predecessor block. The +branch probability associated with a given edge is its own weight divided by +the sum of the weights on the predecessor's outgoing edges. + +For example, consider this IR: + +.. code-block:: llvm + + define void @foo() { + ; ... + A: + br i1 %cond, label %B, label %C, !prof !0 + ; ... + } + !0 = metadata !{metadata !"branch_weights", i32 7, i32 8} + +and this simple graph representation:: + + A -> B (edge-weight: 7) + A -> C (edge-weight: 8) + +The probability of branching from block A to block B is 7/15, and the +probability of branching from block A to block C is 8/15. + +See :doc:`BranchWeightMetadata` for details about the branch weight IR +representation. + +Block Frequency +=============== + +Block frequency is a relative metric that represents the number of times a +block executes. The ratio of a block frequency to the entry block frequency is +the expected number of times the block will execute per entry to the function. + +Block frequency is the main output of the ``BlockFrequencyInfo`` and +``MachineBlockFrequencyInfo`` analysis passes. + +Implementation: a series of DAGs +================================ + +The implementation of the block frequency calculation analyses each loop, +bottom-up, ignoring backedges; i.e., as a DAG. After each loop is processed, +it's packaged up to act as a pseudo-node in its parent loop's (or the +function's) DAG analysis. + +Block Mass +========== + +For each DAG, the entry node is assigned a mass of ``UINT64_MAX`` and mass is +distributed to successors according to branch weights. Block Mass uses a +fixed-point representation where ``UINT64_MAX`` represents ``1.0`` and ``0`` +represents a number just above ``0.0``. + +After mass is fully distributed, in any cut of the DAG that separates the exit +nodes from the entry node, the sum of the block masses of the nodes succeeded +by a cut edge should equal ``UINT64_MAX``. In other words, mass is conserved +as it "falls" through the DAG. + +If a function's basic block graph is a DAG, then block masses are valid block +frequencies. This works poorly in practise though, since downstream users rely +on adding block frequencies together without hitting the maximum. + +Loop Scale +========== + +Loop scale is a metric that indicates how many times a loop iterates per entry. +As mass is distributed through the loop's DAG, the (otherwise ignored) backedge +mass is collected. This backedge mass is used to compute the exit frequency, +and thus the loop scale. + +Implementation: Getting from mass and scale to frequency +======================================================== + +After analysing the complete series of DAGs, each block has a mass (local to +its containing loop, if any), and each loop psuedo-node has a loop scale and +its own mass (from its parent's DAG). + +We can get an initial frequency assignment (with entry frequency of 1.0) by +multiplying these masses and loop scales together. A given block's frequency +is the product of its mass, the mass of containing loops' pseudo nodes, and the +containing loops' loop scales. + +Since downstream users need integers (not floating point), this initial +frequency assignment is shifted as necessary into the range of ``uint64_t``. + +Block Bias +========== + +Block bias is a proposed *absolute* metric to indicate a bias toward or away +from a given block during a function's execution. The idea is that bias can be +used in isolation to indicate whether a block is relatively hot or cold, or to +compare two blocks to indicate whether one is hotter or colder than the other. + +The proposed calculation involves calculating a *reference* block frequency, +where: + +* every branch weight is assumed to be 1 (i.e., every branch probability + distribution is even) and + +* loop scales are ignored. + +This reference frequency represents what the block frequency would be in an +unbiased graph. + +The bias is the ratio of the block frequency to this reference block frequency. diff --git a/docs/BranchWeightMetadata.rst b/docs/BranchWeightMetadata.rst index 71ecd34c821..aff7923d186 100644 --- a/docs/BranchWeightMetadata.rst +++ b/docs/BranchWeightMetadata.rst @@ -8,10 +8,11 @@ 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. diff --git a/docs/index.rst b/docs/index.rst index a55795e3a0c..93a160028be 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -215,6 +215,7 @@ For API clients and LLVM developers. AliasAnalysis BitCodeFormat + BlockFrequencyTerminology BranchWeightMetadata Bugpoint CodeGenerator @@ -298,6 +299,10 @@ For API clients and LLVM developers. :doc:`BranchWeightMetadata` Provides information about Branch Prediction Information. +:doc:`BlockFrequencyTerminology` + Provides information about terminology used in the ``BlockFrequencyInfo`` + analysis pass. + :doc:`SegmentedStacks` This document describes segmented stacks and how they are used in LLVM.