This is an archive of the discontinued LLVM Phabricator instance.

[docs] Update llvm.loop metadata documentation.
ClosedPublic

Authored by Meinersbur on Dec 4 2018, 12:24 PM.

Details

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.

Diff Detail

Event Timeline

Meinersbur created this revision.Dec 4 2018, 12:24 PM
hfinkel added inline comments.Dec 4 2018, 12:33 PM
docs/LangRef.rst
5100 ↗(On Diff #176690)

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

5103 ↗(On Diff #176690)

It is -> They are

5103 ↗(On Diff #176690)

identifiers -> unique loop identifiers

5104 ↗(On Diff #176690)

nor -> nor necessarily

Meinersbur marked an inline comment as done.Dec 4 2018, 12:44 PM
Meinersbur added inline comments.
docs/LangRef.rst
5100 ↗(On Diff #176690)

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.

hfinkel added inline comments.Dec 4 2018, 1:17 PM
docs/LangRef.rst
5100 ↗(On Diff #176690)

Then why add it to the example?

I'd say:

Also, the 'distinct' keyword for loop-metadata nodes is no longer necessary.
Meinersbur updated this revision to Diff 176737.Dec 4 2018, 4:54 PM
Meinersbur updated this revision to Diff 176739.Dec 4 2018, 4:57 PM
Meinersbur marked 4 inline comments as done.
  • Move 'necessarily'
Meinersbur marked 2 inline comments as done.Dec 4 2018, 4:58 PM
Meinersbur added inline comments.
docs/LangRef.rst
5100 ↗(On Diff #176690)

Then why add it to the example?

The idea was, because clang currently generates it.

hfinkel added inline comments.Dec 5 2018, 9:59 AM
docs/LangRef.rst
5088 ↗(On Diff #176739)

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

Meinersbur updated this revision to Diff 177333.Dec 7 2018, 2:59 PM
Meinersbur marked an inline comment as done.
  • Add doc about DILocation nodes in LoopIDs
Herald added a project: Restricted Project. · View Herald TranscriptMar 11 2019, 2:24 PM
hfinkel added inline comments.Apr 16 2019, 3:22 PM
docs/LangRef.rst
5099 ↗(On Diff #177333)

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

5103 ↗(On Diff #177333)

can have up to

5103 ↗(On Diff #177333)

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 ↗(On Diff #177333)

as unique identifiers

5109 ↗(On Diff #177333)

through transformations

Meinersbur marked 6 inline comments as done.
Meinersbur added inline comments.Jun 6 2019, 11:59 AM
docs/LangRef.rst
5108 ↗(On Diff #177333)

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

hfinkel accepted this revision.Jul 14 2020, 8:44 AM

LGTM

docs/LangRef.rst
5086 ↗(On Diff #203411)

For example, (add comma).

This revision is now accepted and ready to land.Jul 14 2020, 8:44 AM
This revision was automatically updated to reflect the committed changes.