[docs] Update llvm.loop metadata documentation.

[Meinersbur]

Summary

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 be not 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.

[hfinkel]

docs/LangRef.rst

5100

Really? Why is it obsolete? (in any case, if that's true, it should be mentioned elsewhere in the LangRef).

5103

It is -> They are

5103

identifiers -> unique loop identifiers

5104

nor -> nor necessarily

[Meinersbur]

docs/LangRef.rst

5100

Obsolete only for use in llvm.loop metadata, not in general. How about this wording?

The 'distinct' keyword for loop metadata is also not necessary anymore.

[Meinersbur]

• Address @hfinkel's review

[hfinkel]

docs/LangRef.rst

5100

Then why add it to the example?

I'd say:

Also, the 'distinct' keyword for loop-metadata nodes is no longer necessary.

[Meinersbur]

• Address @hfinkel's review

[Meinersbur]

• Move 'necessarily'

[Meinersbur]

docs/LangRef.rst

5100

Then why add it to the example?

The idea was, because clang currently generates it.

[hfinkel]

docs/LangRef.rst

5088

While you're improving this, could you also add a note about the debug locations being, optionally, in the list?

[Meinersbur]

• Add doc about DILocation nodes in LoopIDs

[Meinersbur]

ping

[Meinersbur]

ping

[Meinersbur]

ping

[hfinkel]

docs/LangRef.rst

5099

Before the advent of the 'distinct' keyword, this forced the preservation of otherwise-identical metadata nodes.

5103

can have up to

5103

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.

5108

as unique identifiers

5109

through transformations

[Meinersbur]

• Address @hfinkel's remarks

[Meinersbur]

docs/LangRef.rst

5108

The 'unique' seem redundant to me, but ok.

[Meinersbur]

ping

[hfinkel]

LGTM

docs/LangRef.rst

5086

For example, (add comma).

docs/LangRef.rst

 is treated as a boolean value; if it exists, it signals that the branch
 or switch that it is attached to is completely unpredictable.
 
 '``llvm.loop``'
 ^^^^^^^^^^^^^^^
 
 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 an unordered 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 = distinct !{!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. It was used to avoid collapsing of multiple loop
+metadata nodes into one. The use of 'distinct' metadata nodes is also
+obsolete.
+
+Loop metadata nodes cannot be used as identifiers. It is
+neither persistent for the same loop through pass transformations nor
+unique to just one loop.
 
 '``llvm.loop.vectorize``' and '``llvm.loop.interleave``'
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Metadata prefixed with ``llvm.loop.vectorize`` or ``llvm.loop.interleave`` are
 used to control per-loop vectorization and interleaving parameters such as
 vectorization width and interleave count. These metadata should be used in
 conjunction with ``llvm.loop`` loop identification metadata. The
 ``llvm.loop.vectorize`` and ``llvm.loop.interleave`` metadata are only
 optimization hints and the optimizer will only interleave and vectorize loops if
 it believes it is safe to do so. The ``llvm.mem.parallel_loop_access`` metadata
 which contains information about loop-carried memory dependencies can be helpful