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

[Juneyoung Lee via Phabricator via llvm-commits]

aqjune updated this revision to Diff 337047.
aqjune added a comment.

Address comments, add a few examples


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D97924/new/

https://reviews.llvm.org/D97924

Files:
  llvm/docs/LangRef.rst


Index: llvm/docs/LangRef.rst
===================================================================
--- llvm/docs/LangRef.rst
+++ llvm/docs/LangRef.rst
@@ -1198,12 +1198,21 @@
     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.
+    A caller can pass two same pointers with one nocapture tagged and another
+    not tagged as arguments.
+
+.. code-block:: llvm
+
+    define void @f(i8* nocapture %a, i8* %b) {
+      ; (escape %b)
+    }
+
+    call void @f(i8* @glb, i8* @glb) ; well-defined
 
 ``nofree``
     This indicates that callee does not free the pointer argument. This is not
@@ -2648,6 +2657,49 @@
 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
+one or more of the following conditions hold:
+
+1. The call stores any bit of the pointer carrying information into a place
+that is readable by the caller or subsequent function calls, such as a global
+variable or the caller's register.
+
+.. code-block:: llvm
+
+    @glb  = global i8* null
+    @glb2 = global i32 0
+    define void @f(i8* %a) {
+      store i8* %a, i8** @glb ; escapes %a
+
+      %i = ptrtoint i8* %a to i64
+      %j = trunc i64 %i to i32
+      store i32 %j, i32* @glb ; escapes %a
+    }
+
+2. The call's behavior depends on any bit of the pointer carrying information.
+
+.. code-block:: llvm
+
+    @glb  = global i8 0
+    define void @f(i8* %a) {
+      %c = icmp eq i8* %a, @glb
+      br i1 %c, BB_EXIT, BB_CONTINUE ; escapes %a
+    BB_EXIT:
+      call void exit()
+      unreachable
+    BB_CONTINUE:
+      ret void
+    }
+
+Addresses used in volatile operations are considered to be captured.
+
+
 .. _volatile:
 
 Volatile Memory Accesses


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