[llvm] r366964 - [docs] Split out a section on LoopInfo in the new loop documentation
Philip Reames via llvm-commits
llvm-commits at lists.llvm.org
Wed Jul 24 16:46:13 PDT 2019
Author: reames
Date: Wed Jul 24 16:46:13 2019
New Revision: 366964
URL: http://llvm.org/viewvc/llvm-project?rev=366964&view=rev
Log:
[docs] Split out a section on LoopInfo in the new loop documentation
Modified:
llvm/trunk/docs/LoopTerminology.rst
Modified: llvm/trunk/docs/LoopTerminology.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/LoopTerminology.rst?rev=366964&r1=366963&r2=366964&view=diff
==============================================================================
--- llvm/trunk/docs/LoopTerminology.rst (original)
+++ llvm/trunk/docs/LoopTerminology.rst Wed Jul 24 16:46:13 2019
@@ -19,16 +19,13 @@ header block) which dominates all other
Note that there are some important implications of this definition:
* Not all cycles are loops. There exist cycles that do not meet the
- dominance requirement and such are not considered loops. LoopInfo
- does not include such cycles.
+ dominance requirement and such are not considered loops.
* Loops can contain non-loop cycles and non-loop cycles may contain
loops. Loops may also contain sub-loops.
* Given the use of dominance in the definition, all loops are
- statically reachable from the entry of the function. Loops which
- become statically unreachable during optimization *must* be removed
- from LoopInfo.
+ statically reachable from the entry of the function.
* Every loop must have a header block, and some set of predecessors
outside the loop. A loop is allowed to be statically infinite, so
@@ -96,7 +93,41 @@ of overflow when converting one to the o
It's important to note that the same basic block can play multiple
roles in the same loop, or in different loops at once. For example, a
single block can be the header for two nested loops at once, while
-also being an exit block for a sibling loop.
+also being an exiting block for the inner one only, and an exit block
+for a sibling loop. Example:
+
+.. code-block:: C
+
+ while (..) {
+ for (..) {}
+ do {
+ do {
+ // <-- block of interest
+ if (exit) break;
+ } while (..);
+ } while (..)
+ }
+
+LoopInfo
+========
+
+LoopInfo is the core analysis for obtaining information about loops.
+There are few key implications of the definitions given above which
+are important for working successfully with this interface.
+
+* LoopInfo does not contain information about non-loop cycles. As a
+ result, it is not suitable for any algorithm which requires complete
+ cycle detection for correctness.
+
+* LoopInfo provides an interface for enumerating all top level loops
+ (e.g. those not contained in any other loop). From there, you may
+ walk the tree of sub-loops rooted in that top level loop.
+
+* Loops which become statically unreachable during optimization *must*
+ be removed from LoopInfo. If this can not be done for some reason,
+ then the optimization is *required* to preserve the static
+ reachability of the loop.
+
Loop Simplify Form
==================
More information about the llvm-commits
mailing list