[LangRef] Add some documentation for ABI / call-site attributes

[nikic]

Explicitly mention that attributes can be applied to call-sites, and explain that ABI attributes between the call-site and called function should match.

Companion lint change: #121929

Inspired by: https://discourse.llvm.org/t/difference-between-call-site-attributes-and-declaration-attributes/83902

[llvmbot]

@llvm/pr-subscribers-llvm-ir

Author: Nikita Popov (nikic)

Changes

Explicitly mention that attributes can be applied to call-sites, and explain that ABI attributes between the call-site and called function should match.

Companion lint change: #121929

Inspired by: https://discourse.llvm.org/t/difference-between-call-site-attributes-and-declaration-attributes/83902

---

Full diff: https://github.com/llvm/llvm-project/pull/121930.diff

1 Files Affected:

• (modified) llvm/docs/LangRef.rst (+19-1)

diff --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst
index 7e01331b20c570..64a91c6515ae78 100644
--- a/llvm/docs/LangRef.rst
+++ b/llvm/docs/LangRef.rst
@@ -1160,7 +1160,8 @@ The return type and each parameter of a function type may have a set of
 used to communicate additional information about the result or
 parameters of a function. Parameter attributes are considered to be part
 of the function, not of the function type, so functions with different
-parameter attributes can have the same function type.
+parameter attributes can have the same function type. Parameter attributes can
+be placed both on function declarations/definitions, and at call-sites.
 
 Parameter attributes are either simple keywords or strings that follow the
 specified type. Multiple parameter attributes, when required, are separated by
@@ -1168,14 +1169,31 @@ spaces. For example:
 
 .. code-block:: llvm
 
+    ; On function declarations/definitions:
     declare i32 @printf(ptr noalias nocapture, ...)
     declare i32 @atoi(i8 zeroext)
     declare signext i8 @returns_signed_char()
     define void @baz(i32 "amdgpu-flat-work-group-size"="1,256" %x)
 
+    ; On call-sites:
+    call i32 @atoi(i8 zeroext %x)
+    call signext i8 @returns_signed_char()
+
 Note that any attributes for the function result (``nonnull``,
 ``signext``) come before the result type.
 
+Parameter attributes can be broadly separated into two kinds: ABI attributes
+that affect how values are passed to/from functions, like ``zeroext``,
+``inreg``, ``byval``, or ``sret``. And optimization attributes, which provide
+additional optimization guarantees, like ``noalias``, ``nonnull`` and
+``dereferenceable``.
+
+ABI attributes must be specified *both* at the function declaration/definition
+and call-site, otherwise the behavior may be undefined. ABI attributes cannot
+be safely dropped. Optimization attributes do not have to match between
+call-site and function: The intersection of their implied semantics applies.
+Optimization attributes can also be freely dropped.
+
 If an integer argument to a function is not marked signext/zeroext/noext, the
 kind of extension used is target-specific. Some targets depend for
 correctness on the kind of extension to be explicitly specified.

[rnk]

Thanks, lgtm!

[dtcxzyw]

Should we mention that noundef should match between call-site and function declarations/definitions when Memory Sanitizer is enabled?

[nikic]

I added a note about this.

[dtcxzyw]

LGTM.