[llvm] [IR] LangRef: document behavior of double-lifetime.start (PR #184296)

[Ralf Jung via llvm-commits]

https://github.com/RalfJung updated https://github.com/llvm/llvm-project/pull/184296

>From b5d103d23ed5ec220d544ae19815169acc1c2788 Mon Sep 17 00:00:00 2001
From: Ralf Jung <post at ralfj.de>
Date: Tue, 3 Mar 2026 08:43:53 +0100
Subject: [PATCH 1/2] [IR] LangRef: document behavior of double-lifetime.start

---
 llvm/docs/LangRef.rst | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst
index a1835436ae359..b4a10c0befaa9 100644
--- a/llvm/docs/LangRef.rst
+++ b/llvm/docs/LangRef.rst
@@ -27731,10 +27731,12 @@ If ``ptr`` is a ``poison`` value, the intrinsic has no effect.
 Otherwise, the stack-allocated object that ``ptr`` points to is initially
 marked as dead. After '``llvm.lifetime.start``', the stack object is marked as
 alive and has an uninitialized value.
-The stack object is marked as dead when either
+Calling ``llvm.lifetime.start`` when the stack object is already alive just
+resets its contents to be uninitialized.
+
+The stack object is marked as dead again 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

>From d771b3e95800371499c615351a7c453ad3acf6b4 Mon Sep 17 00:00:00 2001
From: Ralf Jung <post at ralfj.de>
Date: Tue, 3 Mar 2026 11:36:01 +0100
Subject: [PATCH 2/2] using the intrinsic on poison should be UB

---
 llvm/docs/LangRef.rst | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst
index b4a10c0befaa9..311e686e9773a 100644
--- a/llvm/docs/LangRef.rst
+++ b/llvm/docs/LangRef.rst
@@ -27721,12 +27721,12 @@ Arguments:
 """"""""""
 
 The argument is either a pointer to an ``alloca`` instruction or a ``poison``
-value.
+value. Otherwise, the IR is considered ill-formed.
 
 Semantics:
 """"""""""
 
-If ``ptr`` is a ``poison`` value, the intrinsic has no effect.
+If ``ptr`` is a ``poison`` value, the intrinsic has Undefined Behavior.
 
 Otherwise, the stack-allocated object that ``ptr`` points to is initially
 marked as dead. After '``llvm.lifetime.start``', the stack object is marked as
@@ -27764,12 +27764,12 @@ Arguments:
 """"""""""
 
 The argument is either a pointer to an ``alloca`` instruction or a ``poison``
-value.
+value. Otherwise, the IR is considered ill-formed.
 
 Semantics:
 """"""""""
 
-If ``ptr`` is a ``poison`` value, the intrinsic has no effect.
+If ``ptr`` is a ``poison`` value, the intrinsic has Undefined Behavior.
 
 Otherwise, the stack-allocated object that ``ptr`` points to becomes dead after
 the call to this intrinsic.