[PATCH] D97924: [LangRef] clarify the semantics of nocapture

[Juneyoung Lee via Phabricator via llvm-commits]

aqjune created this revision.
aqjune added reviewers: jdoerfert, nlopes, nikic, reames.
aqjune requested review of this revision.
Herald added a project: LLVM.
Herald added a subscriber: llvm-commits.

This patch clarifies the semantics of nocapture attribute, especially regarding its behavior w.r.t integral representation of the pointer.

A 'Pointer Escape' subsection is added to describe the semantics of pointer escape first.

For the nocapture example with two same pointer arguments, it is consistent with the semantics that Alive2 used to run lit tests.

Please feel free to comment questions, uncertainties or known mismatches with the actual LLVM implementation.


Repository:
  rG LLVM Github Monorepo

https://reviews.llvm.org/D97924

Files:
  llvm/docs/LangRef.rst


Index: llvm/docs/LangRef.rst
===================================================================
--- llvm/docs/LangRef.rst
+++ llvm/docs/LangRef.rst
@@ -1195,12 +1195,12 @@
     function, returning a pointer to allocated storage disjoint from the
     storage for any other object accessible to the caller.
 
+.. _nocapture:
+
 ``nocapture``
-    This indicates that the callee does not make any copies of the
-    pointer that outlive the callee itself in any form such as a pointer stored
-    in the memory or as a return value. This is not a valid
-    attribute for return values.  Addresses used in volatile operations
-    are considered to be captured.
+    This indicates that the callee does not :ref:`capture <pointerescape>` the
+    pointer. This is not a valid attribute for return values.  Addresses used
+    in volatile operations are considered to be captured.
 
 ``nofree``
     This indicates that callee does not free the pointer argument. This is not
@@ -2627,6 +2627,39 @@
 which specialized optimization passes may use to implement type-based
 alias analysis.
 
+.. _pointerescape:
+
+Pointer Escape
+--------------
+
+Given a function call and a pointer that is passed as an argument or stored in
+the memory before the call, a pointer is *escaped* or *captured* by the call if
+it stores the pointer into a place that did not contain the pointer value
+before and the place is readable by the caller or subsequent function calls,
+such as in a global variable and caller's register.
+If the pointer isn't a :ref:`non-integral pointer <nointptrtype>`, it is escaped
+if assigning different integral addresses to the pointer causes changes in the
+memory and registers' values.
+
+A stack/heap allocation whose pointer is never stored to the memory or passed
+as an argument to a function call is never escaped.
+A pointer that is passed as a :ref:`nocapture <nocapture>` argument isn't
+escaped by the function call.
+
+If a pointer is tagged as 'nocapture', the pointer is escaped if the memory and
+register after the call contains the pointer value with the 'nocapture' tag.
+This means that a caller can pass two same pointers with one nocapture tagged
+and another not tagged as arguments, and callee can escape the untagged
+pointer.
+
+.. code-block:: llvm
+    define void @f(i8* %a, i8* %b) {
+      ; (escape %b)
+    }
+
+    call void @f(i8* nocapture @glb, i8* @glb) ; well-defined
+
+
 .. _volatile:
 
 Volatile Memory Accesses


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D97924.328077.patch
Type: text/x-patch
Size: 2467 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20210304/e52d7389/attachment.bin>