Fix documentation for FindAvailableLoadedValue.

llvm-svn: 273734

llvm/include/llvm/Analysis/Loads.h

@@ -61,24 +61,34 @@ bool isSafeToLoadUnconditionally(Value *V, unsigned Align,
 /// to scan in the block, used by FindAvailableLoadedValue().
 extern cl::opt<unsigned> DefMaxInstsToScan;
 
-/// FindAvailableLoadedValue - Scan the ScanBB block backwards (starting at
+/// \brief Scan backwards to see if we have the value of the given load
-/// the instruction before ScanFrom) checking to see if we have the value at
+/// available locally within a small number of instructions.
-/// the memory address *Ptr locally available within a small number of
-///  instructions. If the value is available, return it.
 ///
-/// If not, return the iterator for the last validated instruction that the
+/// You can use this function to scan across multiple blocks: after you call
-/// value would be live through.  If we scanned the entire block and didn't
+/// this function, if ScanFrom points at the beginning of the block, it's safe
-/// find something that invalidates *Ptr or provides it, ScanFrom would be
+/// to continue scanning the predecessors.
-/// left at begin() and this returns null.  ScanFrom could also be left
 ///
-/// MaxInstsToScan specifies the maximum instructions to scan in the block.
+/// Note that performing load CSE requires special care to make sure the
-/// If it is set to 0, it will scan the whole block. You can also optionally
+/// metadata is set appropriately.  In particular, aliasing metadata needs
-/// specify an alias analysis implementation, which makes this more precise.
+/// to be merged.  (This doesn't matter for store-to-load forwarding because
+/// the only relevant load gets deleted.)
 ///
-/// If AATags is non-null and a load or store is found, the AA tags from the
+/// \param Load The load we want to replace.
-/// load or store are recorded there.  If there are no AA tags or if no access
+/// \param ScanBB The basic block to scan. FIXME: This is redundant.
-/// is found, it is left unmodified.
+/// \param [in,out] ScanFrom The location to start scanning from. When this
-Value *FindAvailableLoadedValue(LoadInst *Load, BasicBlock *ScanBB,
+/// function returns, it points at the last instruction scanned.
+/// \param MaxInstsToScan The maximum number of instructions to scan. If this
+/// is zero, the whole block will be scanned.
+/// \param AA Optional pointer to alias analysis, to make the scan more
+/// precise.
+/// \param [out] AATags The aliasing metadata for the operation which produced
+/// the value. FIXME: This is basically useless.
+/// \param [out] isLoadCSE Whether the returned value is a load from the same
+/// location in memory, as opposed to the value operand of a store.
+///
+/// \returns The found value, or nullptr if no value is found.
+Value *FindAvailableLoadedValue(LoadInst *Load,
+                                BasicBlock *ScanBB,
                                 BasicBlock::iterator &ScanFrom,
                                 unsigned MaxInstsToScan = DefMaxInstsToScan,
                                 AliasAnalysis *AA = nullptr,

llvm/lib/Analysis/Loads.cpp

@@ -300,25 +300,6 @@ llvm::DefMaxInstsToScan("available-load-scan-limit", cl::init(6), cl::Hidden,
            "to scan backward from a given instruction, when searching for "
            "available loaded value"));
 
-/// \brief Scan the ScanBB block backwards to see if we have the value at the
-/// memory address *Ptr locally available within a small number of instructions.
-///
-/// The scan starts from \c ScanFrom. \c MaxInstsToScan specifies the maximum
-/// instructions to scan in the block. If it is set to \c 0, it will scan the whole
-/// block.
-///
-/// If the value is available, this function returns it. If not, it returns the
-/// iterator for the last validated instruction that the value would be live
-/// through. If we scanned the entire block and didn't find something that
-/// invalidates \c *Ptr or provides it, \c ScanFrom is left at the last
-/// instruction processed and this returns null.
-///
-/// You can also optionally specify an alias analysis implementation, which
-/// makes this more precise.
-///
-/// If \c AATags is non-null and a load or store is found, the AA tags from the
-/// load or store are recorded there. If there are no AA tags or if no access is
-/// found, it is left unmodified.
 Value *llvm::FindAvailableLoadedValue(LoadInst *Load, BasicBlock *ScanBB,
                                       BasicBlock::iterator &ScanFrom,
                                       unsigned MaxInstsToScan,