maxjhandsome
/
llvm-project
forked from OSchip/llvm-project
1
0
Fork 0
Code Issues Pull Requests Packages Releases Wiki Activity

[docs] Update llvm.loop metadata documentation. 

Loop metadata nodes do not adhere to the documented property:

(a) LoopIDs are not unique: Any pass that duplicates IR will do it
    including its metadata (e.g. LoopVersioning) such that multiple
    loops are linked with the same LoopID. There is even a test case
    (Transforms/LoopUnroll/unroll-pragmas-disabled.ll) for multiple
    loops with the same LoopID.

(b) LoopIDs are not persistent: Adding or removing an item from a LoopID
    can only be done by creating a new MDNode and assigning it to the
    loop's branch(es). Passes such as LoopUnroll (llvm.loop.unroll.disable)
    and LoopVectorize (llvm.loop.isvectorized) use this to mark loops to
    not be transformed multiple times or to avoid that a LoopVersioned
    original loop is transformed.

Update the documentation according to how llvm.loop is used in practice.

Differential Revision: https://reviews.llvm.org/D55290
This commit is contained in:
Michael Kruse 2020-07-14 10:58:49 -05:00
parent 2c2a297bb6
commit 322e7cfab5
1 changed files with 23 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

45
llvm/docs/LangRef.rst
View File

@ -5718,33 +5718,34 @@ attribute on parameters and return values.
It is sometimes useful to attach information to loop constructs. Currently,
loop metadata is implemented as metadata attached to the branch instruction
in the loop latch block. This type of metadata refer to a metadata node that is
guaranteed to be separate for each loop. The loop identifier metadata is
specified with the name ``llvm.loop``.
The loop identifier metadata is implemented using a metadata that refers to
itself to avoid merging it with any other identifier metadata, e.g.,
during module linkage or function inlining. That is, each loop should refer
to their own identification metadata even if they reside in separate functions.
The following example contains loop identifier metadata for two separate loop
constructs:
.. code-block:: llvm
!0 = !{!0}
!1 = !{!1}
The loop identifier metadata can be used to specify additional
per-loop metadata. Any operands after the first operand can be treated
as user-defined metadata. For example the ``llvm.loop.unroll.count``
suggests an unroll factor to the loop unroller:
in the loop latch block. The loop metadata node is a list of
other metadata nodes, each representing a property of the loop. Usually,
the first item of the property node is a string. For example, the
``llvm.loop.unroll.count`` suggests an unroll factor to the loop
unroller:
.. code-block:: llvm
br i1 %exitcond, label %._crit_edge, label %.lr.ph, !llvm.loop !0
...
!0 = !{!0, !1}
!1 = !{!"llvm.loop.unroll.count", i32 4}
!0 = !{!0, !1, !2}
!1 = !{!"llvm.loop.unroll.enable"}
!2 = !{!"llvm.loop.unroll.count", i32 4}
For legacy reasons, the first item of a loop metadata node must be a
reference to itself. Before the advent of the 'distinct' keyword, this
forced the preservation of otherwise identical metadata nodes. Since
the loop-metadata node can be attached to multiple nodes, the 'distinct'
keyword has become unnecessary.
Prior to the property nodes, one or two ``DILocation`` (debug location)
nodes can be present in the list. The first, if present, identifies the
source-code location where the loop begins. The second, if present,
identifies the source-code location where the loop ends.
Loop metadata nodes cannot be used as unique identifiers. They are
neither persistent for the same loop through transformations nor
necessarily unique to just one loop.
'``llvm.loop.disable_nonforced``'
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^