[llvm] [LangRef] Add a description of the semantics of call signatures. (PR #136189)

[Eli Friedman via llvm-commits]

https://github.com/efriedma-quic updated https://github.com/llvm/llvm-project/pull/136189

>From 65cfb429b474522e8feea2da3c6c8c8450fe1750 Mon Sep 17 00:00:00 2001
From: Eli Friedman <efriedma at quicinc.com>
Date: Thu, 17 Apr 2025 12:48:06 -0700
Subject: [PATCH 1/2] [LangRef] Add a description of the semantics of call
 signatures.

This doesn't introduce anything new; it's just a reflection of the
semantics we've already had for many years.

Fixes #63484.
---
 llvm/docs/LangRef.rst | 27 ++++++++++++++++++++-------
 1 file changed, 20 insertions(+), 7 deletions(-)

diff --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst
index 110c30e19220f..8f5e035c1d736 100644
--- a/llvm/docs/LangRef.rst
+++ b/llvm/docs/LangRef.rst
@@ -9475,10 +9475,11 @@ This instruction requires several arguments:
    from the :ref:`datalayout string<langref_datalayout>` will be used.
 #. '``ty``': the type of the call instruction itself which is also the
    type of the return value. Functions that return no value are marked
-   ``void``.
+   ``void``. The signature is computed based on the return type and argument
+   types.
 #. '``fnty``': shall be the signature of the function being invoked. The
-   argument types must match the types implied by this signature. This
-   type can be omitted if the function is not varargs.
+   argument types must match the types implied by this signature. Thisa
+   is only required if the signature specifies a varargs type.
 #. '``fnptrval``': An LLVM value containing a pointer to a function to
    be invoked. In most cases, this is a direct function invocation, but
    indirect ``invoke``'s are just as possible, calling an arbitrary pointer
@@ -9571,10 +9572,11 @@ This instruction requires several arguments:
    from the :ref:`datalayout string<langref_datalayout>` will be used.
 #. '``ty``': the type of the call instruction itself which is also the
    type of the return value. Functions that return no value are marked
-   ``void``.
+   ``void``.  The signature is computed based on the return type and argument
+   types.
 #. '``fnty``': shall be the signature of the function being called. The
    argument types must match the types implied by this signature. This
-   type can be omitted if the function is not varargs.
+   is only required if the signature specifies a varargs type.
 #. '``fnptrval``': An LLVM value containing a pointer to a function to
    be called. In most cases, this is a direct function call, but
    other ``callbr``'s are just as possible, calling an arbitrary pointer
@@ -13127,10 +13129,11 @@ This instruction requires several arguments:
    from the :ref:`datalayout string<langref_datalayout>` will be used.
 #. '``ty``': the type of the call instruction itself which is also the
    type of the return value. Functions that return no value are marked
-   ``void``.
+   ``void``. The signature is computed based on the return type and argument
+   types.
 #. '``fnty``': shall be the signature of the function being called. The
    argument types must match the types implied by this signature. This
-   type can be omitted if the function is not varargs.
+   is only required if the signature specifies a varargs type.
 #. '``fnptrval``': An LLVM value containing a pointer to a function to
    be called. In most cases, this is a direct function call, but
    indirect ``call``'s are just as possible, calling an arbitrary pointer
@@ -13152,6 +13155,16 @@ values. Upon a '``ret``' instruction in the called function, control
 flow continues with the instruction after the function call, and the
 return value of the function is bound to the result argument.
 
+If the callee refers to an intrinsic function, the signature of the call must
+match the signature of the callee.  Otherwise, if the signature of the call
+does not match the signature of the called function, the behavior is
+target-specific.  For a signficant mismatch, this likely results in undefined
+behavior. LLVM interprocedural optimizations generally only optimize calls
+where the signature of the caller matches the signature of the callee.
+
+Note that it is possible for the signatures to mismatch even if a call appears
+to be a "direct" call, like ``call void @f()``.
+
 Example:
 """"""""
 

>From 865536c92b039754670f4183395073c19c2b0635 Mon Sep 17 00:00:00 2001
From: Eli Friedman <efriedma at quicinc.com>
Date: Thu, 17 Apr 2025 14:14:25 -0700
Subject: [PATCH 2/2] Fix typos.

---
 llvm/docs/LangRef.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/llvm/docs/LangRef.rst b/llvm/docs/LangRef.rst
index 8f5e035c1d736..a5df82895d839 100644
--- a/llvm/docs/LangRef.rst
+++ b/llvm/docs/LangRef.rst
@@ -9478,7 +9478,7 @@ This instruction requires several arguments:
    ``void``. The signature is computed based on the return type and argument
    types.
 #. '``fnty``': shall be the signature of the function being invoked. The
-   argument types must match the types implied by this signature. Thisa
+   argument types must match the types implied by this signature. This
    is only required if the signature specifies a varargs type.
 #. '``fnptrval``': An LLVM value containing a pointer to a function to
    be invoked. In most cases, this is a direct function invocation, but
@@ -13158,7 +13158,7 @@ return value of the function is bound to the result argument.
 If the callee refers to an intrinsic function, the signature of the call must
 match the signature of the callee.  Otherwise, if the signature of the call
 does not match the signature of the called function, the behavior is
-target-specific.  For a signficant mismatch, this likely results in undefined
+target-specific.  For a significant mismatch, this likely results in undefined
 behavior. LLVM interprocedural optimizations generally only optimize calls
 where the signature of the caller matches the signature of the callee.