[LangRef] mention that the lifetime intrinsics' description in LangRef isn't everything

[aqjune]

Summary

This is a minor patch that addresses concerns about lifetime in D94002.

We need to mention that what's written in LangRef isn't everything about lifetime.start/end
and its semantics depends on the stack coloring algorithm's pattern matching of a stack pointer.

If the stack coloring algorithm cannot conclude that a pointer is a stack-allocated object, the pointer is conservatively
considered as a non-stack one because stack coloring won't take this lifetime into account while assigning addresses.

A reference from alloca to lifetime.start/end is added as well.

[RalfJung]

llvm/docs/LangRef.rst

18131

Would this alternatively be captured by saying that if ptr is a stack-allocated object, then it *might* have the effect of the original alloca creating a dead object and this intrinsic making it live (but non-deterministically, not doing this and just replacing the content by poison is also allowed)?

[aqjune]

llvm/docs/LangRef.rst

18131

It will help remove the mentioning of dependency on stack coloring's implementation, but due to practical reasons I think the current text is better.

It's because the current text reveals the problem of the status quo: alloca's lifetime depends on the stack coloring's implementation.
I think this mentioning will help people in the future raise questions about removal of this dependency, if lucky enough. Since this isn't a small problem, fully resolving this would require a dedicated team... I don't know.

Also, personally I prefer being simple here; nondeterminism is a hard concept and there's an opportunity that it can be interpreted differently by readers.

[RalfJung]

llvm/docs/LangRef.rst

18131

As you wish. But then I'd probably weaken the statement earlier in this text where it says that

If ``ptr`` is a stack-allocated object and it points to the first byte of
the object, the object is initially marked as dead.
After '``llvm.lifetime.start``', the stack object that ``ptr`` points is marked
as alive and has an uninitialized value.

Currently, this statement is first made only to be later partially revised; that seems confusing.

[aqjune]

Forward-declare the dependency on the stack coloring algorithm

[aqjune]

Reduce diff

[aqjune]

llvm/docs/LangRef.rst

18131

To minimize touching existing text, I moved it just after the sentence.

[RalfJung]

LGTM, thanks. :)

llvm/docs/LangRef.rst

 space for the allocation.'``alloca``'d memory is automatically released
 when the function returns. The '``alloca``' instruction is commonly used
 to represent automatic variables that must have an address available. When
 the function returns (either with the ``ret`` or ``resume`` instructions),
 the memory is reclaimed. Allocating zero bytes is legal, but the returned
 pointer may not be unique. The order in which memory is allocated (ie.,
 which way the stack grows) is not specified.
 
+If the returned pointer is used by :ref:`llvm.lifetime.start <int_lifestart>`,
+the returned object is initially dead.
+See :ref:`llvm.lifetime.start <int_lifestart>` and
+:ref:`llvm.lifetime.end <int_lifeend>` for the precise semantics of
+lifetime-manipulating intrinsics.
+
 Example:
 """"""""
 
 .. code-block:: llvm
 
       %ptr = alloca i32                             ; yields i32*:ptr
       %ptr = alloca i32, i32 4                      ; yields i32*:ptr
       %ptr = alloca i32, i32 4, align 1024          ; yields i32*:ptr

 object, or -1 if it is variable sized. The second argument is a pointer
 to the object.
 
 Semantics:
 """"""""""
 
 If ``ptr`` is a stack-allocated object and it points to the first byte of
 the object, the object is initially marked as dead.
+``ptr`` is conservatively considered as a non-stack-allocated object if
+the stack coloring algorithm that is used in the optimization pipeline cannot
+conclude that ``ptr`` is a stack-allocated object.
+
 After '``llvm.lifetime.start``', the stack object that ``ptr`` points is marked
 as alive and has an uninitialized value.
 The stack object is marked as dead when either
 :ref:`llvm.lifetime.end <int_lifeend>` to the alloca is executed or the
 function returns.
 
 After :ref:`llvm.lifetime.end <int_lifeend>` is called,
 '``llvm.lifetime.start``' on the stack object can be called again.
 The second '``llvm.lifetime.start``' call marks the object as alive, but it
 does not change the address of the object.
 
 If ``ptr`` is a non-stack-allocated object, it does not point to the first
 byte of the object or it is a stack object that is already alive, it simply
 fills all bytes of the object with ``poison``.
 
 
 .. _int_lifeend:
 
 '``llvm.lifetime.end``' Intrinsic
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Syntax:
 """""""
 
 ::
 
       declare void @llvm.lifetime.end(i64 <size>, i8* nocapture <ptr>)
 

 object, or -1 if it is variable sized. The second argument is a pointer
 to the object.
 
 Semantics:
 """"""""""
 
 If ``ptr`` is a stack-allocated object and it points to the first byte of the
 object, the object is dead.
+``ptr`` is conservatively considered as a non-stack-allocated object if
+the stack coloring algorithm that is used in the optimization pipeline cannot
+conclude that ``ptr`` is a stack-allocated object.
+
 Calling ``llvm.lifetime.end`` on an already dead alloca is no-op.
 
 If ``ptr`` is a non-stack-allocated object or it does not point to the first
 byte of the object, it is equivalent to simply filling all bytes of the object
 with ``poison``.
 
 
 '``llvm.invariant.start``' Intrinsic