From f46c674a16669518dbb24d4cdd4bfc904dd3b505 Mon Sep 17 00:00:00 2001 From: Chandler Carruth Date: Mon, 24 Oct 2011 05:55:58 +0000 Subject: Doxygen-ify the comments on the public interface for BPI. Also, move the two more subtle routines to the bottom and expand on their cautionary comments a bit. No functionality or actual interface change here. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@142789 91177308-0d34-0410-b5e6-96231b3b80d8 --- include/llvm/Analysis/BranchProbabilityInfo.h | 65 +++++++++++++++++++-------- 1 file changed, 47 insertions(+), 18 deletions(-) diff --git a/include/llvm/Analysis/BranchProbabilityInfo.h b/include/llvm/Analysis/BranchProbabilityInfo.h index 82360dc..9148d29 100644 --- a/include/llvm/Analysis/BranchProbabilityInfo.h +++ b/include/llvm/Analysis/BranchProbabilityInfo.h @@ -23,6 +23,15 @@ namespace llvm { class LoopInfo; class raw_ostream; +/// \brief Analysis pass providing branch probability information. +/// +/// This is a function analysis pass which provides information on the relative +/// probabilities of each "edge" in the function's CFG where such an edge is +/// defined by a pair of basic blocks. The probability for a given block and +/// a successor block are always relative to the probabilities of the other +/// successor blocks. Another way of looking at it is that the probabilities +/// for a given block B and each of its successors should sum to exactly +/// one (100%). class BranchProbabilityInfo : public FunctionPass { public: static char ID; @@ -35,32 +44,52 @@ public: bool runOnFunction(Function &F); void print(raw_ostream &OS, const Module *M = 0) const; - // Returned value is between 1 and UINT32_MAX. Look at - // BranchProbabilityInfo.cpp for details. - uint32_t getEdgeWeight(const BasicBlock *Src, const BasicBlock *Dst) const; - - // Look at BranchProbabilityInfo.cpp for details. Use it with caution! - void setEdgeWeight(const BasicBlock *Src, const BasicBlock *Dst, - uint32_t Weight); + /// \brief Get an edge's probability, relative to other out-edges of the Src. + /// + /// This routine provides access to the fractional probability between zero + /// (0%) and one (100%) of this edge executing, relative to other edges + /// leaving the 'Src' block. The returned probability is never zero, and can + /// only be one if the source block has only one successor. + BranchProbability getEdgeProbability(const BasicBlock *Src, + const BasicBlock *Dst) const; - // A 'Hot' edge is an edge which probability is >= 80%. + /// \brief Test if an edge is hot relative to other out-edges of the Src. + /// + /// Check whether this edge out of the source block is 'hot'. We define hot + /// as having a relative probability >= 80%. bool isEdgeHot(const BasicBlock *Src, const BasicBlock *Dst) const; - // Return a hot successor for the block BB or null if there isn't one. + /// \brief Retrieve the hot successor of a block if one exists. + /// + /// Given a basic block, look through its successors and if one exists for + /// which \see isEdgeHot would return true, return that successor block. BasicBlock *getHotSucc(BasicBlock *BB) const; - // Return a probability as a fraction between 0 (0% probability) and - // 1 (100% probability), however the value is never equal to 0, and can be 1 - // only iff SRC block has only one successor. - BranchProbability getEdgeProbability(const BasicBlock *Src, - const BasicBlock *Dst) const; - - // Print value between 0 (0% probability) and 1 (100% probability), - // however the value is never equal to 0, and can be 1 only iff SRC block - // has only one successor. + /// \brief Print an edge's probability. + /// + /// Retrieves an edge's probability similarly to \see getEdgeProbability, but + /// then prints that probability to the provided stream. That stream is then + /// returned. raw_ostream &printEdgeProbability(raw_ostream &OS, const BasicBlock *Src, const BasicBlock *Dst) const; + /// \brief Get the raw edge weight calculated for the block pair. + /// + /// This returns the raw edge weight. It is guaranteed to fall between 1 and + /// UINT32_MAX. Note that the raw edge weight is not meaningful in isolation. + /// This interface should be very carefully, and primarily by routines that + /// are updating the analysis by later calling setEdgeWeight. + uint32_t getEdgeWeight(const BasicBlock *Src, const BasicBlock *Dst) const; + + /// \brief Set the raw edge weight for the block pair. + /// + /// This allows a pass to explicitly set the edge weight for a block. It can + /// be used when updating the CFG to update and preserve the branch + /// probability information. Read the implementation of how these edge + /// weights are calculated carefully before using! + void setEdgeWeight(const BasicBlock *Src, const BasicBlock *Dst, + uint32_t Weight); + private: typedef std::pair Edge; -- cgit v1.1