[llvm] LangRef: mention that willreturn can cause time-traveling UB (PR #214229)

[Ralf Jung via llvm-commits]

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

>From 28035ae7cfbfa7b407ecefe44ddb87b8a323588d Mon Sep 17 00:00:00 2001
From: Ralf Jung <post at ralfj.de>
Date: Wed, 5 Aug 2026 15:10:12 +0200
Subject: [PATCH] LangRef: mention that willreturn can cause time-traveling UB

---
 llvm/docs/LangRef.md            | 2 ++
 llvm/docs/UndefinedBehavior.rst | 6 +++++-
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/llvm/docs/LangRef.md b/llvm/docs/LangRef.md
index 6a3194271b838..6e89cc937543d 100644
--- a/llvm/docs/LangRef.md
+++ b/llvm/docs/LangRef.md
@@ -2495,6 +2495,8 @@ fn -> other_fn -> other_fn ; fn is norecurse
     Annotated functions may still raise an exception, i.a., `nounwind` is not implied.
     If an invocation of an annotated function does not return control back
     to a point in the call stack, the behavior is undefined.
+    If the annotated function has observable behavior (such as I/O or a volatile access),
+    note that the annotation can cause UB to time-travel around such behavior.
 
 `nosync`
 :   This function attribute indicates that the function does not introduce any
diff --git a/llvm/docs/UndefinedBehavior.rst b/llvm/docs/UndefinedBehavior.rst
index 2055244664511..2395a5a0f5ca3 100644
--- a/llvm/docs/UndefinedBehavior.rst
+++ b/llvm/docs/UndefinedBehavior.rst
@@ -83,7 +83,8 @@ most of the supported architectures.
 
 Time Travel
 -----------
-Immediate UB in LLVM IR allows the so-called time travelling. What this means
+When using the ``willreturn`` attribute,
+immediate UB in LLVM IR allows the so-called time travelling. What this means
 is that if a program triggers UB, then we are not required to preserve any of
 its observable behavior, including I/O.
 For example, the following function triggers UB after calling ``printf``:
@@ -105,6 +106,9 @@ optimize the function to simply:
       unreachable
     }
 
+Without ``willreturn``, UB in LLVM will never exhibit time-traveling. This means
+frontends can avoid time-traveling UB by only putting ``willreturn`` on
+functions without observable behavior.
 
 Deferred UB
 ===========