[LangRef] Add memory attribute

[nikic]

Summary

This adds the LangRef wording for the memory attribute proposed at https://discourse.llvm.org/t/rfc-unify-memory-effect-attributes/65579.

The old attributes are not removed from LangRef until the migration is finished.

[nhaehnle]

I'm pretty happy with the proposed spelling.

llvm/docs/LangRef.rst

1733–1735

Since this is a new kind of "composite" attribute, it should be clearly stated:

• What the memory effects are if the attribute is missing entirely (presumably: all memory effects are possible, unless one of the legacy attributes is present)
• How attributes compose if you have one on the call instruction *and* on the callee (presumably: the possible memory effects are the *intersection* of memory effects given by the different attributes)

1748

*additionally

[nikic]

Mention default (all effects) and how effects for a call are derived from call-site and function attributes.

[jdoerfert]

Do we need two spelling "`memory() or memory(none)`:"?

We should talk about call sites not calls, as we refer to them as "call site attributes".

llvm/docs/LangRef.rst

1750

There is no explicit "other" example, if we introduce the keyword we should use it. If we don't introduce the keyword we should not specify it as `other` but rather spell out non specified location kind means all non-specified locations kinds.

1772

intersection ... union ... does at best read confusing. Either we need to "union" both sides first or we just don't talk about that and simply write:

The memory effects of a call is the intersection of the call-site
   ``memory`` attribute with the function ``memory`` attribute and any effects implied by operand bundles.

[nikic]

In D135597#3852809, @jdoerfert wrote:

Do we need two spelling "memory() or memory(none):"?

Nope. I'll drop the memory() spelling.

llvm/docs/LangRef.rst

1772

What I mainly wanted to highly here is that the result is CallSiteEffects & (FuncEffects | BundleEffects), rather than other combinations, such as (CallSiteEffects & FuncEffects) | BundleEffects.

Maybe I should just write that out in code form, rather than make people try to parse English?

[nikic]

Drop memory() spelling, add other example, use code to explain intersection behavior.

[jdoerfert]

llvm/docs/LangRef.rst

1767

I'm still not super happy with this scheme. other is all the location kinds we do not explicitly enumerate at at the current time, which is subject to change. At the same time we have an implicit "default" location kind which we don't even list in the "possible memory location kinds" above. So, we have two ways to refer to things not specified explicitly and they mean different things, that's confusing. Long story short, do we really need other?

1772

Maybe still add a sentence:
Thus, the call site annotations take precedence over the potential effects described by either the function annotation or the operand bundles.

[nikic]

Remove other location kind, only allow specifying it via the default.

[nikic]

llvm/docs/LangRef.rst

1767

Okay, I went ahead and dropped other. I don't really see a use for it, and I agree that having both other and the default is somewhat confusing.

[xbolva00]

Just FYI,

https://github.com/llvm/llvm-project/issues/54312 :

I would recommend not to add size to the existing ones but instead replace them as whole. That said, mapping all but the size argument to existing ones would be great and pretty straight forward (IMHO).

What do you think, should 'memory' attribute take arg-index and size-index into account to support use cases like access attribute in C?

[nikic]

In D135597#3858550, @xbolva00 wrote:

Just FYI,

https://github.com/llvm/llvm-project/issues/54312 :

I would recommend not to add size to the existing ones but instead replace them as whole. That said, mapping all but the size argument to existing ones would be great and pretty straight forward (IMHO).

What do you think, should 'memory' attribute take arg-index and size-index into account to support use cases like access attribute in C?

I don't think so. The memory attribute describes the memory effects of the whole call/function. We have separate attributes that apply to individual arguments.

[jdoerfert]

I like the wording now, thanks for the changes. Others should approve as well though.

In D135597#3858610, @nikic wrote:

In D135597#3858550, @xbolva00 wrote:

Just FYI,

https://github.com/llvm/llvm-project/issues/54312 :

I would recommend not to add size to the existing ones but instead replace them as whole. That said, mapping all but the size argument to existing ones would be great and pretty straight forward (IMHO).

What do you think, should 'memory' attribute take arg-index and size-index into account to support use cases like access attribute in C?

I don't think so. The memory attribute describes the memory effects of the whole call/function. We have separate attributes that apply to individual arguments.

I agree. Argument access information should be attached to the arguments.
So __attribute__ ((access (read_only, 2, 3))) void* memcpy (void*, const void*, size_t); would become

declare i8* memcpy(i8* access(write[0:arg(2)]) %dst, i8* access(read[0:arg(2)]) %src, i32 %size) memory(argmem: readwrite)

And we should do this after.

[nhaehnle]

LGTM

llvm/docs/LangRef.rst

 ``jumptable``
     This attribute indicates that the function should be added to a
     jump-instruction table at code-generation time, and that all address-taken
     references to this function should be replaced with a reference to the
     appropriate jump-instruction-table function pointer. Note that this creates
     a new pointer for the original function, which means that code that depends
     on function-pointer identity can break. So, any function annotated with
     ``jumptable`` must also be ``unnamed_addr``.
+``memory(...)``
+    This attribute specifies the possible memory effects of the call-site or
+    function. It allows specifying the possible access kinds (``none``,
+    ``read``, ``write``, or ``readwrite``) for the possible memory location
+    kinds (``argmem``, ``inaccessiblemem``, as well as a default). It is best
+    understood by example:
+
+    - ``memory(none)``: Does not access any memory.
+    - ``memory(read)``: May read (but not write) any memory.
+    - ``memory(write)``: May write (but not read) any memory.
+    - ``memory(readwrite)``: May read or write any memory.
+    - ``memory(argmem: read)``: May only read argument memory.
+    - ``memory(argmem: read, inaccessiblemem: write)``: May only read argument
+      memory and only write inaccessible memory.
+    - ``memory(read, argmem: readwrite)``: May read any memory (default mode)
+      and additionally write argument memory.
+    - ``memory(readwrite, argmem: none)``: May access any memory apart from
+      argument memory.
+
+    The supported memory location kinds are:
+
+    - ``argmem``: This refers to accesses that are based on pointer arguments
+      to the function.
+    - ``inaccessiblemem``: This refers to accesses to memory which is not
+      accessible by the current module (before return from the function -- an
+      allocator function may return newly accessible memory while only
+      accessing inaccessible memory itself). Inaccessible memory is often used
+      to model control dependencies of intrinsics.
+    - The default access kind (specified without a location prefix) applies to
+      all locations that haven't been specified explicitly, including those that
+      don't currently have a dedicated location kind (e.g. accesses to globals
+      or captured pointers).
+
+    If the ``memory`` attribute is not specified, then ``memory(readwrite)``
+    is implied (all memory effects are possible).
+
+    The memory effects of a call can be computed as
+    ``CallSiteEffects & (FunctionEffects | OperandBundleEffects)``. Thus, the
+    call-site annotation takes precedence over the potential effects described
+    by either the function annotation or the operand bundles.
 ``minsize``
     This attribute suggests that optimization passes and code generator
     passes make choices that keep the code size of this function as small
     as possible and perform optimizations that may sacrifice runtime
     performance in order to minimize the size of the generated code.
 ``naked``
     This attribute disables prologue / epilogue emission for the
     function. This can have very system-specific consequences.