Clarify invariants of software pipelining hooks

[thopre]

Summary

PowerPC backend relies on each pair of prologue/epilogue of a software
pipelined loop to correspond to a single iteration a the loop through
its use of the BDZ instruction to skip inner prologues/epilogues and
loop kernel. However the interface does not make it clear that it is a
valid way to check that the trip count is big enough to execute inner
prologues/epilogues and kernel loop.

The API also does not specify in which order of prologues the
createTripCountGreaterCondition() hook is being called. Knowing that it
starts with the last/innermost prologues can help recording some
information when createTripCountGreaterCondition() is first executed and
reuse it in setPreheader() or adjustTripCount().

This commit documents both aspects.

llvm/include/llvm/CodeGen/TargetInstrInfo.h

public:
   public:
     virtual ~PipelinerLoopInfo();
     /// Return true if the given instruction should not be pipelined and should
     /// be ignored. An example could be a loop comparison, or induction variable
     /// update with no users being pipelined.
     virtual bool shouldIgnoreForPipelining(const MachineInstr *MI) const = 0;
 
     /// Create a condition to determine if the trip count of the loop is greater
-    /// than TC.
+    /// than TC, where TC is always one more than for the previous prologue or
+    /// 0 if this is being called for the outermost prologue.
     ///
     /// If the trip count is statically known to be greater than TC, return
     /// true. If the trip count is statically known to be not greater than TC,
     /// return false. Otherwise return nullopt and fill out Cond with the test
     /// condition.
+    ///
+    /// Note: This hook is guaranteed to be called from the innermost to the
+    /// outermost prologue of the loop being software pipelined.
     virtual Optional<bool>
     createTripCountGreaterCondition(int TC, MachineBasicBlock &MBB,
                                     SmallVectorImpl<MachineOperand> &Cond) = 0;
 
     /// Modify the loop such that the trip count is
     /// OriginalTC + TripCountAdjust.
     virtual void adjustTripCount(int TripCountAdjust) = 0;