[llvm] 1fd23a0 - [LangRef] Add elementtype attribute

[Nikita Popov via llvm-commits]

Author: Nikita Popov
Date: 2021-07-15T18:04:25+02:00
New Revision: 1fd23a065bf729836dd52ef1ad3c84c449735a56

URL: https://github.com/llvm/llvm-project/commit/1fd23a065bf729836dd52ef1ad3c84c449735a56
DIFF: https://github.com/llvm/llvm-project/commit/1fd23a065bf729836dd52ef1ad3c84c449735a56.diff

LOG: [LangRef] Add elementtype attribute

This adds an elementtype(<ty>) attribute, which can be used to
attach an element type to a pointer typed argument. It is similar
to byval/byref in purpose, but unlike those does not carry any
specific semantics by itself. However, certain intrinsics may
require it and interpret it in specific ways.

The in-tree use cases for this that I'm currently aware of are:

    call ptr @llvm.preserve.array.access.index.p0.p0(ptr elementtype(%ty) %base, i32 %dim, i32 %index)
    call ptr @llvm.preserve.struct.access.index.p0.p0(ptr elementtype(%ty) %base, i32 %gep_index, i32 %di_index)
    call token @llvm.experimental.gc.statepoint.p0(i64 0, i32 0, ptr elementtype(void ()) @foo, i32 0, i32 0, i32 0, i32 0, ptr addrspace(1) %obj)

Notably, the gc.statepoint case needs a function as element type,
in which case the workaround of adding a separate %ty undef
argument would not work, as arguments cannot be unsized.

Differential Revision: https://reviews.llvm.org/D105407

Added: 
    

Modified: 
    llvm/docs/LangRef.rst

Removed: 
    


################################################################################
diff  --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst
index 38248b454dd0..cb615ebae761 100644
--- a/llvm/docs/LangRef.rst
+++ b/llvm/docs/LangRef.rst
@@ -1183,6 +1183,22 @@ Currently, only the following parameter attributes are defined:
     The sret type argument specifies the in memory type, which must be
     the same as the pointee type of the argument.
 
+``elementtype(<ty>)``
+
+    The ``elementtype`` argument attribute can be used to specify a pointer
+    element type in a way that is compatible with `opaque pointers
+    <OpaquePointers.html>`.
+
+    The ``elementtype`` attribute by itself does not carry any specific
+    semantics. However, certain intrinsics may require this attribute to be
+    present and assign it particular semantics. This will be documented on
+    individual intrinsics.
+
+    The attribute may only be applied to pointer typed arguments of intrinsic
+    calls. It cannot be applied to non-intrinsic calls, and cannot be applied
+    to parameters on function declarations. For non-opaque pointers, the type
+    passed to ``elementtype`` must match the pointer element type.
+
 .. _attr_align:
 
 ``align <n>`` or ``align(<n>)``