[llvm] [clang-tools-extra] [clang] [HLSL][Docs] Add documentation for HLSL functions (PR #75397)

[Emilia Kond via cfe-commits]

@@ -0,0 +1,321 @@
+===
+HLSL Function Calls
+===
+
+.. contents::
+   :local:
+
+Introduction
+
+
+This document describes the design and implementation of HLSL's function call
+semantics in Clang. This includes details related to argument conversion and
+parameter lifetimes.
+
+This document does not seek to serve as official documentation for HLSL's
+call semantics, but does provide an overview to assist a reader. The
+authoritative documentation for HLSL's language semantics is the `draft 
language
+specification `_.
+
+Argument Semantics
+==
+
+In HLSL, all function arguments are passed by value in and out of functions.
+HLSL has 3 keywords which denote the parameter semantics (``in``, ``out`` and
+``inout``). In a function declaration a parameter may be annotated any of the
+following ways:
+
+#.  - denotes input
+#. ``in`` - denotes input
+#. ``out`` - denotes output
+#. ``in out`` - denotes input and output
+#. ``out in`` - denotes input and output
+#. ``inout`` - denotes input and output
+
+Parameters that are exclusively input behave like C/C++ parameters that are
+passed by value.
+
+For parameters that are output (or input and output), a temporary value is
+created in the caller. The temporary value is then passed by-address. For
+output-only parameters, the temporary is uninitialized when passed (if the
+parameter is not explicitly initialized inside the function an undefined value
+is stored back to the argument expression). For parameters that are both input
+and output, the temporary is initialized from the lvalue argument expression
+through implicit  or explicit casting from the lvalue argument type to the
+parameter type.
+
+On return of the function, the values of any parameter temporaries are written
+back to the argument expression through an inverted conversion sequence (if an
+``out`` parameter was not initialized in the function, the uninitialized value
+may be written back).
+
+Parameters of constant-sized array type are also passed with value semantics.
+This requires input parameters of arrays to construct temporaries and the
+temporaries go through array-to-pointer decay when initializing parameters.
+
+Implementations are allowed to avoid unnecessary temporaries, and HLSL's strict
+no-alias rules can enable some trivial optimizations.
+
+Array Temporaries
+-
+
+Given the following example:
+
+.. code-block:: c++
+
+  void fn(float a[4]) {
+a[0] = a[1] + a[2] + a[3];
+  }
+
+  float4 main() : SV_Target {
+float arr[4] = {1, 1, 1, 1};
+fn(arr);
+return float4(arr[0], arr[1], arr[2], arr[3]);
+  }
+
+In C or C++, the array parameter decays to a pointer, so after the call to
+``fn``, the value of ``arr[0]`` is ``3``. In HLSL, the array is passed by 
value,
+so modifications inside ``fn`` do not propagate out.
+
+.. note::
+
+  DXC may pass unsized arrays directly as decayed pointers, which is an
+  unfortunate behavior divergence.
+
+Out Parameter Temporaries
+-
+
+.. code-block:: c++
+
+  void Init(inout int X, inout int Y) {
+Y = 2;
+X = 1;
+  }
+
+  void main() {
+int V;
+Init(V, V); // MSVC (or clang-cl) V == 2, Clang V == 1
+  }
+
+In the above example the ``Init`` function's behavior depends on the C++
+implementation. C++ does not define the order in which parameters are
+initialized or destroyed. In MSVC and Clang's MSVC compatibility mode, 
arguments
+are emitted right-to-left and destroyed left-to-right. This means that  the
+parameter initialization and destruction occurs in the order: {``Y``, ``X``,
+``~X``, ``~Y``}. This causes the write-back of the value of ``Y`` to occur 
last,
+so the resulting value of ``V`` is ``2``. In the Itanium C++ ABI, the  
parameter
+ordering is reversed, so the initialization and destruction occurs in the 
order:
+{``X``, ``Y``, ``~Y``, ``X``}. This causes the write-back of the value ``X`` to
+occur last, resulting in the value of ``V`` being set to ``1``.
+
+.. code-block:: c++
+
+  void Trunc(inout int3 V) { }
+
+
+  void main() {
+float3 F = {1.5, 2.6, 3.3};
+Trunc(F); // F == {1.0, 2.0, 3.0}
+  }
+
+In the above example, the argument expression ``F`` undergoes element-wise
+conversion from a float vector to an integer vector to create a temporary
+``int3``. On expiration the temporary undergoes elementwise conversion back to
+the floating point vector type ``float3``. This results in an implicit
+element-wise conversion of the vector even if the value is unused in the
+function (effectively truncating the floating point values).
+
+
+.. code-block:: c++
+
+  void UB(out int X) {}
+
+  void main() {
+int X = 7;
+UB(X); // X is undefined!
+  }
+
+In this example an initialized value is passed to an ``out`` parameter.
+Parameters marked ``out`` are not initialized by the argument expression or
+implicitly by the 

[clang-tools-extra] [llvm] [clang] [HLSL][Docs] Add documentation for HLSL functions (PR #75397)

[Chris B via cfe-commits]

https://github.com/llvm-beanz updated 
https://github.com/llvm/llvm-project/pull/75397

>From 4ebc0c58dc751f422de85b0909636cb1a87f8ce4 Mon Sep 17 00:00:00 2001
From: Chris Bieneman 
Date: Wed, 13 Dec 2023 16:44:09 -0600
Subject: [PATCH 1/5] [HLSL][Docs] Add documentation for HLSL functions

This adds a new document that covers the HLSL approach to function
calls and parameter semantics. At time of writing this document is a
proposal for the implementation.
---
 clang/docs/HLSL/FunctionCalls.rst | 316 ++
 clang/docs/HLSL/HLSLDocs.rst  |   1 +
 2 files changed, 317 insertions(+)
 create mode 100644 clang/docs/HLSL/FunctionCalls.rst

diff --git a/clang/docs/HLSL/FunctionCalls.rst 
b/clang/docs/HLSL/FunctionCalls.rst
new file mode 100644
index 00..e62b249e011a94
--- /dev/null
+++ b/clang/docs/HLSL/FunctionCalls.rst
@@ -0,0 +1,316 @@
+===
+HLSL Function Calls
+===
+
+.. contents::
+   :local:
+
+Introduction
+
+
+This document descries the design and implementation of HLSL's function call
+semantics in Clang. This includes details related to argument conversion and
+parameter lifetimes.
+
+This document does not seek to serve as official documentation for HLSL's
+call semantics, but does provide an overview to assist a reader. The
+authoritative documentation for HLSL's language semantics is the `draft 
language
+specification `_.
+
+Argument Semantics
+==
+
+In HLSL, all function arguments are passed by value in and out of functions.
+HLSL has 3 keywords which denote the parameter semantics (``in``, ``out`` and
+``inout``). In a function declaration a parameter may be annotated any of the
+following ways:
+
+#.  - denotes input
+#. ``in`` - denotes input
+#. ``out`` - denotes output
+#. ``in out`` - denotes input and output
+#. ``out in`` - denotes input and output
+#. ``inout`` - denotes input and output
+
+Parameters that are exclusively input behave like C/C++ parameters that are
+passed by value.
+
+For parameters that are output (or input and output), a temporary value is
+created in the caller. The temporary value is then passed by-address. For
+output-only parameters, the temporary is uninitialized when passed (it is
+undefined behavior to not explicitly initialize an ``out`` parameter inside a
+function). For input and output parameters, the temporary is initialized from
+the lvalue argument expression through implicit or explicit casting from the
+lvalue argument type to the parameter type.
+
+On return of the function, the values of any parameter temporaries are written
+back to the argument expression through an inverted conversion sequence (if an
+``out`` parameter was not initialized in the function, the uninitialized value
+may be written back).
+
+Parameters of constant-sized array type, are also passed with value semantics.
+This requires input parameters of arrays to construct temporaries and the
+temporaries go through array-to-pointer decay when initializing parameters.
+
+Implementations are allowed to avoid unnecessary temporaries, and HLSL's strict
+no-alias rules can enable some trivial optimizations.
+
+Array Temporaries
+-
+
+Given the following example:
+
+.. code-block:: c++
+
+  void fn(float a[4]) {
+a[0] = a[1] + a[2] + a[3];
+  }
+
+  float4 main() : SV_Target {
+float arr[4] = {1, 1, 1, 1};
+fn(arr);
+return float4(a[0], a[1], a[2], a[3]);
+  }
+
+In C or C++, the array parameter decays to a pointer, so after the call to
+``fn``, the value of ``a[0]`` is ``3``. In HLSL, the array is passed by value,
+so modifications inside ``fn`` do not propagate out.
+
+.. note::
+
+  DXC supports unsized arrays passed directly as decayed pointers, which is an
+  unfortunate behavior divergence.
+
+Out Parameter Temporaries
+-
+
+.. code-block:: c++
+
+  void Init(inout int X, inout int Y) {
+Y = 2;
+X = 1;
+  }
+
+  void main() {
+int V;
+Init(V, V); // MSVC ABI V == 2, Itanium V == 1
+  }
+
+In the above example the ``Init`` function's behavior depends on the C++ ABI
+implementation. In the MSVC C++ ABI (used for the HLSL DXIL target), call
+arguments are emitted right-to-left and destroyed left-to-right. This means 
that
+the parameter initialization and destruction occurs in the order: {``Y``,
+``X``, ``~X``, ``~Y``}. This causes the write-back of the value of ``Y`` to 
occur
+last, so the resulting value of ``V`` is ``2``. In the Itanium C++ ABI, the
+parameter ordering is reversed, so the initialization and destruction occurs in
+the order: {``X``, ``Y``, ``~Y``, ``X``}. This causes the write-back of the
+value ``X`` to occur last, resulting in the value of ``V`` being set to ``1``.
+
+.. code-block:: c++
+
+  void Trunc(inout int3 V) { }
+
+
+  void main() {
+float3 F = {1.5, 2.6, 3.3};
+Trunc(F); // F == {1.0, 2.0, 3.0}
+  }
+
+In the above example, 

[clang] [HLSL][Docs] Add documentation for HLSL functions (PR #75397)

[Justin Bogner via cfe-commits]

https://github.com/bogner approved this pull request.


https://github.com/llvm/llvm-project/pull/75397
___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[clang] [HLSL][Docs] Add documentation for HLSL functions (PR #75397)

[Chris B via cfe-commits]

https://github.com/llvm-beanz updated 
https://github.com/llvm/llvm-project/pull/75397

>From 4ebc0c58dc751f422de85b0909636cb1a87f8ce4 Mon Sep 17 00:00:00 2001
From: Chris Bieneman 
Date: Wed, 13 Dec 2023 16:44:09 -0600
Subject: [PATCH 1/5] [HLSL][Docs] Add documentation for HLSL functions

This adds a new document that covers the HLSL approach to function
calls and parameter semantics. At time of writing this document is a
proposal for the implementation.
---
 clang/docs/HLSL/FunctionCalls.rst | 316 ++
 clang/docs/HLSL/HLSLDocs.rst  |   1 +
 2 files changed, 317 insertions(+)
 create mode 100644 clang/docs/HLSL/FunctionCalls.rst

diff --git a/clang/docs/HLSL/FunctionCalls.rst 
b/clang/docs/HLSL/FunctionCalls.rst
new file mode 100644
index 00..e62b249e011a94
--- /dev/null
+++ b/clang/docs/HLSL/FunctionCalls.rst
@@ -0,0 +1,316 @@
+===
+HLSL Function Calls
+===
+
+.. contents::
+   :local:
+
+Introduction
+
+
+This document descries the design and implementation of HLSL's function call
+semantics in Clang. This includes details related to argument conversion and
+parameter lifetimes.
+
+This document does not seek to serve as official documentation for HLSL's
+call semantics, but does provide an overview to assist a reader. The
+authoritative documentation for HLSL's language semantics is the `draft 
language
+specification `_.
+
+Argument Semantics
+==
+
+In HLSL, all function arguments are passed by value in and out of functions.
+HLSL has 3 keywords which denote the parameter semantics (``in``, ``out`` and
+``inout``). In a function declaration a parameter may be annotated any of the
+following ways:
+
+#.  - denotes input
+#. ``in`` - denotes input
+#. ``out`` - denotes output
+#. ``in out`` - denotes input and output
+#. ``out in`` - denotes input and output
+#. ``inout`` - denotes input and output
+
+Parameters that are exclusively input behave like C/C++ parameters that are
+passed by value.
+
+For parameters that are output (or input and output), a temporary value is
+created in the caller. The temporary value is then passed by-address. For
+output-only parameters, the temporary is uninitialized when passed (it is
+undefined behavior to not explicitly initialize an ``out`` parameter inside a
+function). For input and output parameters, the temporary is initialized from
+the lvalue argument expression through implicit or explicit casting from the
+lvalue argument type to the parameter type.
+
+On return of the function, the values of any parameter temporaries are written
+back to the argument expression through an inverted conversion sequence (if an
+``out`` parameter was not initialized in the function, the uninitialized value
+may be written back).
+
+Parameters of constant-sized array type, are also passed with value semantics.
+This requires input parameters of arrays to construct temporaries and the
+temporaries go through array-to-pointer decay when initializing parameters.
+
+Implementations are allowed to avoid unnecessary temporaries, and HLSL's strict
+no-alias rules can enable some trivial optimizations.
+
+Array Temporaries
+-
+
+Given the following example:
+
+.. code-block:: c++
+
+  void fn(float a[4]) {
+a[0] = a[1] + a[2] + a[3];
+  }
+
+  float4 main() : SV_Target {
+float arr[4] = {1, 1, 1, 1};
+fn(arr);
+return float4(a[0], a[1], a[2], a[3]);
+  }
+
+In C or C++, the array parameter decays to a pointer, so after the call to
+``fn``, the value of ``a[0]`` is ``3``. In HLSL, the array is passed by value,
+so modifications inside ``fn`` do not propagate out.
+
+.. note::
+
+  DXC supports unsized arrays passed directly as decayed pointers, which is an
+  unfortunate behavior divergence.
+
+Out Parameter Temporaries
+-
+
+.. code-block:: c++
+
+  void Init(inout int X, inout int Y) {
+Y = 2;
+X = 1;
+  }
+
+  void main() {
+int V;
+Init(V, V); // MSVC ABI V == 2, Itanium V == 1
+  }
+
+In the above example the ``Init`` function's behavior depends on the C++ ABI
+implementation. In the MSVC C++ ABI (used for the HLSL DXIL target), call
+arguments are emitted right-to-left and destroyed left-to-right. This means 
that
+the parameter initialization and destruction occurs in the order: {``Y``,
+``X``, ``~X``, ``~Y``}. This causes the write-back of the value of ``Y`` to 
occur
+last, so the resulting value of ``V`` is ``2``. In the Itanium C++ ABI, the
+parameter ordering is reversed, so the initialization and destruction occurs in
+the order: {``X``, ``Y``, ``~Y``, ``X``}. This causes the write-back of the
+value ``X`` to occur last, resulting in the value of ``V`` being set to ``1``.
+
+.. code-block:: c++
+
+  void Trunc(inout int3 V) { }
+
+
+  void main() {
+float3 F = {1.5, 2.6, 3.3};
+Trunc(F); // F == {1.0, 2.0, 3.0}
+  }
+
+In the above example, 

[clang] [HLSL][Docs] Add documentation for HLSL functions (PR #75397)

[John McCall via cfe-commits]

https://github.com/rjmccall edited 
https://github.com/llvm/llvm-project/pull/75397
___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[clang] [HLSL][Docs] Add documentation for HLSL functions (PR #75397)

[John McCall via cfe-commits]

@@ -0,0 +1,300 @@
+===
+HLSL Function Calls
+===
+
+.. contents::
+   :local:
+
+Introduction
+
+
+This document descries the design and implementation of HLSL's function call
+semantics in Clang. This includes details related to argument conversion and
+parameter lifetimes.
+
+This document does not seek to serve as official documentation for HLSL's
+call semantics, but does provide an overview to assist a reader. The
+authoritative documentation for HLSL's language semantics is the `draft 
language
+specification`_.
+
+Argument Semantics
+==
+
+In HLSL, all function arguments are passed by value in and out of functions.
+HLSL has 3 keywords which denote the parameter semantics (``in``, ``out`` and
+``inout``). In a function declaration a parameter may be annotated any of the
+following ways:
+
+#.  - denotes input
+#. ``in`` - denotes input
+#. ``out`` - denotes output
+#. ``in out`` - denotes input and output
+#. ``out in`` - denotes input and output
+#. ``inout`` - denotes input and output
+
+Parameters that are exclusively input behave like C/C++ parameters that are
+passed by value.
+
+For parameters that are output (or input and output), a temporary value is
+created in the caller. The temporary value is then passed by-address. For
+output-only parameters, the temporary is uninitialized when passed (it is
+undefined behavior to not explicitly initialize an ``out`` parameter inside a
+function). For input and output parameters, the temporary is initialized from
+the lvalue argument expression through implicit or explicit casting from the
+lvalue argument type to the parameter type.
+
+On return of the function, the values of any parameter temporaries are written
+back to the argument expression through an inverted conversion sequence (if an
+``out`` parameter was not initialized in the function, the uninitialized value
+may be written back).
+
+Parameters of constant-sized array type, are also passed with value semantics.
+This requires input parameters of arrays to construct temporaries and the
+temporaries go through array-to-pointer decay when initializing parameters.
+
+Implementations are allowed to avoid unnecessary temporaries, and HLSL's strict
+no-alias rules can enable some trivial optimizations.
+
+Array Temporaries
+-
+
+Given the following example:
+
+.. code-block:: c++
+  void fn(float a[4]) {
+a[0] = a[1] + a[2] + a[3];
+  }
+
+  float4 main() : SV_Target {
+float arr[4] = {1, 1, 1, 1};
+fn(arr);
+return float4(a[0], a[1], a[2], a[3]);
+  }
+
+In C or C++, the array parameter decays to a pointer, so after the call to
+``fn``, the value of ``a[0]`` is ``3``. In HLSL, the array is passed by value,
+so modifications inside ``fn`` do not propagate out.
+
+.. note::
+  DXC supports unsized arrays passed directly as decayed pointers, which is an
+  unfortunate behavior divergence.
+
+Out Parameter Temporaries
+-
+
+.. code-block:: c++
+  void Init(inout int X, inout int Y) {
+Y = 2;
+X = 1;
+  }
+
+  void main() {
+int V;
+Init(V, V); // MSVC ABI V == 2, Itanium V == 1
+  }
+
+In the above example the ``Init`` function's behavior depends on the C++ ABI
+implementation. In the MSVC C++ ABI (used for the HLSL DXIL target), call

rjmccall wrote:

Right, this is a general compiler difference and not actually ABI-specific 
*except* that the MSVC C++ ABI does effectively require that arguments of class 
type are evaluated right-to-left (because they're destroyed left-to-right in 
the callee).

https://github.com/llvm/llvm-project/pull/75397
___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[clang] [HLSL][Docs] Add documentation for HLSL functions (PR #75397)

[John McCall via cfe-commits]

rjmccall wrote:

> @rjmccall, I'm curious if you have any thoughts on the proposed 
> implementation approach here?
> 
> The TL;DR for the gnarly bit is to have AST nodes representing parameters 
> that need temporary values, and for "output" parameters where there may be 
> cast sequences involved the AST node will capture the cast sequences for both 
> parameter initialization and writing back to the argument lvalue. Then we can 
> slightly tweak the CGCall write back support to support having a cast 
> sequence in the AST.

Yeah, I think having the argument being some kind of special expression that 
stores the cast sequences back and forth makes a lot of sense.

I've frequently felt that our `Expr`-centric representation for cast sequences 
is unnecessarily awkward to work with; we'd probably benefit from some sort of 
explicit `Cast` representation that would just get stored in a `CastExpr`.  I 
can't in good conscience ask you to implement that and then refactor all our 
conversion code in CodeGen around it, though.  Given our current 
representations, you probably just need to do something with `OpaqueValueExpr`.

https://github.com/llvm/llvm-project/pull/75397
___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[clang] [HLSL][Docs] Add documentation for HLSL functions (PR #75397)

[Justin Bogner via cfe-commits]

@@ -0,0 +1,316 @@
+===
+HLSL Function Calls
+===
+
+.. contents::
+   :local:
+
+Introduction
+
+
+This document describes the design and implementation of HLSL's function call
+semantics in Clang. This includes details related to argument conversion and
+parameter lifetimes.
+
+This document does not seek to serve as official documentation for HLSL's
+call semantics, but does provide an overview to assist a reader. The
+authoritative documentation for HLSL's language semantics is the `draft 
language
+specification `_.
+
+Argument Semantics
+==
+
+In HLSL, all function arguments are passed by value in and out of functions.
+HLSL has 3 keywords which denote the parameter semantics (``in``, ``out`` and
+``inout``). In a function declaration a parameter may be annotated any of the
+following ways:
+
+#.  - denotes input
+#. ``in`` - denotes input
+#. ``out`` - denotes output
+#. ``in out`` - denotes input and output
+#. ``out in`` - denotes input and output
+#. ``inout`` - denotes input and output
+
+Parameters that are exclusively input behave like C/C++ parameters that are
+passed by value.
+
+For parameters that are output (or input and output), a temporary value is
+created in the caller. The temporary value is then passed by-address. For
+output-only parameters, the temporary is uninitialized when passed (it is
+undefined behavior to not explicitly initialize an ``out`` parameter inside a
+function). For input and output parameters, the temporary is initialized from
+the lvalue argument expression through implicit or explicit casting from the
+lvalue argument type to the parameter type.
+
+On return of the function, the values of any parameter temporaries are written
+back to the argument expression through an inverted conversion sequence (if an
+``out`` parameter was not initialized in the function, the uninitialized value
+may be written back).
+
+Parameters of constant-sized array type, are also passed with value semantics.
+This requires input parameters of arrays to construct temporaries and the
+temporaries go through array-to-pointer decay when initializing parameters.
+
+Implementations are allowed to avoid unnecessary temporaries, and HLSL's strict
+no-alias rules can enable some trivial optimizations.
+
+Array Temporaries
+-
+
+Given the following example:
+
+.. code-block:: c++
+
+  void fn(float a[4]) {
+a[0] = a[1] + a[2] + a[3];
+  }
+
+  float4 main() : SV_Target {
+float arr[4] = {1, 1, 1, 1};
+fn(arr);
+return float4(a[0], a[1], a[2], a[3]);
+  }
+
+In C or C++, the array parameter decays to a pointer, so after the call to
+``fn``, the value of ``a[0]`` is ``3``. In HLSL, the array is passed by value,
+so modifications inside ``fn`` do not propagate out.
+
+.. note::
+
+  DXC supports unsized arrays passed directly as decayed pointers, which is an
+  unfortunate behavior divergence.

bogner wrote:

Maybe the note should say something like "DXC may pass unsized arrays directly 
as decayed pointers, which is an unfortunate behavior divergence" then, rather 
than claiming support?

https://github.com/llvm/llvm-project/pull/75397
___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[clang] [HLSL][Docs] Add documentation for HLSL functions (PR #75397)

[Justin Bogner via cfe-commits]

@@ -0,0 +1,319 @@
+===
+HLSL Function Calls
+===
+
+.. contents::
+   :local:
+
+Introduction
+
+
+This document describes the design and implementation of HLSL's function call
+semantics in Clang. This includes details related to argument conversion and
+parameter lifetimes.
+
+This document does not seek to serve as official documentation for HLSL's
+call semantics, but does provide an overview to assist a reader. The
+authoritative documentation for HLSL's language semantics is the `draft 
language
+specification `_.
+
+Argument Semantics
+==
+
+In HLSL, all function arguments are passed by value in and out of functions.
+HLSL has 3 keywords which denote the parameter semantics (``in``, ``out`` and
+``inout``). In a function declaration a parameter may be annotated any of the
+following ways:
+
+#.  - denotes input
+#. ``in`` - denotes input
+#. ``out`` - denotes output
+#. ``in out`` - denotes input and output
+#. ``out in`` - denotes input and output
+#. ``inout`` - denotes input and output
+
+Parameters that are exclusively input behave like C/C++ parameters that are
+passed by value.
+
+For parameters that are output (or input and output), a temporary value is
+created in the caller. The temporary value is then passed by-address. For
+output-only parameters, the temporary is uninitialized when passed (if the
+parameter is not explicitly initialized inside the function an undefined value
+is stored back to the argument expression). For input and output parameters, 
the
+temporary is initialized from  the lvalue argument expression through implicit
+or explicit casting from the lvalue argument type to the parameter type.

bogner wrote:

There's a little bit of ambiguity in this paragraph when you use the term 
"input and output", where it could be read as "parameters that are input and 
parameters that are output" rather than "parameters that are both input and 
output". I'm not sure the best way to improve this without getting overly wordy 
though - I suppose we could spell it "input-and-output" to be clear that it's 
atomic, or maybe we could use "both" and update that in the list above as well.

https://github.com/llvm/llvm-project/pull/75397
___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[clang] [HLSL][Docs] Add documentation for HLSL functions (PR #75397)

[Justin Bogner via cfe-commits]

@@ -0,0 +1,319 @@
+===
+HLSL Function Calls
+===
+
+.. contents::
+   :local:
+
+Introduction
+
+
+This document describes the design and implementation of HLSL's function call
+semantics in Clang. This includes details related to argument conversion and
+parameter lifetimes.
+
+This document does not seek to serve as official documentation for HLSL's
+call semantics, but does provide an overview to assist a reader. The
+authoritative documentation for HLSL's language semantics is the `draft 
language
+specification `_.
+
+Argument Semantics
+==
+
+In HLSL, all function arguments are passed by value in and out of functions.
+HLSL has 3 keywords which denote the parameter semantics (``in``, ``out`` and
+``inout``). In a function declaration a parameter may be annotated any of the
+following ways:
+
+#.  - denotes input
+#. ``in`` - denotes input
+#. ``out`` - denotes output
+#. ``in out`` - denotes input and output
+#. ``out in`` - denotes input and output
+#. ``inout`` - denotes input and output
+
+Parameters that are exclusively input behave like C/C++ parameters that are
+passed by value.
+
+For parameters that are output (or input and output), a temporary value is
+created in the caller. The temporary value is then passed by-address. For
+output-only parameters, the temporary is uninitialized when passed (if the
+parameter is not explicitly initialized inside the function an undefined value
+is stored back to the argument expression). For input and output parameters, 
the
+temporary is initialized from  the lvalue argument expression through implicit
+or explicit casting from the lvalue argument type to the parameter type.
+
+On return of the function, the values of any parameter temporaries are written
+back to the argument expression through an inverted conversion sequence (if an
+``out`` parameter was not initialized in the function, the uninitialized value
+may be written back).
+
+Parameters of constant-sized array type, are also passed with value semantics.

bogner wrote:

spurious comma

https://github.com/llvm/llvm-project/pull/75397
___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[clang] [HLSL][Docs] Add documentation for HLSL functions (PR #75397)

[Justin Bogner via cfe-commits]

@@ -0,0 +1,300 @@
+===
+HLSL Function Calls
+===
+
+.. contents::
+   :local:
+
+Introduction
+
+
+This document descries the design and implementation of HLSL's function call
+semantics in Clang. This includes details related to argument conversion and
+parameter lifetimes.
+
+This document does not seek to serve as official documentation for HLSL's
+call semantics, but does provide an overview to assist a reader. The
+authoritative documentation for HLSL's language semantics is the `draft 
language
+specification`_.
+
+Argument Semantics
+==
+
+In HLSL, all function arguments are passed by value in and out of functions.
+HLSL has 3 keywords which denote the parameter semantics (``in``, ``out`` and
+``inout``). In a function declaration a parameter may be annotated any of the
+following ways:
+
+#.  - denotes input
+#. ``in`` - denotes input
+#. ``out`` - denotes output
+#. ``in out`` - denotes input and output
+#. ``out in`` - denotes input and output
+#. ``inout`` - denotes input and output
+
+Parameters that are exclusively input behave like C/C++ parameters that are
+passed by value.
+
+For parameters that are output (or input and output), a temporary value is
+created in the caller. The temporary value is then passed by-address. For
+output-only parameters, the temporary is uninitialized when passed (it is
+undefined behavior to not explicitly initialize an ``out`` parameter inside a
+function). For input and output parameters, the temporary is initialized from
+the lvalue argument expression through implicit or explicit casting from the
+lvalue argument type to the parameter type.
+
+On return of the function, the values of any parameter temporaries are written
+back to the argument expression through an inverted conversion sequence (if an
+``out`` parameter was not initialized in the function, the uninitialized value
+may be written back).
+
+Parameters of constant-sized array type, are also passed with value semantics.
+This requires input parameters of arrays to construct temporaries and the
+temporaries go through array-to-pointer decay when initializing parameters.
+
+Implementations are allowed to avoid unnecessary temporaries, and HLSL's strict
+no-alias rules can enable some trivial optimizations.
+
+Array Temporaries
+-
+
+Given the following example:
+
+.. code-block:: c++
+  void fn(float a[4]) {
+a[0] = a[1] + a[2] + a[3];
+  }
+
+  float4 main() : SV_Target {
+float arr[4] = {1, 1, 1, 1};
+fn(arr);
+return float4(a[0], a[1], a[2], a[3]);
+  }
+
+In C or C++, the array parameter decays to a pointer, so after the call to
+``fn``, the value of ``a[0]`` is ``3``. In HLSL, the array is passed by value,
+so modifications inside ``fn`` do not propagate out.
+
+.. note::
+  DXC supports unsized arrays passed directly as decayed pointers, which is an
+  unfortunate behavior divergence.
+
+Out Parameter Temporaries
+-
+
+.. code-block:: c++
+  void Init(inout int X, inout int Y) {
+Y = 2;
+X = 1;
+  }
+
+  void main() {
+int V;
+Init(V, V); // MSVC ABI V == 2, Itanium V == 1
+  }
+
+In the above example the ``Init`` function's behavior depends on the C++ ABI
+implementation. In the MSVC C++ ABI (used for the HLSL DXIL target), call

bogner wrote:

This is mostly me being pedantic, but I don't believe this ordering is 
specified in the Itanium ABI at all (and I don't see anything obvious here: 
https://itanium-cxx-abi.github.io/cxx-abi/abi.html). I'm not sure about the 
MSVC ABI. Would it be more accurate to point out that C++ has historically not 
defined this ordering, describe the two alternatives, and point out that DXC 
behaves in the MSVC way and so we want to match that?

https://github.com/llvm/llvm-project/pull/75397
___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[clang] [HLSL][Docs] Add documentation for HLSL functions (PR #75397)

[Chris B via cfe-commits]

llvm-beanz wrote:

@rjmccall, I'm curious if you have any thoughts on the proposed implementation 
approach here?

The TL;DR for the gnarly bit is to have AST nodes representing parameters that 
need temporary values, and for "output" parameters where there may be cast 
sequences involved the AST node will capture the cast sequences for both 
parameter initialization and writing back to the argument lvalue. Then we can 
slightly tweak the CGCall write back support to support having a cast sequence 
in the AST.

https://github.com/llvm/llvm-project/pull/75397
___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[clang] [HLSL][Docs] Add documentation for HLSL functions (PR #75397)

[Chris B via cfe-commits]

https://github.com/llvm-beanz updated 
https://github.com/llvm/llvm-project/pull/75397

>From 4ebc0c58dc751f422de85b0909636cb1a87f8ce4 Mon Sep 17 00:00:00 2001
From: Chris Bieneman 
Date: Wed, 13 Dec 2023 16:44:09 -0600
Subject: [PATCH 1/4] [HLSL][Docs] Add documentation for HLSL functions

This adds a new document that covers the HLSL approach to function
calls and parameter semantics. At time of writing this document is a
proposal for the implementation.
---
 clang/docs/HLSL/FunctionCalls.rst | 316 ++
 clang/docs/HLSL/HLSLDocs.rst  |   1 +
 2 files changed, 317 insertions(+)
 create mode 100644 clang/docs/HLSL/FunctionCalls.rst

diff --git a/clang/docs/HLSL/FunctionCalls.rst 
b/clang/docs/HLSL/FunctionCalls.rst
new file mode 100644
index 00..e62b249e011a94
--- /dev/null
+++ b/clang/docs/HLSL/FunctionCalls.rst
@@ -0,0 +1,316 @@
+===
+HLSL Function Calls
+===
+
+.. contents::
+   :local:
+
+Introduction
+
+
+This document descries the design and implementation of HLSL's function call
+semantics in Clang. This includes details related to argument conversion and
+parameter lifetimes.
+
+This document does not seek to serve as official documentation for HLSL's
+call semantics, but does provide an overview to assist a reader. The
+authoritative documentation for HLSL's language semantics is the `draft 
language
+specification `_.
+
+Argument Semantics
+==
+
+In HLSL, all function arguments are passed by value in and out of functions.
+HLSL has 3 keywords which denote the parameter semantics (``in``, ``out`` and
+``inout``). In a function declaration a parameter may be annotated any of the
+following ways:
+
+#.  - denotes input
+#. ``in`` - denotes input
+#. ``out`` - denotes output
+#. ``in out`` - denotes input and output
+#. ``out in`` - denotes input and output
+#. ``inout`` - denotes input and output
+
+Parameters that are exclusively input behave like C/C++ parameters that are
+passed by value.
+
+For parameters that are output (or input and output), a temporary value is
+created in the caller. The temporary value is then passed by-address. For
+output-only parameters, the temporary is uninitialized when passed (it is
+undefined behavior to not explicitly initialize an ``out`` parameter inside a
+function). For input and output parameters, the temporary is initialized from
+the lvalue argument expression through implicit or explicit casting from the
+lvalue argument type to the parameter type.
+
+On return of the function, the values of any parameter temporaries are written
+back to the argument expression through an inverted conversion sequence (if an
+``out`` parameter was not initialized in the function, the uninitialized value
+may be written back).
+
+Parameters of constant-sized array type, are also passed with value semantics.
+This requires input parameters of arrays to construct temporaries and the
+temporaries go through array-to-pointer decay when initializing parameters.
+
+Implementations are allowed to avoid unnecessary temporaries, and HLSL's strict
+no-alias rules can enable some trivial optimizations.
+
+Array Temporaries
+-
+
+Given the following example:
+
+.. code-block:: c++
+
+  void fn(float a[4]) {
+a[0] = a[1] + a[2] + a[3];
+  }
+
+  float4 main() : SV_Target {
+float arr[4] = {1, 1, 1, 1};
+fn(arr);
+return float4(a[0], a[1], a[2], a[3]);
+  }
+
+In C or C++, the array parameter decays to a pointer, so after the call to
+``fn``, the value of ``a[0]`` is ``3``. In HLSL, the array is passed by value,
+so modifications inside ``fn`` do not propagate out.
+
+.. note::
+
+  DXC supports unsized arrays passed directly as decayed pointers, which is an
+  unfortunate behavior divergence.
+
+Out Parameter Temporaries
+-
+
+.. code-block:: c++
+
+  void Init(inout int X, inout int Y) {
+Y = 2;
+X = 1;
+  }
+
+  void main() {
+int V;
+Init(V, V); // MSVC ABI V == 2, Itanium V == 1
+  }
+
+In the above example the ``Init`` function's behavior depends on the C++ ABI
+implementation. In the MSVC C++ ABI (used for the HLSL DXIL target), call
+arguments are emitted right-to-left and destroyed left-to-right. This means 
that
+the parameter initialization and destruction occurs in the order: {``Y``,
+``X``, ``~X``, ``~Y``}. This causes the write-back of the value of ``Y`` to 
occur
+last, so the resulting value of ``V`` is ``2``. In the Itanium C++ ABI, the
+parameter ordering is reversed, so the initialization and destruction occurs in
+the order: {``X``, ``Y``, ``~Y``, ``X``}. This causes the write-back of the
+value ``X`` to occur last, resulting in the value of ``V`` being set to ``1``.
+
+.. code-block:: c++
+
+  void Trunc(inout int3 V) { }
+
+
+  void main() {
+float3 F = {1.5, 2.6, 3.3};
+Trunc(F); // F == {1.0, 2.0, 3.0}
+  }
+
+In the above example, 

[clang] [HLSL][Docs] Add documentation for HLSL functions (PR #75397)

[Chris B via cfe-commits]

@@ -0,0 +1,316 @@
+===
+HLSL Function Calls
+===
+
+.. contents::
+   :local:
+
+Introduction
+
+
+This document describes the design and implementation of HLSL's function call
+semantics in Clang. This includes details related to argument conversion and
+parameter lifetimes.
+
+This document does not seek to serve as official documentation for HLSL's
+call semantics, but does provide an overview to assist a reader. The
+authoritative documentation for HLSL's language semantics is the `draft 
language
+specification `_.
+
+Argument Semantics
+==
+
+In HLSL, all function arguments are passed by value in and out of functions.
+HLSL has 3 keywords which denote the parameter semantics (``in``, ``out`` and
+``inout``). In a function declaration a parameter may be annotated any of the
+following ways:
+
+#.  - denotes input
+#. ``in`` - denotes input
+#. ``out`` - denotes output
+#. ``in out`` - denotes input and output
+#. ``out in`` - denotes input and output
+#. ``inout`` - denotes input and output
+
+Parameters that are exclusively input behave like C/C++ parameters that are
+passed by value.
+
+For parameters that are output (or input and output), a temporary value is
+created in the caller. The temporary value is then passed by-address. For
+output-only parameters, the temporary is uninitialized when passed (if the
+parameter is not explicitly initialized inside the function an undefined value
+is stored back to the argument expression). For input and output parameters, 
the
+temporary is initialized from  the lvalue argument expression through implicit
+or explicit casting from the lvalue argument type to the parameter type.
+
+On return of the function, the values of any parameter temporaries are written
+back to the argument expression through an inverted conversion sequence (if an
+``out`` parameter was not initialized in the function, the uninitialized value
+may be written back).
+
+Parameters of constant-sized array type, are also passed with value semantics.
+This requires input parameters of arrays to construct temporaries and the
+temporaries go through array-to-pointer decay when initializing parameters.
+
+Implementations are allowed to avoid unnecessary temporaries, and HLSL's strict
+no-alias rules can enable some trivial optimizations.
+
+Array Temporaries
+-
+
+Given the following example:
+
+.. code-block:: c++
+
+  void fn(float a[4]) {
+a[0] = a[1] + a[2] + a[3];
+  }
+
+  float4 main() : SV_Target {
+float arr[4] = {1, 1, 1, 1};
+fn(arr);
+return float4(arr[0], arr[1], arr[2], arr[3]);
+  }
+
+In C or C++, the array parameter decays to a pointer, so after the call to
+``fn``, the value of ``arr[0]`` is ``3``. In HLSL, the array is passed by 
value,
+so modifications inside ``fn`` do not propagate out.
+
+.. note::
+
+  DXC supports unsized arrays passed directly as decayed pointers, which is an
+  unfortunate behavior divergence.
+
+Out Parameter Temporaries
+-
+
+.. code-block:: c++
+
+  void Init(inout int X, inout int Y) {
+Y = 2;
+X = 1;
+  }
+
+  void main() {
+int V;
+Init(V, V); // MSVC ABI V == 2, Itanium V == 1
+  }
+
+In the above example the ``Init`` function's behavior depends on the C++ ABI
+implementation. In the MSVC C++ ABI (used for the HLSL DXIL target), call
+arguments are emitted right-to-left and destroyed left-to-right. This means 
that
+the parameter initialization and destruction occurs in the order: {``Y``,
+``X``, ``~X``, ``~Y``}. This causes the write-back of the value of ``Y`` to 
occur
+last, so the resulting value of ``V`` is ``2``. In the Itanium C++ ABI, the
+parameter ordering is reversed, so the initialization and destruction occurs in
+the order: {``X``, ``Y``, ``~Y``, ``X``}. This causes the write-back of the
+value ``X`` to occur last, resulting in the value of ``V`` being set to ``1``.
+
+.. code-block:: c++
+
+  void Trunc(inout int3 V) { }
+
+
+  void main() {
+float3 F = {1.5, 2.6, 3.3};
+Trunc(F); // F == {1.0, 2.0, 3.0}
+  }
+
+In the above example, the argument expression ``F`` undergoes element-wise
+conversion from a float vector to an integer vector to create a temporary
+``int3``. On expiration the temporary undergoes elementwise conversion back to
+the floating point vector type ``float3``. This results in an implicit
+truncation of the vector even if the value is unused in the function.
+
+
+.. code-block:: c++
+
+  void UB(out int X) {}
+
+  void main() {
+int X = 7;
+UB(X); // X is undefined!
+  }
+
+In this example an initialized value is passed to an ``out`` parameter.
+Parameters marked ``out`` are not initialized by the argument expression or
+implicitly by the function. They must be explicitly initialized. In this case
+the argument is not initialized in the function so the temporary is still
+uninitialized when 

[clang] [HLSL][Docs] Add documentation for HLSL functions (PR #75397)

[Chris B via cfe-commits]

@@ -0,0 +1,316 @@
+===
+HLSL Function Calls
+===
+
+.. contents::
+   :local:
+
+Introduction
+
+
+This document describes the design and implementation of HLSL's function call
+semantics in Clang. This includes details related to argument conversion and
+parameter lifetimes.
+
+This document does not seek to serve as official documentation for HLSL's
+call semantics, but does provide an overview to assist a reader. The
+authoritative documentation for HLSL's language semantics is the `draft 
language
+specification `_.
+
+Argument Semantics
+==
+
+In HLSL, all function arguments are passed by value in and out of functions.
+HLSL has 3 keywords which denote the parameter semantics (``in``, ``out`` and
+``inout``). In a function declaration a parameter may be annotated any of the
+following ways:
+
+#.  - denotes input
+#. ``in`` - denotes input
+#. ``out`` - denotes output
+#. ``in out`` - denotes input and output
+#. ``out in`` - denotes input and output
+#. ``inout`` - denotes input and output
+
+Parameters that are exclusively input behave like C/C++ parameters that are
+passed by value.
+
+For parameters that are output (or input and output), a temporary value is
+created in the caller. The temporary value is then passed by-address. For
+output-only parameters, the temporary is uninitialized when passed (it is
+undefined behavior to not explicitly initialize an ``out`` parameter inside a
+function). For input and output parameters, the temporary is initialized from
+the lvalue argument expression through implicit or explicit casting from the
+lvalue argument type to the parameter type.
+
+On return of the function, the values of any parameter temporaries are written
+back to the argument expression through an inverted conversion sequence (if an
+``out`` parameter was not initialized in the function, the uninitialized value
+may be written back).
+
+Parameters of constant-sized array type, are also passed with value semantics.
+This requires input parameters of arrays to construct temporaries and the
+temporaries go through array-to-pointer decay when initializing parameters.
+
+Implementations are allowed to avoid unnecessary temporaries, and HLSL's strict
+no-alias rules can enable some trivial optimizations.
+
+Array Temporaries
+-
+
+Given the following example:
+
+.. code-block:: c++
+
+  void fn(float a[4]) {
+a[0] = a[1] + a[2] + a[3];
+  }
+
+  float4 main() : SV_Target {
+float arr[4] = {1, 1, 1, 1};
+fn(arr);
+return float4(a[0], a[1], a[2], a[3]);
+  }
+
+In C or C++, the array parameter decays to a pointer, so after the call to
+``fn``, the value of ``a[0]`` is ``3``. In HLSL, the array is passed by value,
+so modifications inside ``fn`` do not propagate out.
+
+.. note::
+
+  DXC supports unsized arrays passed directly as decayed pointers, which is an
+  unfortunate behavior divergence.

llvm-beanz wrote:

I filed an issue on [HLSL 
Specs](https://github.com/microsoft/hlsl-specs/issues/141) to track considering 
approaches for unsized arrays at the language level.

https://github.com/llvm/llvm-project/pull/75397
___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[clang] [HLSL][Docs] Add documentation for HLSL functions (PR #75397)

[Chris B via cfe-commits]

@@ -0,0 +1,316 @@
+===
+HLSL Function Calls
+===
+
+.. contents::
+   :local:
+
+Introduction
+
+
+This document describes the design and implementation of HLSL's function call
+semantics in Clang. This includes details related to argument conversion and
+parameter lifetimes.
+
+This document does not seek to serve as official documentation for HLSL's
+call semantics, but does provide an overview to assist a reader. The
+authoritative documentation for HLSL's language semantics is the `draft 
language
+specification `_.
+
+Argument Semantics
+==
+
+In HLSL, all function arguments are passed by value in and out of functions.
+HLSL has 3 keywords which denote the parameter semantics (``in``, ``out`` and
+``inout``). In a function declaration a parameter may be annotated any of the
+following ways:
+
+#.  - denotes input
+#. ``in`` - denotes input
+#. ``out`` - denotes output
+#. ``in out`` - denotes input and output
+#. ``out in`` - denotes input and output
+#. ``inout`` - denotes input and output
+
+Parameters that are exclusively input behave like C/C++ parameters that are
+passed by value.
+
+For parameters that are output (or input and output), a temporary value is
+created in the caller. The temporary value is then passed by-address. For
+output-only parameters, the temporary is uninitialized when passed (it is
+undefined behavior to not explicitly initialize an ``out`` parameter inside a
+function). For input and output parameters, the temporary is initialized from
+the lvalue argument expression through implicit or explicit casting from the
+lvalue argument type to the parameter type.
+
+On return of the function, the values of any parameter temporaries are written
+back to the argument expression through an inverted conversion sequence (if an
+``out`` parameter was not initialized in the function, the uninitialized value
+may be written back).
+
+Parameters of constant-sized array type, are also passed with value semantics.
+This requires input parameters of arrays to construct temporaries and the
+temporaries go through array-to-pointer decay when initializing parameters.
+
+Implementations are allowed to avoid unnecessary temporaries, and HLSL's strict
+no-alias rules can enable some trivial optimizations.
+
+Array Temporaries
+-
+
+Given the following example:
+
+.. code-block:: c++
+
+  void fn(float a[4]) {
+a[0] = a[1] + a[2] + a[3];
+  }
+
+  float4 main() : SV_Target {
+float arr[4] = {1, 1, 1, 1};
+fn(arr);
+return float4(a[0], a[1], a[2], a[3]);
+  }
+
+In C or C++, the array parameter decays to a pointer, so after the call to
+``fn``, the value of ``a[0]`` is ``3``. In HLSL, the array is passed by value,
+so modifications inside ``fn`` do not propagate out.
+
+.. note::
+
+  DXC supports unsized arrays passed directly as decayed pointers, which is an
+  unfortunate behavior divergence.

llvm-beanz wrote:

I agree that we should remove these from the language, but I think our current 
implementation needs to assume that they are around since... they are.

https://github.com/llvm/llvm-project/pull/75397
___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[clang] [HLSL][Docs] Add documentation for HLSL functions (PR #75397)

[Tex Riddell via cfe-commits]

@@ -0,0 +1,316 @@
+===
+HLSL Function Calls
+===
+
+.. contents::
+   :local:
+
+Introduction
+
+
+This document describes the design and implementation of HLSL's function call
+semantics in Clang. This includes details related to argument conversion and
+parameter lifetimes.
+
+This document does not seek to serve as official documentation for HLSL's
+call semantics, but does provide an overview to assist a reader. The
+authoritative documentation for HLSL's language semantics is the `draft 
language
+specification `_.
+
+Argument Semantics
+==
+
+In HLSL, all function arguments are passed by value in and out of functions.
+HLSL has 3 keywords which denote the parameter semantics (``in``, ``out`` and
+``inout``). In a function declaration a parameter may be annotated any of the
+following ways:
+
+#.  - denotes input
+#. ``in`` - denotes input
+#. ``out`` - denotes output
+#. ``in out`` - denotes input and output
+#. ``out in`` - denotes input and output
+#. ``inout`` - denotes input and output
+
+Parameters that are exclusively input behave like C/C++ parameters that are
+passed by value.
+
+For parameters that are output (or input and output), a temporary value is
+created in the caller. The temporary value is then passed by-address. For
+output-only parameters, the temporary is uninitialized when passed (if the
+parameter is not explicitly initialized inside the function an undefined value
+is stored back to the argument expression). For input and output parameters, 
the
+temporary is initialized from  the lvalue argument expression through implicit
+or explicit casting from the lvalue argument type to the parameter type.
+
+On return of the function, the values of any parameter temporaries are written
+back to the argument expression through an inverted conversion sequence (if an
+``out`` parameter was not initialized in the function, the uninitialized value
+may be written back).
+
+Parameters of constant-sized array type, are also passed with value semantics.
+This requires input parameters of arrays to construct temporaries and the
+temporaries go through array-to-pointer decay when initializing parameters.
+
+Implementations are allowed to avoid unnecessary temporaries, and HLSL's strict
+no-alias rules can enable some trivial optimizations.
+
+Array Temporaries
+-
+
+Given the following example:
+
+.. code-block:: c++
+
+  void fn(float a[4]) {
+a[0] = a[1] + a[2] + a[3];
+  }
+
+  float4 main() : SV_Target {
+float arr[4] = {1, 1, 1, 1};
+fn(arr);
+return float4(arr[0], arr[1], arr[2], arr[3]);
+  }
+
+In C or C++, the array parameter decays to a pointer, so after the call to
+``fn``, the value of ``arr[0]`` is ``3``. In HLSL, the array is passed by 
value,
+so modifications inside ``fn`` do not propagate out.
+
+.. note::
+
+  DXC supports unsized arrays passed directly as decayed pointers, which is an
+  unfortunate behavior divergence.
+
+Out Parameter Temporaries
+-
+
+.. code-block:: c++
+
+  void Init(inout int X, inout int Y) {
+Y = 2;
+X = 1;
+  }
+
+  void main() {
+int V;
+Init(V, V); // MSVC ABI V == 2, Itanium V == 1
+  }
+
+In the above example the ``Init`` function's behavior depends on the C++ ABI
+implementation. In the MSVC C++ ABI (used for the HLSL DXIL target), call
+arguments are emitted right-to-left and destroyed left-to-right. This means 
that
+the parameter initialization and destruction occurs in the order: {``Y``,
+``X``, ``~X``, ``~Y``}. This causes the write-back of the value of ``Y`` to 
occur
+last, so the resulting value of ``V`` is ``2``. In the Itanium C++ ABI, the
+parameter ordering is reversed, so the initialization and destruction occurs in
+the order: {``X``, ``Y``, ``~Y``, ``X``}. This causes the write-back of the
+value ``X`` to occur last, resulting in the value of ``V`` being set to ``1``.
+
+.. code-block:: c++
+
+  void Trunc(inout int3 V) { }
+
+
+  void main() {
+float3 F = {1.5, 2.6, 3.3};
+Trunc(F); // F == {1.0, 2.0, 3.0}
+  }
+
+In the above example, the argument expression ``F`` undergoes element-wise
+conversion from a float vector to an integer vector to create a temporary
+``int3``. On expiration the temporary undergoes elementwise conversion back to
+the floating point vector type ``float3``. This results in an implicit
+truncation of the vector even if the value is unused in the function.
+
+
+.. code-block:: c++
+
+  void UB(out int X) {}
+
+  void main() {
+int X = 7;
+UB(X); // X is undefined!
+  }
+
+In this example an initialized value is passed to an ``out`` parameter.
+Parameters marked ``out`` are not initialized by the argument expression or
+implicitly by the function. They must be explicitly initialized. In this case
+the argument is not initialized in the function so the temporary is still
+uninitialized when 

[clang] [HLSL][Docs] Add documentation for HLSL functions (PR #75397)

[Tex Riddell via cfe-commits]

@@ -0,0 +1,316 @@
+===
+HLSL Function Calls
+===
+
+.. contents::
+   :local:
+
+Introduction
+
+
+This document describes the design and implementation of HLSL's function call
+semantics in Clang. This includes details related to argument conversion and
+parameter lifetimes.
+
+This document does not seek to serve as official documentation for HLSL's
+call semantics, but does provide an overview to assist a reader. The
+authoritative documentation for HLSL's language semantics is the `draft 
language
+specification `_.
+
+Argument Semantics
+==
+
+In HLSL, all function arguments are passed by value in and out of functions.
+HLSL has 3 keywords which denote the parameter semantics (``in``, ``out`` and
+``inout``). In a function declaration a parameter may be annotated any of the
+following ways:
+
+#.  - denotes input
+#. ``in`` - denotes input
+#. ``out`` - denotes output
+#. ``in out`` - denotes input and output
+#. ``out in`` - denotes input and output
+#. ``inout`` - denotes input and output
+
+Parameters that are exclusively input behave like C/C++ parameters that are
+passed by value.
+
+For parameters that are output (or input and output), a temporary value is
+created in the caller. The temporary value is then passed by-address. For
+output-only parameters, the temporary is uninitialized when passed (if the
+parameter is not explicitly initialized inside the function an undefined value
+is stored back to the argument expression). For input and output parameters, 
the
+temporary is initialized from  the lvalue argument expression through implicit
+or explicit casting from the lvalue argument type to the parameter type.
+
+On return of the function, the values of any parameter temporaries are written
+back to the argument expression through an inverted conversion sequence (if an
+``out`` parameter was not initialized in the function, the uninitialized value
+may be written back).
+
+Parameters of constant-sized array type, are also passed with value semantics.
+This requires input parameters of arrays to construct temporaries and the
+temporaries go through array-to-pointer decay when initializing parameters.
+
+Implementations are allowed to avoid unnecessary temporaries, and HLSL's strict
+no-alias rules can enable some trivial optimizations.
+
+Array Temporaries
+-
+
+Given the following example:
+
+.. code-block:: c++
+
+  void fn(float a[4]) {
+a[0] = a[1] + a[2] + a[3];
+  }
+
+  float4 main() : SV_Target {
+float arr[4] = {1, 1, 1, 1};
+fn(arr);
+return float4(arr[0], arr[1], arr[2], arr[3]);
+  }
+
+In C or C++, the array parameter decays to a pointer, so after the call to
+``fn``, the value of ``arr[0]`` is ``3``. In HLSL, the array is passed by 
value,
+so modifications inside ``fn`` do not propagate out.
+
+.. note::
+
+  DXC supports unsized arrays passed directly as decayed pointers, which is an
+  unfortunate behavior divergence.
+
+Out Parameter Temporaries
+-
+
+.. code-block:: c++
+
+  void Init(inout int X, inout int Y) {
+Y = 2;
+X = 1;
+  }
+
+  void main() {
+int V;
+Init(V, V); // MSVC ABI V == 2, Itanium V == 1
+  }
+
+In the above example the ``Init`` function's behavior depends on the C++ ABI
+implementation. In the MSVC C++ ABI (used for the HLSL DXIL target), call
+arguments are emitted right-to-left and destroyed left-to-right. This means 
that
+the parameter initialization and destruction occurs in the order: {``Y``,
+``X``, ``~X``, ``~Y``}. This causes the write-back of the value of ``Y`` to 
occur
+last, so the resulting value of ``V`` is ``2``. In the Itanium C++ ABI, the
+parameter ordering is reversed, so the initialization and destruction occurs in
+the order: {``X``, ``Y``, ``~Y``, ``X``}. This causes the write-back of the
+value ``X`` to occur last, resulting in the value of ``V`` being set to ``1``.
+
+.. code-block:: c++
+
+  void Trunc(inout int3 V) { }
+
+
+  void main() {
+float3 F = {1.5, 2.6, 3.3};
+Trunc(F); // F == {1.0, 2.0, 3.0}
+  }
+
+In the above example, the argument expression ``F`` undergoes element-wise
+conversion from a float vector to an integer vector to create a temporary
+``int3``. On expiration the temporary undergoes elementwise conversion back to
+the floating point vector type ``float3``. This results in an implicit
+truncation of the vector even if the value is unused in the function.

tex3d wrote:

This results in an implicit float to int conversion for each component of the 
vector, not a vector truncation (which would be a reduction in the size of the 
vector).

https://github.com/llvm/llvm-project/pull/75397
___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[clang] [HLSL][Docs] Add documentation for HLSL functions (PR #75397)

[Tex Riddell via cfe-commits]

@@ -0,0 +1,316 @@
+===
+HLSL Function Calls
+===
+
+.. contents::
+   :local:
+
+Introduction
+
+
+This document describes the design and implementation of HLSL's function call
+semantics in Clang. This includes details related to argument conversion and
+parameter lifetimes.
+
+This document does not seek to serve as official documentation for HLSL's
+call semantics, but does provide an overview to assist a reader. The
+authoritative documentation for HLSL's language semantics is the `draft 
language
+specification `_.
+
+Argument Semantics
+==
+
+In HLSL, all function arguments are passed by value in and out of functions.
+HLSL has 3 keywords which denote the parameter semantics (``in``, ``out`` and
+``inout``). In a function declaration a parameter may be annotated any of the
+following ways:
+
+#.  - denotes input
+#. ``in`` - denotes input
+#. ``out`` - denotes output
+#. ``in out`` - denotes input and output
+#. ``out in`` - denotes input and output
+#. ``inout`` - denotes input and output
+
+Parameters that are exclusively input behave like C/C++ parameters that are
+passed by value.
+
+For parameters that are output (or input and output), a temporary value is
+created in the caller. The temporary value is then passed by-address. For
+output-only parameters, the temporary is uninitialized when passed (it is
+undefined behavior to not explicitly initialize an ``out`` parameter inside a
+function). For input and output parameters, the temporary is initialized from
+the lvalue argument expression through implicit or explicit casting from the
+lvalue argument type to the parameter type.
+
+On return of the function, the values of any parameter temporaries are written
+back to the argument expression through an inverted conversion sequence (if an
+``out`` parameter was not initialized in the function, the uninitialized value
+may be written back).
+
+Parameters of constant-sized array type, are also passed with value semantics.
+This requires input parameters of arrays to construct temporaries and the
+temporaries go through array-to-pointer decay when initializing parameters.
+
+Implementations are allowed to avoid unnecessary temporaries, and HLSL's strict
+no-alias rules can enable some trivial optimizations.
+
+Array Temporaries
+-
+
+Given the following example:
+
+.. code-block:: c++
+
+  void fn(float a[4]) {
+a[0] = a[1] + a[2] + a[3];
+  }
+
+  float4 main() : SV_Target {
+float arr[4] = {1, 1, 1, 1};
+fn(arr);
+return float4(a[0], a[1], a[2], a[3]);
+  }
+
+In C or C++, the array parameter decays to a pointer, so after the call to
+``fn``, the value of ``a[0]`` is ``3``. In HLSL, the array is passed by value,
+so modifications inside ``fn`` do not propagate out.
+
+.. note::
+
+  DXC supports unsized arrays passed directly as decayed pointers, which is an
+  unfortunate behavior divergence.

tex3d wrote:

Well, not reliably.  This area is weird and buggy, in both DXC and FXC.  This 
was originally supported in DXC because it appeared that FXC supported it.  
However, support of unsized array parameters in FXC was limited to resource 
arrays (and only on SM 5.1).  These can also be buggy in FXC, with differences 
in behavior between SM 5.0 and SM 5.1.

In DXC, use of unsized arrays can lead to asserts or crashes.  The primary area 
where they are likely to be useful is when passing an unbounded resource array 
to a function, where you do not want a copy of the resource handles, but want 
the original resource range declared globally to be passed to a function and 
indexed there.  This scenario works for SM 5.1 in FXC, but appears to assert in 
DXC.

For these reasons, we should consider removing support for them in DXC.

https://github.com/llvm/llvm-project/pull/75397
___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[clang] [HLSL][Docs] Add documentation for HLSL functions (PR #75397)

[Chris B via cfe-commits]

https://github.com/llvm-beanz updated 
https://github.com/llvm/llvm-project/pull/75397

>From 4ebc0c58dc751f422de85b0909636cb1a87f8ce4 Mon Sep 17 00:00:00 2001
From: Chris Bieneman 
Date: Wed, 13 Dec 2023 16:44:09 -0600
Subject: [PATCH 1/3] [HLSL][Docs] Add documentation for HLSL functions

This adds a new document that covers the HLSL approach to function
calls and parameter semantics. At time of writing this document is a
proposal for the implementation.
---
 clang/docs/HLSL/FunctionCalls.rst | 316 ++
 clang/docs/HLSL/HLSLDocs.rst  |   1 +
 2 files changed, 317 insertions(+)
 create mode 100644 clang/docs/HLSL/FunctionCalls.rst

diff --git a/clang/docs/HLSL/FunctionCalls.rst 
b/clang/docs/HLSL/FunctionCalls.rst
new file mode 100644
index 00..e62b249e011a94
--- /dev/null
+++ b/clang/docs/HLSL/FunctionCalls.rst
@@ -0,0 +1,316 @@
+===
+HLSL Function Calls
+===
+
+.. contents::
+   :local:
+
+Introduction
+
+
+This document descries the design and implementation of HLSL's function call
+semantics in Clang. This includes details related to argument conversion and
+parameter lifetimes.
+
+This document does not seek to serve as official documentation for HLSL's
+call semantics, but does provide an overview to assist a reader. The
+authoritative documentation for HLSL's language semantics is the `draft 
language
+specification `_.
+
+Argument Semantics
+==
+
+In HLSL, all function arguments are passed by value in and out of functions.
+HLSL has 3 keywords which denote the parameter semantics (``in``, ``out`` and
+``inout``). In a function declaration a parameter may be annotated any of the
+following ways:
+
+#.  - denotes input
+#. ``in`` - denotes input
+#. ``out`` - denotes output
+#. ``in out`` - denotes input and output
+#. ``out in`` - denotes input and output
+#. ``inout`` - denotes input and output
+
+Parameters that are exclusively input behave like C/C++ parameters that are
+passed by value.
+
+For parameters that are output (or input and output), a temporary value is
+created in the caller. The temporary value is then passed by-address. For
+output-only parameters, the temporary is uninitialized when passed (it is
+undefined behavior to not explicitly initialize an ``out`` parameter inside a
+function). For input and output parameters, the temporary is initialized from
+the lvalue argument expression through implicit or explicit casting from the
+lvalue argument type to the parameter type.
+
+On return of the function, the values of any parameter temporaries are written
+back to the argument expression through an inverted conversion sequence (if an
+``out`` parameter was not initialized in the function, the uninitialized value
+may be written back).
+
+Parameters of constant-sized array type, are also passed with value semantics.
+This requires input parameters of arrays to construct temporaries and the
+temporaries go through array-to-pointer decay when initializing parameters.
+
+Implementations are allowed to avoid unnecessary temporaries, and HLSL's strict
+no-alias rules can enable some trivial optimizations.
+
+Array Temporaries
+-
+
+Given the following example:
+
+.. code-block:: c++
+
+  void fn(float a[4]) {
+a[0] = a[1] + a[2] + a[3];
+  }
+
+  float4 main() : SV_Target {
+float arr[4] = {1, 1, 1, 1};
+fn(arr);
+return float4(a[0], a[1], a[2], a[3]);
+  }
+
+In C or C++, the array parameter decays to a pointer, so after the call to
+``fn``, the value of ``a[0]`` is ``3``. In HLSL, the array is passed by value,
+so modifications inside ``fn`` do not propagate out.
+
+.. note::
+
+  DXC supports unsized arrays passed directly as decayed pointers, which is an
+  unfortunate behavior divergence.
+
+Out Parameter Temporaries
+-
+
+.. code-block:: c++
+
+  void Init(inout int X, inout int Y) {
+Y = 2;
+X = 1;
+  }
+
+  void main() {
+int V;
+Init(V, V); // MSVC ABI V == 2, Itanium V == 1
+  }
+
+In the above example the ``Init`` function's behavior depends on the C++ ABI
+implementation. In the MSVC C++ ABI (used for the HLSL DXIL target), call
+arguments are emitted right-to-left and destroyed left-to-right. This means 
that
+the parameter initialization and destruction occurs in the order: {``Y``,
+``X``, ``~X``, ``~Y``}. This causes the write-back of the value of ``Y`` to 
occur
+last, so the resulting value of ``V`` is ``2``. In the Itanium C++ ABI, the
+parameter ordering is reversed, so the initialization and destruction occurs in
+the order: {``X``, ``Y``, ``~Y``, ``X``}. This causes the write-back of the
+value ``X`` to occur last, resulting in the value of ``V`` being set to ``1``.
+
+.. code-block:: c++
+
+  void Trunc(inout int3 V) { }
+
+
+  void main() {
+float3 F = {1.5, 2.6, 3.3};
+Trunc(F); // F == {1.0, 2.0, 3.0}
+  }
+
+In the above example, 

[clang] [HLSL][Docs] Add documentation for HLSL functions (PR #75397)

[Chris B via cfe-commits]

@@ -0,0 +1,316 @@
+===
+HLSL Function Calls
+===
+
+.. contents::
+   :local:
+
+Introduction
+
+
+This document describes the design and implementation of HLSL's function call
+semantics in Clang. This includes details related to argument conversion and
+parameter lifetimes.
+
+This document does not seek to serve as official documentation for HLSL's
+call semantics, but does provide an overview to assist a reader. The
+authoritative documentation for HLSL's language semantics is the `draft 
language
+specification `_.
+
+Argument Semantics
+==
+
+In HLSL, all function arguments are passed by value in and out of functions.
+HLSL has 3 keywords which denote the parameter semantics (``in``, ``out`` and
+``inout``). In a function declaration a parameter may be annotated any of the
+following ways:
+
+#.  - denotes input
+#. ``in`` - denotes input
+#. ``out`` - denotes output
+#. ``in out`` - denotes input and output
+#. ``out in`` - denotes input and output
+#. ``inout`` - denotes input and output
+
+Parameters that are exclusively input behave like C/C++ parameters that are
+passed by value.
+
+For parameters that are output (or input and output), a temporary value is
+created in the caller. The temporary value is then passed by-address. For
+output-only parameters, the temporary is uninitialized when passed (it is
+undefined behavior to not explicitly initialize an ``out`` parameter inside a
+function). For input and output parameters, the temporary is initialized from
+the lvalue argument expression through implicit or explicit casting from the
+lvalue argument type to the parameter type.
+
+On return of the function, the values of any parameter temporaries are written
+back to the argument expression through an inverted conversion sequence (if an
+``out`` parameter was not initialized in the function, the uninitialized value
+may be written back).
+
+Parameters of constant-sized array type, are also passed with value semantics.
+This requires input parameters of arrays to construct temporaries and the
+temporaries go through array-to-pointer decay when initializing parameters.
+
+Implementations are allowed to avoid unnecessary temporaries, and HLSL's strict
+no-alias rules can enable some trivial optimizations.
+
+Array Temporaries
+-
+
+Given the following example:
+
+.. code-block:: c++
+
+  void fn(float a[4]) {
+a[0] = a[1] + a[2] + a[3];
+  }
+
+  float4 main() : SV_Target {
+float arr[4] = {1, 1, 1, 1};
+fn(arr);
+return float4(a[0], a[1], a[2], a[3]);

llvm-beanz wrote:

doh!

https://github.com/llvm/llvm-project/pull/75397
___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[clang] [HLSL][Docs] Add documentation for HLSL functions (PR #75397)

[Tex Riddell via cfe-commits]

@@ -0,0 +1,316 @@
+===
+HLSL Function Calls
+===
+
+.. contents::
+   :local:
+
+Introduction
+
+
+This document describes the design and implementation of HLSL's function call
+semantics in Clang. This includes details related to argument conversion and
+parameter lifetimes.
+
+This document does not seek to serve as official documentation for HLSL's
+call semantics, but does provide an overview to assist a reader. The
+authoritative documentation for HLSL's language semantics is the `draft 
language
+specification `_.
+
+Argument Semantics
+==
+
+In HLSL, all function arguments are passed by value in and out of functions.
+HLSL has 3 keywords which denote the parameter semantics (``in``, ``out`` and
+``inout``). In a function declaration a parameter may be annotated any of the
+following ways:
+
+#.  - denotes input
+#. ``in`` - denotes input
+#. ``out`` - denotes output
+#. ``in out`` - denotes input and output
+#. ``out in`` - denotes input and output
+#. ``inout`` - denotes input and output
+
+Parameters that are exclusively input behave like C/C++ parameters that are
+passed by value.
+
+For parameters that are output (or input and output), a temporary value is
+created in the caller. The temporary value is then passed by-address. For
+output-only parameters, the temporary is uninitialized when passed (it is
+undefined behavior to not explicitly initialize an ``out`` parameter inside a
+function). For input and output parameters, the temporary is initialized from
+the lvalue argument expression through implicit or explicit casting from the
+lvalue argument type to the parameter type.
+
+On return of the function, the values of any parameter temporaries are written
+back to the argument expression through an inverted conversion sequence (if an
+``out`` parameter was not initialized in the function, the uninitialized value
+may be written back).
+
+Parameters of constant-sized array type, are also passed with value semantics.
+This requires input parameters of arrays to construct temporaries and the
+temporaries go through array-to-pointer decay when initializing parameters.
+
+Implementations are allowed to avoid unnecessary temporaries, and HLSL's strict
+no-alias rules can enable some trivial optimizations.
+
+Array Temporaries
+-
+
+Given the following example:
+
+.. code-block:: c++
+
+  void fn(float a[4]) {
+a[0] = a[1] + a[2] + a[3];
+  }
+
+  float4 main() : SV_Target {
+float arr[4] = {1, 1, 1, 1};
+fn(arr);
+return float4(a[0], a[1], a[2], a[3]);
+  }
+
+In C or C++, the array parameter decays to a pointer, so after the call to
+``fn``, the value of ``a[0]`` is ``3``. In HLSL, the array is passed by value,

tex3d wrote:

Shouldn't this say: "the value of `arr[0]` is `3`"?  (wrong array again)

https://github.com/llvm/llvm-project/pull/75397
___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[clang] [HLSL][Docs] Add documentation for HLSL functions (PR #75397)

[Tex Riddell via cfe-commits]

@@ -0,0 +1,316 @@
+===
+HLSL Function Calls
+===
+
+.. contents::
+   :local:
+
+Introduction
+
+
+This document describes the design and implementation of HLSL's function call
+semantics in Clang. This includes details related to argument conversion and
+parameter lifetimes.
+
+This document does not seek to serve as official documentation for HLSL's
+call semantics, but does provide an overview to assist a reader. The
+authoritative documentation for HLSL's language semantics is the `draft 
language
+specification `_.
+
+Argument Semantics
+==
+
+In HLSL, all function arguments are passed by value in and out of functions.
+HLSL has 3 keywords which denote the parameter semantics (``in``, ``out`` and
+``inout``). In a function declaration a parameter may be annotated any of the
+following ways:
+
+#.  - denotes input
+#. ``in`` - denotes input
+#. ``out`` - denotes output
+#. ``in out`` - denotes input and output
+#. ``out in`` - denotes input and output
+#. ``inout`` - denotes input and output
+
+Parameters that are exclusively input behave like C/C++ parameters that are
+passed by value.
+
+For parameters that are output (or input and output), a temporary value is
+created in the caller. The temporary value is then passed by-address. For
+output-only parameters, the temporary is uninitialized when passed (it is
+undefined behavior to not explicitly initialize an ``out`` parameter inside a
+function). For input and output parameters, the temporary is initialized from
+the lvalue argument expression through implicit or explicit casting from the
+lvalue argument type to the parameter type.
+
+On return of the function, the values of any parameter temporaries are written
+back to the argument expression through an inverted conversion sequence (if an
+``out`` parameter was not initialized in the function, the uninitialized value
+may be written back).
+
+Parameters of constant-sized array type, are also passed with value semantics.
+This requires input parameters of arrays to construct temporaries and the
+temporaries go through array-to-pointer decay when initializing parameters.
+
+Implementations are allowed to avoid unnecessary temporaries, and HLSL's strict
+no-alias rules can enable some trivial optimizations.
+
+Array Temporaries
+-
+
+Given the following example:
+
+.. code-block:: c++
+
+  void fn(float a[4]) {
+a[0] = a[1] + a[2] + a[3];
+  }
+
+  float4 main() : SV_Target {
+float arr[4] = {1, 1, 1, 1};
+fn(arr);
+return float4(a[0], a[1], a[2], a[3]);

tex3d wrote:

`return float4(a[0], a[1], a[2], a[3]);` references the wrong array.  It should 
be `arr[0], ...`, right?

https://github.com/llvm/llvm-project/pull/75397
___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[clang] [HLSL][Docs] Add documentation for HLSL functions (PR #75397)

[Tex Riddell via cfe-commits]

@@ -0,0 +1,316 @@
+===
+HLSL Function Calls
+===
+
+.. contents::
+   :local:
+
+Introduction
+
+
+This document describes the design and implementation of HLSL's function call
+semantics in Clang. This includes details related to argument conversion and
+parameter lifetimes.
+
+This document does not seek to serve as official documentation for HLSL's
+call semantics, but does provide an overview to assist a reader. The
+authoritative documentation for HLSL's language semantics is the `draft 
language
+specification `_.
+
+Argument Semantics
+==
+
+In HLSL, all function arguments are passed by value in and out of functions.
+HLSL has 3 keywords which denote the parameter semantics (``in``, ``out`` and
+``inout``). In a function declaration a parameter may be annotated any of the
+following ways:
+
+#.  - denotes input
+#. ``in`` - denotes input
+#. ``out`` - denotes output
+#. ``in out`` - denotes input and output
+#. ``out in`` - denotes input and output
+#. ``inout`` - denotes input and output
+
+Parameters that are exclusively input behave like C/C++ parameters that are
+passed by value.
+
+For parameters that are output (or input and output), a temporary value is
+created in the caller. The temporary value is then passed by-address. For
+output-only parameters, the temporary is uninitialized when passed (it is
+undefined behavior to not explicitly initialize an ``out`` parameter inside a
+function). For input and output parameters, the temporary is initialized from

tex3d wrote:

> (it is undefined behavior to not explicitly initialize an ``out`` parameter 
> inside a function)

Perhaps it's better to say that an out parameter has an undefined value if not 
initialized inside the function, rather than this being considered undefined 
**_behavior_**?

https://github.com/llvm/llvm-project/pull/75397
___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[clang] [HLSL][Docs] Add documentation for HLSL functions (PR #75397)

[Chris B via cfe-commits]

https://github.com/llvm-beanz updated 
https://github.com/llvm/llvm-project/pull/75397

>From 4ebc0c58dc751f422de85b0909636cb1a87f8ce4 Mon Sep 17 00:00:00 2001
From: Chris Bieneman 
Date: Wed, 13 Dec 2023 16:44:09 -0600
Subject: [PATCH 1/2] [HLSL][Docs] Add documentation for HLSL functions

This adds a new document that covers the HLSL approach to function
calls and parameter semantics. At time of writing this document is a
proposal for the implementation.
---
 clang/docs/HLSL/FunctionCalls.rst | 316 ++
 clang/docs/HLSL/HLSLDocs.rst  |   1 +
 2 files changed, 317 insertions(+)
 create mode 100644 clang/docs/HLSL/FunctionCalls.rst

diff --git a/clang/docs/HLSL/FunctionCalls.rst 
b/clang/docs/HLSL/FunctionCalls.rst
new file mode 100644
index 00..e62b249e011a94
--- /dev/null
+++ b/clang/docs/HLSL/FunctionCalls.rst
@@ -0,0 +1,316 @@
+===
+HLSL Function Calls
+===
+
+.. contents::
+   :local:
+
+Introduction
+
+
+This document descries the design and implementation of HLSL's function call
+semantics in Clang. This includes details related to argument conversion and
+parameter lifetimes.
+
+This document does not seek to serve as official documentation for HLSL's
+call semantics, but does provide an overview to assist a reader. The
+authoritative documentation for HLSL's language semantics is the `draft 
language
+specification `_.
+
+Argument Semantics
+==
+
+In HLSL, all function arguments are passed by value in and out of functions.
+HLSL has 3 keywords which denote the parameter semantics (``in``, ``out`` and
+``inout``). In a function declaration a parameter may be annotated any of the
+following ways:
+
+#.  - denotes input
+#. ``in`` - denotes input
+#. ``out`` - denotes output
+#. ``in out`` - denotes input and output
+#. ``out in`` - denotes input and output
+#. ``inout`` - denotes input and output
+
+Parameters that are exclusively input behave like C/C++ parameters that are
+passed by value.
+
+For parameters that are output (or input and output), a temporary value is
+created in the caller. The temporary value is then passed by-address. For
+output-only parameters, the temporary is uninitialized when passed (it is
+undefined behavior to not explicitly initialize an ``out`` parameter inside a
+function). For input and output parameters, the temporary is initialized from
+the lvalue argument expression through implicit or explicit casting from the
+lvalue argument type to the parameter type.
+
+On return of the function, the values of any parameter temporaries are written
+back to the argument expression through an inverted conversion sequence (if an
+``out`` parameter was not initialized in the function, the uninitialized value
+may be written back).
+
+Parameters of constant-sized array type, are also passed with value semantics.
+This requires input parameters of arrays to construct temporaries and the
+temporaries go through array-to-pointer decay when initializing parameters.
+
+Implementations are allowed to avoid unnecessary temporaries, and HLSL's strict
+no-alias rules can enable some trivial optimizations.
+
+Array Temporaries
+-
+
+Given the following example:
+
+.. code-block:: c++
+
+  void fn(float a[4]) {
+a[0] = a[1] + a[2] + a[3];
+  }
+
+  float4 main() : SV_Target {
+float arr[4] = {1, 1, 1, 1};
+fn(arr);
+return float4(a[0], a[1], a[2], a[3]);
+  }
+
+In C or C++, the array parameter decays to a pointer, so after the call to
+``fn``, the value of ``a[0]`` is ``3``. In HLSL, the array is passed by value,
+so modifications inside ``fn`` do not propagate out.
+
+.. note::
+
+  DXC supports unsized arrays passed directly as decayed pointers, which is an
+  unfortunate behavior divergence.
+
+Out Parameter Temporaries
+-
+
+.. code-block:: c++
+
+  void Init(inout int X, inout int Y) {
+Y = 2;
+X = 1;
+  }
+
+  void main() {
+int V;
+Init(V, V); // MSVC ABI V == 2, Itanium V == 1
+  }
+
+In the above example the ``Init`` function's behavior depends on the C++ ABI
+implementation. In the MSVC C++ ABI (used for the HLSL DXIL target), call
+arguments are emitted right-to-left and destroyed left-to-right. This means 
that
+the parameter initialization and destruction occurs in the order: {``Y``,
+``X``, ``~X``, ``~Y``}. This causes the write-back of the value of ``Y`` to 
occur
+last, so the resulting value of ``V`` is ``2``. In the Itanium C++ ABI, the
+parameter ordering is reversed, so the initialization and destruction occurs in
+the order: {``X``, ``Y``, ``~Y``, ``X``}. This causes the write-back of the
+value ``X`` to occur last, resulting in the value of ``V`` being set to ``1``.
+
+.. code-block:: c++
+
+  void Trunc(inout int3 V) { }
+
+
+  void main() {
+float3 F = {1.5, 2.6, 3.3};
+Trunc(F); // F == {1.0, 2.0, 3.0}
+  }
+
+In the above example, 

[clang] [HLSL][Docs] Add documentation for HLSL functions (PR #75397)

[Chris B via cfe-commits]

@@ -0,0 +1,300 @@
+===
+HLSL Function Calls
+===
+
+.. contents::
+   :local:
+
+Introduction
+
+
+This document descries the design and implementation of HLSL's function call
+semantics in Clang. This includes details related to argument conversion and
+parameter lifetimes.
+
+This document does not seek to serve as official documentation for HLSL's
+call semantics, but does provide an overview to assist a reader. The
+authoritative documentation for HLSL's language semantics is the `draft 
language
+specification`_.
+
+Argument Semantics
+==
+
+In HLSL, all function arguments are passed by value in and out of functions.
+HLSL has 3 keywords which denote the parameter semantics (``in``, ``out`` and
+``inout``). In a function declaration a parameter may be annotated any of the
+following ways:
+
+#.  - denotes input
+#. ``in`` - denotes input
+#. ``out`` - denotes output
+#. ``in out`` - denotes input and output
+#. ``out in`` - denotes input and output
+#. ``inout`` - denotes input and output
+
+Parameters that are exclusively input behave like C/C++ parameters that are
+passed by value.
+
+For parameters that are output (or input and output), a temporary value is
+created in the caller. The temporary value is then passed by-address. For
+output-only parameters, the temporary is uninitialized when passed (it is
+undefined behavior to not explicitly initialize an ``out`` parameter inside a
+function). For input and output parameters, the temporary is initialized from
+the lvalue argument expression through implicit or explicit casting from the
+lvalue argument type to the parameter type.
+
+On return of the function, the values of any parameter temporaries are written
+back to the argument expression through an inverted conversion sequence (if an
+``out`` parameter was not initialized in the function, the uninitialized value
+may be written back).
+
+Parameters of constant-sized array type, are also passed with value semantics.
+This requires input parameters of arrays to construct temporaries and the
+temporaries go through array-to-pointer decay when initializing parameters.
+
+Implementations are allowed to avoid unnecessary temporaries, and HLSL's strict
+no-alias rules can enable some trivial optimizations.
+
+Array Temporaries
+-
+
+Given the following example:
+
+.. code-block:: c++
+  void fn(float a[4]) {
+a[0] = a[1] + a[2] + a[3];
+  }
+
+  float4 main() : SV_Target {
+float arr[4] = {1, 1, 1, 1};
+fn(arr);
+return float4(a[0], a[1], a[2], a[3]);
+  }
+
+In C or C++, the array parameter decays to a pointer, so after the call to
+``fn``, the value of ``a[0]`` is ``3``. In HLSL, the array is passed by value,
+so modifications inside ``fn`` do not propagate out.
+
+.. note::
+  DXC supports unsized arrays passed directly as decayed pointers, which is an
+  unfortunate behavior divergence.
+
+Out Parameter Temporaries
+-
+
+.. code-block:: c++
+  void Init(inout int X, inout int Y) {
+Y = 2;
+X = 1;
+  }
+
+  void main() {
+int V;
+Init(V, V); // MSVC ABI V == 2, Itanium V == 1
+  }
+
+In the above example the ``Init`` function's behavior depends on the C++ ABI
+implementation. In the MSVC C++ ABI (used for the HLSL DXIL target), call
+arguments are emitted right-to-left and destroyed left-to-right. This means 
that
+the parameter initialization and destruction occurs in the order: {``Y``,
+``X``, ``~X``, ``~Y``}. This causes the write-back of the value of ``Y`` to 
occur
+last, so the resulting value of ``V`` is ``2``. In the Itanium C++ ABI, the
+parameter ordering is reversed, so the initialization and destruction occurs in
+the order: {``X``, ``Y``, ``~Y``, ``X``}. This causes the write-back of the
+value ``X`` to occur last, resulting in the value of ``V`` being set to ``1``.
+
+.. code-block:: c++
+  void Trunc(inout int3 V) { }
+
+
+  void main() {
+float3 F = {1.5, 2.6, 3.3};
+Trunc(F); // F == {1.0, 2.0, 3.0}
+  }
+
+In the above example, the argument expression ``F`` undergoes element-wise
+conversion from a float vector to an integer vector to create a temporary
+``int3``. On expiration the temporary undergoes elementwise conversion back to
+the floating point vector type ``float3``. This results in an implicit
+truncation of the vector even if the value is unused in the function.
+
+
+.. code-block:: c++
+  void UB(out int X) {}
+
+  void main() {
+int X = 7;
+UB(X); // X is undefined!
+  }
+
+In this example an initialized value is passed to an ``out`` parameter.
+Parameters marked ``out`` are not initialized by the argument expression or
+implicitly by the function. They must be explicitly initialized. In this case
+the argument is not initialized in the function so the temporary is still
+uninitialized when it is copied back to the argument expression. This is

[clang] [HLSL][Docs] Add documentation for HLSL functions (PR #75397)

[Chris B via cfe-commits]

@@ -0,0 +1,300 @@
+===
+HLSL Function Calls
+===
+
+.. contents::
+   :local:
+
+Introduction
+
+
+This document descries the design and implementation of HLSL's function call
+semantics in Clang. This includes details related to argument conversion and
+parameter lifetimes.
+
+This document does not seek to serve as official documentation for HLSL's
+call semantics, but does provide an overview to assist a reader. The
+authoritative documentation for HLSL's language semantics is the `draft 
language
+specification`_.
+
+Argument Semantics
+==
+
+In HLSL, all function arguments are passed by value in and out of functions.
+HLSL has 3 keywords which denote the parameter semantics (``in``, ``out`` and
+``inout``). In a function declaration a parameter may be annotated any of the
+following ways:
+
+#.  - denotes input
+#. ``in`` - denotes input
+#. ``out`` - denotes output
+#. ``in out`` - denotes input and output
+#. ``out in`` - denotes input and output
+#. ``inout`` - denotes input and output
+
+Parameters that are exclusively input behave like C/C++ parameters that are
+passed by value.
+
+For parameters that are output (or input and output), a temporary value is
+created in the caller. The temporary value is then passed by-address. For
+output-only parameters, the temporary is uninitialized when passed (it is
+undefined behavior to not explicitly initialize an ``out`` parameter inside a
+function). For input and output parameters, the temporary is initialized from
+the lvalue argument expression through implicit or explicit casting from the
+lvalue argument type to the parameter type.
+
+On return of the function, the values of any parameter temporaries are written
+back to the argument expression through an inverted conversion sequence (if an
+``out`` parameter was not initialized in the function, the uninitialized value
+may be written back).
+
+Parameters of constant-sized array type, are also passed with value semantics.
+This requires input parameters of arrays to construct temporaries and the
+temporaries go through array-to-pointer decay when initializing parameters.
+
+Implementations are allowed to avoid unnecessary temporaries, and HLSL's strict
+no-alias rules can enable some trivial optimizations.
+
+Array Temporaries
+-
+
+Given the following example:
+
+.. code-block:: c++
+  void fn(float a[4]) {
+a[0] = a[1] + a[2] + a[3];
+  }
+
+  float4 main() : SV_Target {
+float arr[4] = {1, 1, 1, 1};
+fn(arr);
+return float4(a[0], a[1], a[2], a[3]);
+  }
+
+In C or C++, the array parameter decays to a pointer, so after the call to
+``fn``, the value of ``a[0]`` is ``3``. In HLSL, the array is passed by value,
+so modifications inside ``fn`` do not propagate out.
+
+.. note::
+  DXC supports unsized arrays passed directly as decayed pointers, which is an
+  unfortunate behavior divergence.
+
+Out Parameter Temporaries
+-
+
+.. code-block:: c++
+  void Init(inout int X, inout int Y) {
+Y = 2;
+X = 1;
+  }
+
+  void main() {
+int V;
+Init(V, V); // MSVC ABI V == 2, Itanium V == 1
+  }
+
+In the above example the ``Init`` function's behavior depends on the C++ ABI
+implementation. In the MSVC C++ ABI (used for the HLSL DXIL target), call

llvm-beanz wrote:

I don't think we explicitly define it, but we need the Clang DXIL generation to 
match otherwise we could expose subtle bugs.

https://github.com/llvm/llvm-project/pull/75397
___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[clang] [HLSL][Docs] Add documentation for HLSL functions (PR #75397)

[Damyan Pepper via cfe-commits]

https://github.com/damyanp edited 
https://github.com/llvm/llvm-project/pull/75397
___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[clang] [HLSL][Docs] Add documentation for HLSL functions (PR #75397)

[Damyan Pepper via cfe-commits]

@@ -0,0 +1,300 @@
+===
+HLSL Function Calls
+===
+
+.. contents::
+   :local:
+
+Introduction
+
+
+This document descries the design and implementation of HLSL's function call
+semantics in Clang. This includes details related to argument conversion and
+parameter lifetimes.
+
+This document does not seek to serve as official documentation for HLSL's
+call semantics, but does provide an overview to assist a reader. The
+authoritative documentation for HLSL's language semantics is the `draft 
language
+specification`_.
+
+Argument Semantics
+==
+
+In HLSL, all function arguments are passed by value in and out of functions.
+HLSL has 3 keywords which denote the parameter semantics (``in``, ``out`` and
+``inout``). In a function declaration a parameter may be annotated any of the
+following ways:
+
+#.  - denotes input
+#. ``in`` - denotes input
+#. ``out`` - denotes output
+#. ``in out`` - denotes input and output
+#. ``out in`` - denotes input and output
+#. ``inout`` - denotes input and output
+
+Parameters that are exclusively input behave like C/C++ parameters that are
+passed by value.
+
+For parameters that are output (or input and output), a temporary value is
+created in the caller. The temporary value is then passed by-address. For
+output-only parameters, the temporary is uninitialized when passed (it is
+undefined behavior to not explicitly initialize an ``out`` parameter inside a
+function). For input and output parameters, the temporary is initialized from
+the lvalue argument expression through implicit or explicit casting from the
+lvalue argument type to the parameter type.
+
+On return of the function, the values of any parameter temporaries are written
+back to the argument expression through an inverted conversion sequence (if an
+``out`` parameter was not initialized in the function, the uninitialized value
+may be written back).
+
+Parameters of constant-sized array type, are also passed with value semantics.
+This requires input parameters of arrays to construct temporaries and the
+temporaries go through array-to-pointer decay when initializing parameters.
+
+Implementations are allowed to avoid unnecessary temporaries, and HLSL's strict
+no-alias rules can enable some trivial optimizations.
+
+Array Temporaries
+-
+
+Given the following example:
+
+.. code-block:: c++
+  void fn(float a[4]) {
+a[0] = a[1] + a[2] + a[3];
+  }
+
+  float4 main() : SV_Target {
+float arr[4] = {1, 1, 1, 1};
+fn(arr);
+return float4(a[0], a[1], a[2], a[3]);
+  }
+
+In C or C++, the array parameter decays to a pointer, so after the call to
+``fn``, the value of ``a[0]`` is ``3``. In HLSL, the array is passed by value,
+so modifications inside ``fn`` do not propagate out.
+
+.. note::
+  DXC supports unsized arrays passed directly as decayed pointers, which is an
+  unfortunate behavior divergence.
+
+Out Parameter Temporaries
+-
+
+.. code-block:: c++
+  void Init(inout int X, inout int Y) {
+Y = 2;
+X = 1;
+  }
+
+  void main() {
+int V;
+Init(V, V); // MSVC ABI V == 2, Itanium V == 1
+  }
+
+In the above example the ``Init`` function's behavior depends on the C++ ABI
+implementation. In the MSVC C++ ABI (used for the HLSL DXIL target), call
+arguments are emitted right-to-left and destroyed left-to-right. This means 
that
+the parameter initialization and destruction occurs in the order: {``Y``,
+``X``, ``~X``, ``~Y``}. This causes the write-back of the value of ``Y`` to 
occur
+last, so the resulting value of ``V`` is ``2``. In the Itanium C++ ABI, the
+parameter ordering is reversed, so the initialization and destruction occurs in
+the order: {``X``, ``Y``, ``~Y``, ``X``}. This causes the write-back of the
+value ``X`` to occur last, resulting in the value of ``V`` being set to ``1``.
+
+.. code-block:: c++
+  void Trunc(inout int3 V) { }
+
+
+  void main() {
+float3 F = {1.5, 2.6, 3.3};
+Trunc(F); // F == {1.0, 2.0, 3.0}
+  }
+
+In the above example, the argument expression ``F`` undergoes element-wise
+conversion from a float vector to an integer vector to create a temporary
+``int3``. On expiration the temporary undergoes elementwise conversion back to
+the floating point vector type ``float3``. This results in an implicit
+truncation of the vector even if the value is unused in the function.
+
+
+.. code-block:: c++
+  void UB(out int X) {}
+
+  void main() {
+int X = 7;
+UB(X); // X is undefined!
+  }
+
+In this example an initialized value is passed to an ``out`` parameter.
+Parameters marked ``out`` are not initialized by the argument expression or
+implicitly by the function. They must be explicitly initialized. In this case
+the argument is not initialized in the function so the temporary is still
+uninitialized when it is copied back to the argument expression. This is

[clang] [HLSL][Docs] Add documentation for HLSL functions (PR #75397)

[Damyan Pepper via cfe-commits]

@@ -0,0 +1,300 @@
+===
+HLSL Function Calls
+===
+
+.. contents::
+   :local:
+
+Introduction
+
+
+This document descries the design and implementation of HLSL's function call
+semantics in Clang. This includes details related to argument conversion and
+parameter lifetimes.
+
+This document does not seek to serve as official documentation for HLSL's
+call semantics, but does provide an overview to assist a reader. The
+authoritative documentation for HLSL's language semantics is the `draft 
language
+specification`_.
+
+Argument Semantics
+==
+
+In HLSL, all function arguments are passed by value in and out of functions.
+HLSL has 3 keywords which denote the parameter semantics (``in``, ``out`` and
+``inout``). In a function declaration a parameter may be annotated any of the
+following ways:
+
+#.  - denotes input
+#. ``in`` - denotes input
+#. ``out`` - denotes output
+#. ``in out`` - denotes input and output
+#. ``out in`` - denotes input and output
+#. ``inout`` - denotes input and output
+
+Parameters that are exclusively input behave like C/C++ parameters that are
+passed by value.
+
+For parameters that are output (or input and output), a temporary value is
+created in the caller. The temporary value is then passed by-address. For
+output-only parameters, the temporary is uninitialized when passed (it is
+undefined behavior to not explicitly initialize an ``out`` parameter inside a
+function). For input and output parameters, the temporary is initialized from
+the lvalue argument expression through implicit or explicit casting from the
+lvalue argument type to the parameter type.
+
+On return of the function, the values of any parameter temporaries are written
+back to the argument expression through an inverted conversion sequence (if an
+``out`` parameter was not initialized in the function, the uninitialized value
+may be written back).
+
+Parameters of constant-sized array type, are also passed with value semantics.
+This requires input parameters of arrays to construct temporaries and the
+temporaries go through array-to-pointer decay when initializing parameters.
+
+Implementations are allowed to avoid unnecessary temporaries, and HLSL's strict
+no-alias rules can enable some trivial optimizations.
+
+Array Temporaries
+-
+
+Given the following example:
+
+.. code-block:: c++
+  void fn(float a[4]) {
+a[0] = a[1] + a[2] + a[3];
+  }
+
+  float4 main() : SV_Target {
+float arr[4] = {1, 1, 1, 1};
+fn(arr);
+return float4(a[0], a[1], a[2], a[3]);
+  }
+
+In C or C++, the array parameter decays to a pointer, so after the call to
+``fn``, the value of ``a[0]`` is ``3``. In HLSL, the array is passed by value,
+so modifications inside ``fn`` do not propagate out.
+
+.. note::
+  DXC supports unsized arrays passed directly as decayed pointers, which is an
+  unfortunate behavior divergence.
+
+Out Parameter Temporaries
+-
+
+.. code-block:: c++
+  void Init(inout int X, inout int Y) {
+Y = 2;
+X = 1;
+  }
+
+  void main() {
+int V;
+Init(V, V); // MSVC ABI V == 2, Itanium V == 1
+  }
+
+In the above example the ``Init`` function's behavior depends on the C++ ABI
+implementation. In the MSVC C++ ABI (used for the HLSL DXIL target), call

damyanp wrote:

Is this defined behavior that we have to ensure continues to work so HLSL 
developers targeting DXIL can depend on it?

https://github.com/llvm/llvm-project/pull/75397
___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[clang] [HLSL][Docs] Add documentation for HLSL functions (PR #75397)

[Damyan Pepper via cfe-commits]

@@ -0,0 +1,300 @@
+===
+HLSL Function Calls
+===
+
+.. contents::
+   :local:
+
+Introduction
+
+
+This document descries the design and implementation of HLSL's function call

damyanp wrote:

typo: `descries` -> `describes`

https://github.com/llvm/llvm-project/pull/75397
___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[clang] [HLSL][Docs] Add documentation for HLSL functions (PR #75397)

[Damyan Pepper via cfe-commits]

https://github.com/damyanp approved this pull request.


https://github.com/llvm/llvm-project/pull/75397
___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[clang] [HLSL][Docs] Add documentation for HLSL functions (PR #75397)

[Chris B via cfe-commits]

https://github.com/llvm-beanz updated 
https://github.com/llvm/llvm-project/pull/75397

>From 4ebc0c58dc751f422de85b0909636cb1a87f8ce4 Mon Sep 17 00:00:00 2001
From: Chris Bieneman 
Date: Wed, 13 Dec 2023 16:44:09 -0600
Subject: [PATCH] [HLSL][Docs] Add documentation for HLSL functions

This adds a new document that covers the HLSL approach to function
calls and parameter semantics. At time of writing this document is a
proposal for the implementation.
---
 clang/docs/HLSL/FunctionCalls.rst | 316 ++
 clang/docs/HLSL/HLSLDocs.rst  |   1 +
 2 files changed, 317 insertions(+)
 create mode 100644 clang/docs/HLSL/FunctionCalls.rst

diff --git a/clang/docs/HLSL/FunctionCalls.rst 
b/clang/docs/HLSL/FunctionCalls.rst
new file mode 100644
index 00..e62b249e011a94
--- /dev/null
+++ b/clang/docs/HLSL/FunctionCalls.rst
@@ -0,0 +1,316 @@
+===
+HLSL Function Calls
+===
+
+.. contents::
+   :local:
+
+Introduction
+
+
+This document descries the design and implementation of HLSL's function call
+semantics in Clang. This includes details related to argument conversion and
+parameter lifetimes.
+
+This document does not seek to serve as official documentation for HLSL's
+call semantics, but does provide an overview to assist a reader. The
+authoritative documentation for HLSL's language semantics is the `draft 
language
+specification `_.
+
+Argument Semantics
+==
+
+In HLSL, all function arguments are passed by value in and out of functions.
+HLSL has 3 keywords which denote the parameter semantics (``in``, ``out`` and
+``inout``). In a function declaration a parameter may be annotated any of the
+following ways:
+
+#.  - denotes input
+#. ``in`` - denotes input
+#. ``out`` - denotes output
+#. ``in out`` - denotes input and output
+#. ``out in`` - denotes input and output
+#. ``inout`` - denotes input and output
+
+Parameters that are exclusively input behave like C/C++ parameters that are
+passed by value.
+
+For parameters that are output (or input and output), a temporary value is
+created in the caller. The temporary value is then passed by-address. For
+output-only parameters, the temporary is uninitialized when passed (it is
+undefined behavior to not explicitly initialize an ``out`` parameter inside a
+function). For input and output parameters, the temporary is initialized from
+the lvalue argument expression through implicit or explicit casting from the
+lvalue argument type to the parameter type.
+
+On return of the function, the values of any parameter temporaries are written
+back to the argument expression through an inverted conversion sequence (if an
+``out`` parameter was not initialized in the function, the uninitialized value
+may be written back).
+
+Parameters of constant-sized array type, are also passed with value semantics.
+This requires input parameters of arrays to construct temporaries and the
+temporaries go through array-to-pointer decay when initializing parameters.
+
+Implementations are allowed to avoid unnecessary temporaries, and HLSL's strict
+no-alias rules can enable some trivial optimizations.
+
+Array Temporaries
+-
+
+Given the following example:
+
+.. code-block:: c++
+
+  void fn(float a[4]) {
+a[0] = a[1] + a[2] + a[3];
+  }
+
+  float4 main() : SV_Target {
+float arr[4] = {1, 1, 1, 1};
+fn(arr);
+return float4(a[0], a[1], a[2], a[3]);
+  }
+
+In C or C++, the array parameter decays to a pointer, so after the call to
+``fn``, the value of ``a[0]`` is ``3``. In HLSL, the array is passed by value,
+so modifications inside ``fn`` do not propagate out.
+
+.. note::
+
+  DXC supports unsized arrays passed directly as decayed pointers, which is an
+  unfortunate behavior divergence.
+
+Out Parameter Temporaries
+-
+
+.. code-block:: c++
+
+  void Init(inout int X, inout int Y) {
+Y = 2;
+X = 1;
+  }
+
+  void main() {
+int V;
+Init(V, V); // MSVC ABI V == 2, Itanium V == 1
+  }
+
+In the above example the ``Init`` function's behavior depends on the C++ ABI
+implementation. In the MSVC C++ ABI (used for the HLSL DXIL target), call
+arguments are emitted right-to-left and destroyed left-to-right. This means 
that
+the parameter initialization and destruction occurs in the order: {``Y``,
+``X``, ``~X``, ``~Y``}. This causes the write-back of the value of ``Y`` to 
occur
+last, so the resulting value of ``V`` is ``2``. In the Itanium C++ ABI, the
+parameter ordering is reversed, so the initialization and destruction occurs in
+the order: {``X``, ``Y``, ``~Y``, ``X``}. This causes the write-back of the
+value ``X`` to occur last, resulting in the value of ``V`` being set to ``1``.
+
+.. code-block:: c++
+
+  void Trunc(inout int3 V) { }
+
+
+  void main() {
+float3 F = {1.5, 2.6, 3.3};
+Trunc(F); // F == {1.0, 2.0, 3.0}
+  }
+
+In the above example, the 

[clang] [HLSL][Docs] Add documentation for HLSL functions (PR #75397)

[via cfe-commits]

llvmbot wrote:




@llvm/pr-subscribers-clang

Author: Chris B (llvm-beanz)


Changes

This adds a new document that covers the HLSL approach to function calls and 
parameter semantics. At time of writing this document is a proposal for the 
implementation.

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


2 Files Affected:

- (added) clang/docs/HLSL/FunctionCalls.rst (+300) 
- (modified) clang/docs/HLSL/HLSLDocs.rst (+1) 


``diff
diff --git a/clang/docs/HLSL/FunctionCalls.rst 
b/clang/docs/HLSL/FunctionCalls.rst
new file mode 100644
index 00..aeddac087cb89d
--- /dev/null
+++ b/clang/docs/HLSL/FunctionCalls.rst
@@ -0,0 +1,300 @@
+===
+HLSL Function Calls
+===
+
+.. contents::
+   :local:
+
+Introduction
+
+
+This document descries the design and implementation of HLSL's function call
+semantics in Clang. This includes details related to argument conversion and
+parameter lifetimes.
+
+This document does not seek to serve as official documentation for HLSL's
+call semantics, but does provide an overview to assist a reader. The
+authoritative documentation for HLSL's language semantics is the `draft 
language
+specification`_.
+
+Argument Semantics
+==
+
+In HLSL, all function arguments are passed by value in and out of functions.
+HLSL has 3 keywords which denote the parameter semantics (``in``, ``out`` and
+``inout``). In a function declaration a parameter may be annotated any of the
+following ways:
+
+#.  - denotes input
+#. ``in`` - denotes input
+#. ``out`` - denotes output
+#. ``in out`` - denotes input and output
+#. ``out in`` - denotes input and output
+#. ``inout`` - denotes input and output
+
+Parameters that are exclusively input behave like C/C++ parameters that are
+passed by value.
+
+For parameters that are output (or input and output), a temporary value is
+created in the caller. The temporary value is then passed by-address. For
+output-only parameters, the temporary is uninitialized when passed (it is
+undefined behavior to not explicitly initialize an ``out`` parameter inside a
+function). For input and output parameters, the temporary is initialized from
+the lvalue argument expression through implicit or explicit casting from the
+lvalue argument type to the parameter type.
+
+On return of the function, the values of any parameter temporaries are written
+back to the argument expression through an inverted conversion sequence (if an
+``out`` parameter was not initialized in the function, the uninitialized value
+may be written back).
+
+Parameters of constant-sized array type, are also passed with value semantics.
+This requires input parameters of arrays to construct temporaries and the
+temporaries go through array-to-pointer decay when initializing parameters.
+
+Implementations are allowed to avoid unnecessary temporaries, and HLSL's strict
+no-alias rules can enable some trivial optimizations.
+
+Array Temporaries
+-
+
+Given the following example:
+
+.. code-block:: c++
+  void fn(float a[4]) {
+a[0] = a[1] + a[2] + a[3];
+  }
+
+  float4 main() : SV_Target {
+float arr[4] = {1, 1, 1, 1};
+fn(arr);
+return float4(a[0], a[1], a[2], a[3]);
+  }
+
+In C or C++, the array parameter decays to a pointer, so after the call to
+``fn``, the value of ``a[0]`` is ``3``. In HLSL, the array is passed by value,
+so modifications inside ``fn`` do not propagate out.
+
+.. note::
+  DXC supports unsized arrays passed directly as decayed pointers, which is an
+  unfortunate behavior divergence.
+
+Out Parameter Temporaries
+-
+
+.. code-block:: c++
+  void Init(inout int X, inout int Y) {
+Y = 2;
+X = 1;
+  }
+
+  void main() {
+int V;
+Init(V, V); // MSVC ABI V == 2, Itanium V == 1
+  }
+
+In the above example the ``Init`` function's behavior depends on the C++ ABI
+implementation. In the MSVC C++ ABI (used for the HLSL DXIL target), call
+arguments are emitted right-to-left and destroyed left-to-right. This means 
that
+the parameter initialization and destruction occurs in the order: {``Y``,
+``X``, ``~X``, ``~Y``}. This causes the write-back of the value of ``Y`` to 
occur
+last, so the resulting value of ``V`` is ``2``. In the Itanium C++ ABI, the
+parameter ordering is reversed, so the initialization and destruction occurs in
+the order: {``X``, ``Y``, ``~Y``, ``X``}. This causes the write-back of the
+value ``X`` to occur last, resulting in the value of ``V`` being set to ``1``.
+
+.. code-block:: c++
+  void Trunc(inout int3 V) { }
+
+
+  void main() {
+float3 F = {1.5, 2.6, 3.3};
+Trunc(F); // F == {1.0, 2.0, 3.0}
+  }
+
+In the above example, the argument expression ``F`` undergoes element-wise
+conversion from a float vector to an integer vector to create a temporary
+``int3``. On expiration the temporary undergoes elementwise conversion back to
+the 

[clang] [HLSL][Docs] Add documentation for HLSL functions (PR #75397)

[Chris B via cfe-commits]

https://github.com/llvm-beanz created 
https://github.com/llvm/llvm-project/pull/75397

This adds a new document that covers the HLSL approach to function calls and 
parameter semantics. At time of writing this document is a proposal for the 
implementation.

>From d6f57c27a3030f242bba62077ecd84ba49d8e468 Mon Sep 17 00:00:00 2001
From: Chris Bieneman 
Date: Wed, 13 Dec 2023 16:44:09 -0600
Subject: [PATCH] [HLSL][Docs] Add documentation for HLSL functions

This adds a new document that covers the HLSL approach to function
calls and parameter semantics. At time of writing this document is a
proposal for the implementation.
---
 clang/docs/HLSL/FunctionCalls.rst | 300 ++
 clang/docs/HLSL/HLSLDocs.rst  |   1 +
 2 files changed, 301 insertions(+)
 create mode 100644 clang/docs/HLSL/FunctionCalls.rst

diff --git a/clang/docs/HLSL/FunctionCalls.rst 
b/clang/docs/HLSL/FunctionCalls.rst
new file mode 100644
index 00..aeddac087cb89d
--- /dev/null
+++ b/clang/docs/HLSL/FunctionCalls.rst
@@ -0,0 +1,300 @@
+===
+HLSL Function Calls
+===
+
+.. contents::
+   :local:
+
+Introduction
+
+
+This document descries the design and implementation of HLSL's function call
+semantics in Clang. This includes details related to argument conversion and
+parameter lifetimes.
+
+This document does not seek to serve as official documentation for HLSL's
+call semantics, but does provide an overview to assist a reader. The
+authoritative documentation for HLSL's language semantics is the `draft 
language
+specification`_.
+
+Argument Semantics
+==
+
+In HLSL, all function arguments are passed by value in and out of functions.
+HLSL has 3 keywords which denote the parameter semantics (``in``, ``out`` and
+``inout``). In a function declaration a parameter may be annotated any of the
+following ways:
+
+#.  - denotes input
+#. ``in`` - denotes input
+#. ``out`` - denotes output
+#. ``in out`` - denotes input and output
+#. ``out in`` - denotes input and output
+#. ``inout`` - denotes input and output
+
+Parameters that are exclusively input behave like C/C++ parameters that are
+passed by value.
+
+For parameters that are output (or input and output), a temporary value is
+created in the caller. The temporary value is then passed by-address. For
+output-only parameters, the temporary is uninitialized when passed (it is
+undefined behavior to not explicitly initialize an ``out`` parameter inside a
+function). For input and output parameters, the temporary is initialized from
+the lvalue argument expression through implicit or explicit casting from the
+lvalue argument type to the parameter type.
+
+On return of the function, the values of any parameter temporaries are written
+back to the argument expression through an inverted conversion sequence (if an
+``out`` parameter was not initialized in the function, the uninitialized value
+may be written back).
+
+Parameters of constant-sized array type, are also passed with value semantics.
+This requires input parameters of arrays to construct temporaries and the
+temporaries go through array-to-pointer decay when initializing parameters.
+
+Implementations are allowed to avoid unnecessary temporaries, and HLSL's strict
+no-alias rules can enable some trivial optimizations.
+
+Array Temporaries
+-
+
+Given the following example:
+
+.. code-block:: c++
+  void fn(float a[4]) {
+a[0] = a[1] + a[2] + a[3];
+  }
+
+  float4 main() : SV_Target {
+float arr[4] = {1, 1, 1, 1};
+fn(arr);
+return float4(a[0], a[1], a[2], a[3]);
+  }
+
+In C or C++, the array parameter decays to a pointer, so after the call to
+``fn``, the value of ``a[0]`` is ``3``. In HLSL, the array is passed by value,
+so modifications inside ``fn`` do not propagate out.
+
+.. note::
+  DXC supports unsized arrays passed directly as decayed pointers, which is an
+  unfortunate behavior divergence.
+
+Out Parameter Temporaries
+-
+
+.. code-block:: c++
+  void Init(inout int X, inout int Y) {
+Y = 2;
+X = 1;
+  }
+
+  void main() {
+int V;
+Init(V, V); // MSVC ABI V == 2, Itanium V == 1
+  }
+
+In the above example the ``Init`` function's behavior depends on the C++ ABI
+implementation. In the MSVC C++ ABI (used for the HLSL DXIL target), call
+arguments are emitted right-to-left and destroyed left-to-right. This means 
that
+the parameter initialization and destruction occurs in the order: {``Y``,
+``X``, ``~X``, ``~Y``}. This causes the write-back of the value of ``Y`` to 
occur
+last, so the resulting value of ``V`` is ``2``. In the Itanium C++ ABI, the
+parameter ordering is reversed, so the initialization and destruction occurs in
+the order: {``X``, ``Y``, ``~Y``, ``X``}. This causes the write-back of the
+value ``X`` to occur last, resulting in the value of ``V`` being set to ``1``.
+
+.. code-block::