Update langref to indicate that calls may be convergent.

[jlebar]

Summary

As previously written, only functions could be convergent. But calls
need to have a notion of convergence as well.

To see why this is important, consider an indirect call. We may or may
not want to disable optimizations around it and behave as though we're
calling a convergent function -- it depends on the semantics of the
language we're compiling. Thus the need for this attr on the call.

[mehdi_amini]

What happens on inline?

[jlebar]

In D17314#354379, @joker.eph wrote:

What happens on inline?

We can clarify this if you want (there are no restrictions on inlining a call to a convergent function), but inasmuch as it's unclear, I think it may speak to a larger problem with the way we're describing this, and I'm afraid that calling out inlining specifically may just paper over the issue. For example, what about outlining? Someone more familiar with LLVM than I can probably come up with other edge cases.

The most concrete way I have to explain this is something like:

There are certain instructions, e.g. llvm.cuda.syncthreads(), that must never be made control-flow dependent on additional values. This applies transitively through function calls (so long as they are marked convergent). That is, if a call is convergent, then we must behave as though the call will trigger a convergent instruction (unless we can prove otherwise), and therefore we can't make the call control-flow dependent on additional values, because that would make our putative convergent instruction control-flow dependent on additional values.

I think this makes it relatively clear that inlining/outlining is OK -- the issue is just that you can't put additional control-dependencies in the way of an eventual call to syncthreads. This is also how I'd explain this notion of convergence to someone IRL.

As I see it, the problem as currently written is that we make no distinction between different "types" of convergent functions. But we can remove "convergent" from any function which doesn't invoke any convergent functions...so is it turtles all the way down? Like, if you can see the full program source, can you just drop "convergent" everywhere? Clearly not, because there are leaves: these special instructions such as syncthreads. If it weren't for these leaves, we really *could* drop convergent everywhere, in the presence of full source.

In the spec we treat these special instructions the same as functions that you can't see the source of, and I grant that they behave the same, from the perspective of the compiler. But to at least one human, they're not at all the same. If we could agree on clarifying that, I think we might make this whole thing a lot better.

But if we can't, I'll just add a note about inlining. :)

[mehdi_amini]

I think the last paragraph may be enough to me. Please see the two nits.

docs/LangRef.rst

1252 ↗

(On Diff #48128)

"When the appears" does not seem right to me. "When it appears"?

1260 ↗

(On Diff #48128)

"does not run" sounds odd, what about "can call" instead?

[jlebar]

Thank you for the review. :)

llvm/trunk/docs/LangRef.rst

 ``cold``
     This attribute indicates that this function is rarely called. When
     computing edge weights, basic blocks post-dominated by a cold
     function call are also considered to be cold; and, thus, given low
     weight.
 ``convergent``
     In some parallel execution models, there exist operations that cannot be
     made control-dependent on any additional values.  We call such operations
-    ``convergent``, and mark them with this function attribute.
+    ``convergent``, and mark them with this attribute.
 
+    The ``convergent`` attribute may appear on functions or call/invoke
+    instructions.  When it appears on a function, it indicates that calls to
+    this function should not be made control-dependent on additional values.
     For example, the intrinsic ``llvm.cuda.syncthreads`` is ``convergent``, so
     calls to this intrinsic cannot be made control-dependent on additional
-    values.  Other functions may also be marked as convergent; this prevents
-    the same optimization on those functions.
+    values.
 
-    The optimizer may remove the ``convergent`` attribute when it can prove
-    that the function does not execute any convergent operations.
+    When it appears on a call/invoke, the ``convergent`` attribute indicates
+    that we should treat the call as though we're calling a convergent
+    function.  This is particularly useful on indirect calls; without this we
+    may treat such calls as though the target is non-convergent.
+
+    The optimizer may remove the ``convergent`` attribute on functions when it
+    can prove that the function does not execute any convergent operations.
+    Similarly, the optimizer may remove ``convergent`` on calls/invokes when it
+    can prove that the call/invoke cannot call a convergent function.
 ``inaccessiblememonly``
     This attribute indicates that the function may only access memory that
     is not accessible by the module being compiled. This is a weaker form
     of ``readnone``.
 ``inaccessiblemem_or_argmemonly``
     This attribute indicates that the function may only access memory that is
     either not accessible by the module being compiled, or is pointed to
     by its pointer arguments. This is a weaker form of  ``argmemonly``