CycleInfo: Introduce cycles as a generalization of loops

LLVM loops cannot represent irreducible structures in the CFG. This
change introduce the concept of cycles as a generalization of loops,
along with a CycleInfo analysis that discovers a nested
hierarchy of such cycles. This is based on Havlak (1997), Nesting of
Reducible and Irreducible Loops.

The cycle analysis is implemented as a generic template and then
instatiated for LLVM IR and Machine IR. The template relies on a new
GenericSSAContext template which must be specialized when used for
each IR.

This review is a restart of an older review request:
https://reviews.llvm.org/D83094

Original implementation by Nicolai Hähnle <[email protected]>,
with recent refactoring by Sameer Sahasrabuddhe <[email protected]>

Differential Revision: https://reviews.llvm.org/D112696

Author: ssahasra

llvm/docs/CycleTerminology.rst

@@ -0,0 +1,228 @@
+.. _cycle-terminology:
+
+======================
+LLVM Cycle Terminology
+======================
+
+.. contents::
+   :local:
+
+Cycles
+======
+
+Cycles are a generalization of LLVM :ref:`loops <loop-terminology>`,
+defined recursively as follows [HavlakCycles]_:
+
+1. In a directed graph G, an *outermost cycle* is a maximal strongly
+   connected region with at least one internal edge. (Informational
+   note --- The requirement for at least one internal edge ensures
+   that a single basic block is a cycle only if there is an edge that
+   goes back to the same basic block.)
+2. A basic block in the cycle that can be reached from the entry of
+   the function along a path that does not visit any other basic block
+   in the cycle is called an *entry* of the cycle. A cycle can have
+   multiple entries.
+3. In any depth-first search starting from the entry of the function,
+   the first node of a cycle to be visited will be one of the entries.
+   This entry is called the *header* of the cycle. (Informational note
+   --- Thus, the header of the cycle is implementation-defined.)
+4. In any depth-first search starting from the entry, set of outermost
+   cycles found in the CFG is the same. These are the *top-level
+   cycles* that do not themselves have a parent.
+5. The cycles nested inside a cycle C with header H are the outermost
+   cycles in the subgraph induced on the set of nodes (C - H). C is
+   said to be the *parent* of these cycles, and each of these cycles
+   is a *child* of C.
+
+Thus, cycles form an implementation-defined forest where each cycle C is
+the parent of any outermost cycles nested inside C. The tree closely
+follows the nesting of loops in the same function. The unique entry of
+a reducible cycle (an LLVM loop) L dominates all its other nodes, and
+is always chosen as the header of some cycle C regardless of the DFS
+tree used. This cycle C is a superset of the loop L. For an
+irreducible cycle, no one entry dominates the nodes of the cycle. One
+of the entries is chosen as header of the cycle, in an
+implementation-defined way.
+
+.. _cycle-irreducible:
+
+A cycle is *irreducible* if it has multiple entries and it is
+*reducible* otherwise.
+
+.. _cycle-parent-block:
+
+A cycle C is said to be the *parent* of a basic block B if B occurs in
+C but not in any child cycle of C. Then B is also said to be a *child*
+of cycle C.
+
+.. _cycle-sibling:
+
+A basic block or cycle X is a *sibling* of another basic block or
+cycle Y if they both have no parent or both have the same parent.
+
+Informational notes:
+
+- Non-header entry blocks of a cycle can be contained in child cycles.
+- If the CFG is reducible, the cycles are exactly the natural loops and
+  every cycle has exactly one entry block.
+- Cycles are well-nested (by definition).
+- The entry blocks of a cycle are siblings in the dominator tree.
+
+.. [HavlakCycles] Paul Havlak, "Nesting of reducible and irreducible
+                  loops." ACM Transactions on Programming Languages
+                  and Systems (TOPLAS) 19.4 (1997): 557-567.
+
+.. _cycle-examples:
+
+Examples of Cycles
+==================
+
+Irreducible cycle enclosing natural loops
+-----------------------------------------
+
+.. Graphviz source; the indented blocks below form a comment.
+
+  ///     |   |
+  ///   />A] [B<\
+  ///   |  \ /  |
+  ///   ^---C---^
+  ///       |
+
+  strict digraph {
+    { rank=same; A B}
+    Entry -> A
+    Entry -> B
+    A -> A
+    A -> C
+    B -> B
+    B -> C
+    C -> A
+    C -> B
+    C -> Exit
+  }
+
+.. image:: cycle-1.png
+
+The self-loops of ``A`` and ``B`` give rise to two single-block
+natural loops. A possible hierarchy of cycles is::
+
+    cycle: {A, B, C} entries: {A, B} header: A
+    - cycle: {B, C}  entries: {B, C} header: C
+      - cycle: {B}   entries: {B}    header: B
+
+This hierarchy arises when DFS visits the blocks in the order ``A``,
+``C``, ``B`` (in preorder).
+
+Irreducible union of two natural loops
+--------------------------------------
+
+.. Graphviz source; the indented blocks below form a comment.
+
+  ///     |   |
+  ///     A<->B
+  ///     ^   ^
+  ///     |   |
+  ///     v   v
+  ///     C   D
+  ///     |   |
+
+  strict digraph {
+    { rank=same; A B}
+    { rank=same; C D}
+    Entry -> A
+    Entry -> B
+    A -> B
+    B -> A
+    A -> C
+    C -> A
+    B -> D
+    D -> B
+    C -> Exit
+    D -> Exit
+  }
+
+.. image:: cycle-2.png
+
+There are two natural loops: ``{A, C}`` and ``{B, D}``. A possible
+hierarchy of cycles is::
+
+    cycle: {A, B, C, D} entries: {A, B} header: A
+    - cycle: {B, D}     entries: {B}    header: B
+
+Irreducible cycle without natural loops
+---------------------------------------
+
+.. Graphviz source; the indented blocks below form a comment.
+
+  ///     |   |
+  ///   />A   B<\
+  ///   | |\ /| |
+  ///   | | x | |
+  ///   | |/ \| |
+  ///   ^-C   D-^
+  ///     |   |
+  ///
+
+  strict digraph {
+    { rank=same; A B}
+    { rank=same; C D}
+    Entry -> A
+    Entry -> B
+    A -> C
+    A -> D
+    B -> C
+    B -> D
+    C -> A
+    D -> B
+    C -> Exit
+    D -> Exit
+  }
+
+.. image:: cycle-3.png
+
+This graph does not contain any natural loops --- the nodes ``A``,
+``B``, ``C`` and ``D`` are siblings in the dominator tree. A possible
+hierarchy of cycles is::
+
+    cycle: {A, B, C, D} entries: {A, B} header: A
+    - cycle: {B, D}     entries: {B, D} header: D
+
+.. _cycle-closed-path:
+
+Closed Paths and Cycles
+=======================
+
+A *closed path* in a CFG is a connected sequence of nodes and edges in
+the CFG whose start and end points are the same.
+
+1. If a node D dominates one or more nodes in a closed path P and P
+   does not contain D, then D dominates every node in P.
+
+   **Proof:** Let U be a node in P that is dominated by D. If there
+   was a node V in P not dominated by D, then U would be reachable
+   from the function entry node via V without passing through D, which
+   contradicts the fact that D dominates U.
+
+2. If a node D dominates one or more nodes in a closed path P and P
+   does not contain D, then there exists a cycle C that contains P but
+   not D.
+
+   **Proof:** From the above property, D dominates all the nodes in P.
+   For any nesting of cycles discovered by the implementation-defined
+   DFS, consider the smallest cycle C which contains P. For the sake
+   of contradiction, assume that D is in C. Then the header H of C
+   cannot be in P, since the header of a cycle cannot be dominated by
+   any other node in the cycle. Thus, P is in the set (C-H), and there
+   must be a smaller cycle C' in C which also contains P, but that
+   contradicts how we chose C.
+
+3. If a closed path P contains nodes U1 and U2 but not their
+   dominators D1 and D2 respectively, then there exists a cycle C that
+   contains U1 and U2 but neither of D1 and D2.
+
+   **Proof:** From the above properties, each D1 and D2 separately
+   dominate every node in P. There exists a cycle C1 (respectively,
+   C2) that contains P but not D1 (respectively, D2). Either C1 and C2
+   are the same cycle, or one of them is nested inside the other.
+   Hence there is always a cycle that contains U1 and U2 but neither
+   of D1 and D2.

llvm/docs/UserGuides.rst

@@ -27,6 +27,7 @@ intermediate LLVM representation.
    CommandLine
    CompileCudaWithLLVM
    CoverageMappingFormat
+   CycleTerminology
    DebuggingJITedCode
    Docker
    ExtendingLLVM
@@ -137,6 +138,9 @@ Optimizations
 :doc:`LoopTerminology`
   A document describing Loops and associated terms as used in LLVM.
 
+:doc:`CycleTerminology`
+  A document describing cycles as a generalization of loops.
+
 :doc:`Vectorizers`
    This document describes the current status of vectorization in LLVM.