[clang] [HLSL][Doc] Add doc about expected differences (PR #82395)

[Chris B via cfe-commits]

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

[clang] [HLSL][Doc] Add doc about expected differences (PR #82395)

[S. Bharadwaj Yadavalli via cfe-commits]

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


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

[clang] [HLSL][Doc] Add doc about expected differences (PR #82395)

[Chris B via cfe-commits]

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

>From 558dd6182a4dc6fc5c5383358cac422289a7a90b Mon Sep 17 00:00:00 2001
From: Chris Bieneman 
Date: Tue, 20 Feb 2024 12:01:16 -0600
Subject: [PATCH 1/6] [HLSL][Doc] Add doc about expected differences

This document covers expected differences between Clang and the HLSL
reference compiler implementations (FXC & DXC). The document is not
intended to be exhaustive, but it should be a best effort to cover known
cases.

This document should document both the behavioral difference and the
explanation of why Clang differs.

The initail document covers known overload resolution differences.
---
 clang/docs/HLSL/ExpectedDifferences.rst | 108 
 clang/docs/HLSL/HLSLDocs.rst|   1 +
 2 files changed, 109 insertions(+)
 create mode 100644 clang/docs/HLSL/ExpectedDifferences.rst

diff --git a/clang/docs/HLSL/ExpectedDifferences.rst 
b/clang/docs/HLSL/ExpectedDifferences.rst
new file mode 100644
index 00..f1d52b52092466
--- /dev/null
+++ b/clang/docs/HLSL/ExpectedDifferences.rst
@@ -0,0 +1,108 @@
+
+Expected Differences vs DXC and FXC
+===
+
+.. contents::
+   :local:
+
+Introduction
+
+
+HLSL currently has two reference compilers, the `DirectX Shader Compiler (DXC)
+`_ and the
+`Effect-Compiler (FXC) 
`_.
+The two reference compilers do not fully agree. Some known disagreements in the
+references are tracked on
+`DXC's GitHub
+`_,
+but many more are known to exist.
+
+HLSL as implemented by Clang will also not fully match either of the reference
+implementations, it is instead being written to match the `draft language
+specification `_.
+
+This document is a non-exhaustive collection the known differences between
+Clang's implementation of HLSL and the existing reference compilers.
+
+General Principles
+--
+
+Most of the intended differences between Clang and the earlier reference
+compilers are focused on increased consistency and correctness. Both reference
+compilers do not always apply language rules the same in all contexts.
+
+Clang also deviates from the reference compilers by providing different
+diagnostics, both in terms of the textual messages and the contexts in which
+diagnostics are produced. While striving for a high level of source
+compatibility with conforming HLSL code, Clang may produce earlier and more
+robust diagnostics for incorrect code or reject code that a reference compiler
+incorrectly accepted.
+
+Language Version
+
+
+Clang targets language compatibility for HLSL 2021 as implemented by DXC.
+Language features that were removed in earlier versions of HLSL may be added on
+a case-by-case basis, but are not planned for the initial implementation.
+
+Overload Resolution
+===
+
+Clang's HLSL implementation adopts C++ overload resolution rules as proposed 
for
+HLSL 202x based on proposal
+`0007 
`_
+and
+`0008 
`_.
+
+Clang's implementation extends standard overload resolution rules to HLSL
+library functionality. This causes subtle changes in overload resolution
+behavior between Clang and DXC. Some examples include:
+
+.. code-block:: c++
+
+  void halfOrInt16(half H);
+  void halfOrInt16(uint16_t I);
+
+  void takesDoubles(double, double, double);
+
+  cbuffer CB {
+uint U;
+uint I;
+float X, Y, Z;
+double3 A, B;
+  }
+
+  export void call() {
+halfOrInt16(U); // All: Resolves to halfOrInt16(uint16_t).
+halfOrInt16(I); // All: Resolves to halfOrInt16(uint16_t).
+  #ifndef IGNORE_ERRORS
+half H = asfloat16(I); // DXC: Fails to resolve overload for int.
+  // Clang: Resolves to halfOrInt16(uint16_t).
+half H = asfloat16(U); // DXC: Fails to resolve overload for int.
+  // Clang: Resolves to halfOrInt16(uint16_t).
+  #endif
+half H = asfloat16(0x01); // DXC: Resolves to halfOrInt16(half).
+  // Clang: Resolves to halfOrInt16(uint16_t).
+
+takesDoubles(X, Y, Z); // Works on all compilers
+  #ifndef IGNORE_ERRORS
+fma(X, Y, Z); // DXC: Fails to resolve no known conversion from float to 
double.
+  // Clang: Resolces to fma(double,double,double).
+  #endif
+
+double D = dot(A, B); // DXC: Resolves to dot(double3, double3), fails 
DXIL Validation.
+  // FXC: Expands to compute double dot product with 
fmul/fadd
+  // 

[clang] [HLSL][Doc] Add doc about expected differences (PR #82395)

[Chris B via cfe-commits]

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

>From 558dd6182a4dc6fc5c5383358cac422289a7a90b Mon Sep 17 00:00:00 2001
From: Chris Bieneman 
Date: Tue, 20 Feb 2024 12:01:16 -0600
Subject: [PATCH 1/5] [HLSL][Doc] Add doc about expected differences

This document covers expected differences between Clang and the HLSL
reference compiler implementations (FXC & DXC). The document is not
intended to be exhaustive, but it should be a best effort to cover known
cases.

This document should document both the behavioral difference and the
explanation of why Clang differs.

The initail document covers known overload resolution differences.
---
 clang/docs/HLSL/ExpectedDifferences.rst | 108 
 clang/docs/HLSL/HLSLDocs.rst|   1 +
 2 files changed, 109 insertions(+)
 create mode 100644 clang/docs/HLSL/ExpectedDifferences.rst

diff --git a/clang/docs/HLSL/ExpectedDifferences.rst 
b/clang/docs/HLSL/ExpectedDifferences.rst
new file mode 100644
index 00..f1d52b52092466
--- /dev/null
+++ b/clang/docs/HLSL/ExpectedDifferences.rst
@@ -0,0 +1,108 @@
+
+Expected Differences vs DXC and FXC
+===
+
+.. contents::
+   :local:
+
+Introduction
+
+
+HLSL currently has two reference compilers, the `DirectX Shader Compiler (DXC)
+`_ and the
+`Effect-Compiler (FXC) 
`_.
+The two reference compilers do not fully agree. Some known disagreements in the
+references are tracked on
+`DXC's GitHub
+`_,
+but many more are known to exist.
+
+HLSL as implemented by Clang will also not fully match either of the reference
+implementations, it is instead being written to match the `draft language
+specification `_.
+
+This document is a non-exhaustive collection the known differences between
+Clang's implementation of HLSL and the existing reference compilers.
+
+General Principles
+--
+
+Most of the intended differences between Clang and the earlier reference
+compilers are focused on increased consistency and correctness. Both reference
+compilers do not always apply language rules the same in all contexts.
+
+Clang also deviates from the reference compilers by providing different
+diagnostics, both in terms of the textual messages and the contexts in which
+diagnostics are produced. While striving for a high level of source
+compatibility with conforming HLSL code, Clang may produce earlier and more
+robust diagnostics for incorrect code or reject code that a reference compiler
+incorrectly accepted.
+
+Language Version
+
+
+Clang targets language compatibility for HLSL 2021 as implemented by DXC.
+Language features that were removed in earlier versions of HLSL may be added on
+a case-by-case basis, but are not planned for the initial implementation.
+
+Overload Resolution
+===
+
+Clang's HLSL implementation adopts C++ overload resolution rules as proposed 
for
+HLSL 202x based on proposal
+`0007 
`_
+and
+`0008 
`_.
+
+Clang's implementation extends standard overload resolution rules to HLSL
+library functionality. This causes subtle changes in overload resolution
+behavior between Clang and DXC. Some examples include:
+
+.. code-block:: c++
+
+  void halfOrInt16(half H);
+  void halfOrInt16(uint16_t I);
+
+  void takesDoubles(double, double, double);
+
+  cbuffer CB {
+uint U;
+uint I;
+float X, Y, Z;
+double3 A, B;
+  }
+
+  export void call() {
+halfOrInt16(U); // All: Resolves to halfOrInt16(uint16_t).
+halfOrInt16(I); // All: Resolves to halfOrInt16(uint16_t).
+  #ifndef IGNORE_ERRORS
+half H = asfloat16(I); // DXC: Fails to resolve overload for int.
+  // Clang: Resolves to halfOrInt16(uint16_t).
+half H = asfloat16(U); // DXC: Fails to resolve overload for int.
+  // Clang: Resolves to halfOrInt16(uint16_t).
+  #endif
+half H = asfloat16(0x01); // DXC: Resolves to halfOrInt16(half).
+  // Clang: Resolves to halfOrInt16(uint16_t).
+
+takesDoubles(X, Y, Z); // Works on all compilers
+  #ifndef IGNORE_ERRORS
+fma(X, Y, Z); // DXC: Fails to resolve no known conversion from float to 
double.
+  // Clang: Resolces to fma(double,double,double).
+  #endif
+
+double D = dot(A, B); // DXC: Resolves to dot(double3, double3), fails 
DXIL Validation.
+  // FXC: Expands to compute double dot product with 
fmul/fadd
+  // 

[clang] [HLSL][Doc] Add doc about expected differences (PR #82395)

[Damyan Pepper via cfe-commits]

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


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

[clang] [HLSL][Doc] Add doc about expected differences (PR #82395)

[S. Bharadwaj Yadavalli via cfe-commits]

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

[clang] [HLSL][Doc] Add doc about expected differences (PR #82395)

[S. Bharadwaj Yadavalli via cfe-commits]

@@ -0,0 +1,107 @@
+
+Expected Differences vs DXC and FXC
+===
+
+.. contents::
+   :local:
+
+Introduction
+
+
+HLSL currently has two reference compilers, the `DirectX Shader Compiler (DXC)
+`_ and the
+`Effect-Compiler (FXC) 
`_.
+The two reference compilers do not fully agree. Some known disagreements in the
+references are tracked on
+`DXC's GitHub
+`_,
+but many more are known to exist.
+
+HLSL as implemented by Clang will also not fully match either of the reference
+implementations, it is instead being written to match the `draft language
+specification `_.
+
+This document is a non-exhaustive collection the known differences between
+Clang's implementation of HLSL and the existing reference compilers.
+
+General Principles
+--
+
+Most of the intended differences between Clang and the earlier reference
+compilers are focused on increased consistency and correctness. Both reference
+compilers do not always apply language rules the same in all contexts.
+
+Clang also deviates from the reference compilers by providing different
+diagnostics, both in terms of the textual messages and the contexts in which
+diagnostics are produced. While striving for a high level of source
+compatibility with conforming HLSL code, Clang may produce earlier and more
+robust diagnostics for incorrect code or reject code that a reference compiler
+incorrectly accepted.
+
+Language Version
+
+
+Clang targets language compatibility for HLSL 2021 as implemented by DXC.
+Language features that were removed in earlier versions of HLSL may be added on
+a case-by-case basis, but are not planned for the initial implementation.
+
+Overload Resolution
+===
+
+Clang's HLSL implementation adopts C++ overload resolution rules as proposed 
for
+HLSL 202x based on proposal
+`0007 
`_
+and
+`0008 
`_.
+
+Clang's implementation extends standard overload resolution rules to HLSL
+library functionality. This causes subtle changes in overload resolution
+behavior between Clang and DXC. Some examples include:
+
+.. code-block:: c++
+
+  void halfOrInt16(half H);
+  void halfOrInt16(uint16_t I);
+
+  void takesDoubles(double, double, double);
+
+  cbuffer CB {
+uint U;
+int I;
+float X, Y, Z;
+double3 A, B;
+  }
+
+  export void call() {
+halfOrInt16(U); // All: Resolves to halfOrInt16(uint16_t).
+halfOrInt16(I); // All: Resolves to halfOrInt16(uint16_t).
+half H;
+  #ifndef IGNORE_ERRORS
+H = asfloat16(I); // DXC: Fails to resolve overload for int.
+  // Clang: Resolves to asfloat16(uint16_t).
+H = asfloat16(U); // DXC: Fails to resolve overload for int.
+  // Clang: Resolves to asfloat16(uint16_t).
+  #endif
+H = asfloat16(0x01); // DXC: Resolves to asfloat16(half).
+ // Clang: Resolves to asfloat16(uint16_t).
+
+takesDoubles(X, Y, Z); // Works on all compilers
+  #ifndef IGNORE_ERRORS
+fma(X, Y, Z); // DXC: Fails to resolve no known conversion from float to 
double.
+  // Clang: Resolces to fma(double,double,double).
+  #endif
+
+double D = dot(A, B); // DXC: Resolves to dot(double3, double3), fails 
DXIL Validation.
+  // FXC: Expands to compute double dot product with 
fmul/fadd
+  // Clang: Resolves to dot(float3, float3), emits 
conversion warnings.
+
+  }
+
+.. note::
+
+  In Clang a conscious decision was made to exclude the ``dot(vector,
+  vector)`` overload and allow overload resolution to resolve the

bharadwajy wrote:

```suggestion
  In Clang a conscious decision was made to exclude the ``dot(vector, 
vector)`` 
  overload and allow overload resolution to resolve the
```
 
The new-line splitting the verbatim text is rendered as such in the rendered 
version. Suggest a fix as above.

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

[clang] [HLSL][Doc] Add doc about expected differences (PR #82395)

[Chris B via cfe-commits]

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

>From 558dd6182a4dc6fc5c5383358cac422289a7a90b Mon Sep 17 00:00:00 2001
From: Chris Bieneman 
Date: Tue, 20 Feb 2024 12:01:16 -0600
Subject: [PATCH 1/4] [HLSL][Doc] Add doc about expected differences

This document covers expected differences between Clang and the HLSL
reference compiler implementations (FXC & DXC). The document is not
intended to be exhaustive, but it should be a best effort to cover known
cases.

This document should document both the behavioral difference and the
explanation of why Clang differs.

The initail document covers known overload resolution differences.
---
 clang/docs/HLSL/ExpectedDifferences.rst | 108 
 clang/docs/HLSL/HLSLDocs.rst|   1 +
 2 files changed, 109 insertions(+)
 create mode 100644 clang/docs/HLSL/ExpectedDifferences.rst

diff --git a/clang/docs/HLSL/ExpectedDifferences.rst 
b/clang/docs/HLSL/ExpectedDifferences.rst
new file mode 100644
index 00..f1d52b52092466
--- /dev/null
+++ b/clang/docs/HLSL/ExpectedDifferences.rst
@@ -0,0 +1,108 @@
+
+Expected Differences vs DXC and FXC
+===
+
+.. contents::
+   :local:
+
+Introduction
+
+
+HLSL currently has two reference compilers, the `DirectX Shader Compiler (DXC)
+`_ and the
+`Effect-Compiler (FXC) 
`_.
+The two reference compilers do not fully agree. Some known disagreements in the
+references are tracked on
+`DXC's GitHub
+`_,
+but many more are known to exist.
+
+HLSL as implemented by Clang will also not fully match either of the reference
+implementations, it is instead being written to match the `draft language
+specification `_.
+
+This document is a non-exhaustive collection the known differences between
+Clang's implementation of HLSL and the existing reference compilers.
+
+General Principles
+--
+
+Most of the intended differences between Clang and the earlier reference
+compilers are focused on increased consistency and correctness. Both reference
+compilers do not always apply language rules the same in all contexts.
+
+Clang also deviates from the reference compilers by providing different
+diagnostics, both in terms of the textual messages and the contexts in which
+diagnostics are produced. While striving for a high level of source
+compatibility with conforming HLSL code, Clang may produce earlier and more
+robust diagnostics for incorrect code or reject code that a reference compiler
+incorrectly accepted.
+
+Language Version
+
+
+Clang targets language compatibility for HLSL 2021 as implemented by DXC.
+Language features that were removed in earlier versions of HLSL may be added on
+a case-by-case basis, but are not planned for the initial implementation.
+
+Overload Resolution
+===
+
+Clang's HLSL implementation adopts C++ overload resolution rules as proposed 
for
+HLSL 202x based on proposal
+`0007 
`_
+and
+`0008 
`_.
+
+Clang's implementation extends standard overload resolution rules to HLSL
+library functionality. This causes subtle changes in overload resolution
+behavior between Clang and DXC. Some examples include:
+
+.. code-block:: c++
+
+  void halfOrInt16(half H);
+  void halfOrInt16(uint16_t I);
+
+  void takesDoubles(double, double, double);
+
+  cbuffer CB {
+uint U;
+uint I;
+float X, Y, Z;
+double3 A, B;
+  }
+
+  export void call() {
+halfOrInt16(U); // All: Resolves to halfOrInt16(uint16_t).
+halfOrInt16(I); // All: Resolves to halfOrInt16(uint16_t).
+  #ifndef IGNORE_ERRORS
+half H = asfloat16(I); // DXC: Fails to resolve overload for int.
+  // Clang: Resolves to halfOrInt16(uint16_t).
+half H = asfloat16(U); // DXC: Fails to resolve overload for int.
+  // Clang: Resolves to halfOrInt16(uint16_t).
+  #endif
+half H = asfloat16(0x01); // DXC: Resolves to halfOrInt16(half).
+  // Clang: Resolves to halfOrInt16(uint16_t).
+
+takesDoubles(X, Y, Z); // Works on all compilers
+  #ifndef IGNORE_ERRORS
+fma(X, Y, Z); // DXC: Fails to resolve no known conversion from float to 
double.
+  // Clang: Resolces to fma(double,double,double).
+  #endif
+
+double D = dot(A, B); // DXC: Resolves to dot(double3, double3), fails 
DXIL Validation.
+  // FXC: Expands to compute double dot product with 
fmul/fadd
+  // 

[clang] [HLSL][Doc] Add doc about expected differences (PR #82395)

[Chris B via cfe-commits]

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

>From 558dd6182a4dc6fc5c5383358cac422289a7a90b Mon Sep 17 00:00:00 2001
From: Chris Bieneman 
Date: Tue, 20 Feb 2024 12:01:16 -0600
Subject: [PATCH 1/3] [HLSL][Doc] Add doc about expected differences

This document covers expected differences between Clang and the HLSL
reference compiler implementations (FXC & DXC). The document is not
intended to be exhaustive, but it should be a best effort to cover known
cases.

This document should document both the behavioral difference and the
explanation of why Clang differs.

The initail document covers known overload resolution differences.
---
 clang/docs/HLSL/ExpectedDifferences.rst | 108 
 clang/docs/HLSL/HLSLDocs.rst|   1 +
 2 files changed, 109 insertions(+)
 create mode 100644 clang/docs/HLSL/ExpectedDifferences.rst

diff --git a/clang/docs/HLSL/ExpectedDifferences.rst 
b/clang/docs/HLSL/ExpectedDifferences.rst
new file mode 100644
index 00..f1d52b52092466
--- /dev/null
+++ b/clang/docs/HLSL/ExpectedDifferences.rst
@@ -0,0 +1,108 @@
+
+Expected Differences vs DXC and FXC
+===
+
+.. contents::
+   :local:
+
+Introduction
+
+
+HLSL currently has two reference compilers, the `DirectX Shader Compiler (DXC)
+`_ and the
+`Effect-Compiler (FXC) 
`_.
+The two reference compilers do not fully agree. Some known disagreements in the
+references are tracked on
+`DXC's GitHub
+`_,
+but many more are known to exist.
+
+HLSL as implemented by Clang will also not fully match either of the reference
+implementations, it is instead being written to match the `draft language
+specification `_.
+
+This document is a non-exhaustive collection the known differences between
+Clang's implementation of HLSL and the existing reference compilers.
+
+General Principles
+--
+
+Most of the intended differences between Clang and the earlier reference
+compilers are focused on increased consistency and correctness. Both reference
+compilers do not always apply language rules the same in all contexts.
+
+Clang also deviates from the reference compilers by providing different
+diagnostics, both in terms of the textual messages and the contexts in which
+diagnostics are produced. While striving for a high level of source
+compatibility with conforming HLSL code, Clang may produce earlier and more
+robust diagnostics for incorrect code or reject code that a reference compiler
+incorrectly accepted.
+
+Language Version
+
+
+Clang targets language compatibility for HLSL 2021 as implemented by DXC.
+Language features that were removed in earlier versions of HLSL may be added on
+a case-by-case basis, but are not planned for the initial implementation.
+
+Overload Resolution
+===
+
+Clang's HLSL implementation adopts C++ overload resolution rules as proposed 
for
+HLSL 202x based on proposal
+`0007 
`_
+and
+`0008 
`_.
+
+Clang's implementation extends standard overload resolution rules to HLSL
+library functionality. This causes subtle changes in overload resolution
+behavior between Clang and DXC. Some examples include:
+
+.. code-block:: c++
+
+  void halfOrInt16(half H);
+  void halfOrInt16(uint16_t I);
+
+  void takesDoubles(double, double, double);
+
+  cbuffer CB {
+uint U;
+uint I;
+float X, Y, Z;
+double3 A, B;
+  }
+
+  export void call() {
+halfOrInt16(U); // All: Resolves to halfOrInt16(uint16_t).
+halfOrInt16(I); // All: Resolves to halfOrInt16(uint16_t).
+  #ifndef IGNORE_ERRORS
+half H = asfloat16(I); // DXC: Fails to resolve overload for int.
+  // Clang: Resolves to halfOrInt16(uint16_t).
+half H = asfloat16(U); // DXC: Fails to resolve overload for int.
+  // Clang: Resolves to halfOrInt16(uint16_t).
+  #endif
+half H = asfloat16(0x01); // DXC: Resolves to halfOrInt16(half).
+  // Clang: Resolves to halfOrInt16(uint16_t).
+
+takesDoubles(X, Y, Z); // Works on all compilers
+  #ifndef IGNORE_ERRORS
+fma(X, Y, Z); // DXC: Fails to resolve no known conversion from float to 
double.
+  // Clang: Resolces to fma(double,double,double).
+  #endif
+
+double D = dot(A, B); // DXC: Resolves to dot(double3, double3), fails 
DXIL Validation.
+  // FXC: Expands to compute double dot product with 
fmul/fadd
+  // 

[clang] [HLSL][Doc] Add doc about expected differences (PR #82395)

[Justin Bogner via cfe-commits]

@@ -0,0 +1,108 @@
+
+Expected Differences vs DXC and FXC
+===
+
+.. contents::
+   :local:
+
+Introduction
+
+
+HLSL currently has two reference compilers, the `DirectX Shader Compiler (DXC)
+`_ and the
+`Effect-Compiler (FXC) 
`_.
+The two reference compilers do not fully agree. Some known disagreements in the
+references are tracked on
+`DXC's GitHub
+`_,
+but many more are known to exist.
+
+HLSL as implemented by Clang will also not fully match either of the reference
+implementations, it is instead being written to match the `draft language
+specification `_.
+
+This document is a non-exhaustive collection the known differences between
+Clang's implementation of HLSL and the existing reference compilers.
+
+General Principles
+--
+
+Most of the intended differences between Clang and the earlier reference
+compilers are focused on increased consistency and correctness. Both reference
+compilers do not always apply language rules the same in all contexts.
+
+Clang also deviates from the reference compilers by providing different
+diagnostics, both in terms of the textual messages and the contexts in which
+diagnostics are produced. While striving for a high level of source
+compatibility with conforming HLSL code, Clang may produce earlier and more
+robust diagnostics for incorrect code or reject code that a reference compiler
+incorrectly accepted.
+
+Language Version
+
+
+Clang targets language compatibility for HLSL 2021 as implemented by DXC.
+Language features that were removed in earlier versions of HLSL may be added on
+a case-by-case basis, but are not planned for the initial implementation.
+
+Overload Resolution
+===
+
+Clang's HLSL implementation adopts C++ overload resolution rules as proposed 
for
+HLSL 202x based on proposal
+`0007 
`_
+and
+`0008 
`_.
+
+Clang's implementation extends standard overload resolution rules to HLSL
+library functionality. This causes subtle changes in overload resolution
+behavior between Clang and DXC. Some examples include:
+
+.. code-block:: c++
+
+  void halfOrInt16(half H);
+  void halfOrInt16(uint16_t I);
+
+  void takesDoubles(double, double, double);
+
+  cbuffer CB {
+uint U;
+uint I;
+float X, Y, Z;
+double3 A, B;
+  }
+
+  export void call() {
+halfOrInt16(U); // All: Resolves to halfOrInt16(uint16_t).
+halfOrInt16(I); // All: Resolves to halfOrInt16(uint16_t).
+  #ifndef IGNORE_ERRORS
+half H = asfloat16(I); // DXC: Fails to resolve overload for int.
+  // Clang: Resolves to asfloat16(uint16_t).
+half H = asfloat16(U); // DXC: Fails to resolve overload for int.
+  // Clang: Resolves to asfloat16(uint16_t).
+  #endif
+half H = asfloat16(0x01); // DXC: Resolves to asfloat16(half).
+  // Clang: Resolves to asfloat16(uint16_t).
+
+takesDoubles(X, Y, Z); // Works on all compilers
+  #ifndef IGNORE_ERRORS
+fma(X, Y, Z); // DXC: Fails to resolve no known conversion from float to 
double.
+  // Clang: Resolces to fma(double,double,double).

bogner wrote:

Typo: "Resolces"

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

[clang] [HLSL][Doc] Add doc about expected differences (PR #82395)

[Justin Bogner via cfe-commits]

@@ -0,0 +1,108 @@
+
+Expected Differences vs DXC and FXC
+===
+
+.. contents::
+   :local:
+
+Introduction
+
+
+HLSL currently has two reference compilers, the `DirectX Shader Compiler (DXC)
+`_ and the
+`Effect-Compiler (FXC) 
`_.
+The two reference compilers do not fully agree. Some known disagreements in the
+references are tracked on
+`DXC's GitHub
+`_,
+but many more are known to exist.
+
+HLSL as implemented by Clang will also not fully match either of the reference
+implementations, it is instead being written to match the `draft language
+specification `_.
+
+This document is a non-exhaustive collection the known differences between
+Clang's implementation of HLSL and the existing reference compilers.
+
+General Principles
+--
+
+Most of the intended differences between Clang and the earlier reference
+compilers are focused on increased consistency and correctness. Both reference
+compilers do not always apply language rules the same in all contexts.
+
+Clang also deviates from the reference compilers by providing different
+diagnostics, both in terms of the textual messages and the contexts in which
+diagnostics are produced. While striving for a high level of source
+compatibility with conforming HLSL code, Clang may produce earlier and more
+robust diagnostics for incorrect code or reject code that a reference compiler
+incorrectly accepted.
+
+Language Version
+
+
+Clang targets language compatibility for HLSL 2021 as implemented by DXC.
+Language features that were removed in earlier versions of HLSL may be added on
+a case-by-case basis, but are not planned for the initial implementation.
+
+Overload Resolution
+===
+
+Clang's HLSL implementation adopts C++ overload resolution rules as proposed 
for
+HLSL 202x based on proposal
+`0007 
`_
+and
+`0008 
`_.
+
+Clang's implementation extends standard overload resolution rules to HLSL
+library functionality. This causes subtle changes in overload resolution
+behavior between Clang and DXC. Some examples include:
+
+.. code-block:: c++
+
+  void halfOrInt16(half H);
+  void halfOrInt16(uint16_t I);
+
+  void takesDoubles(double, double, double);
+
+  cbuffer CB {
+uint U;
+uint I;
+float X, Y, Z;
+double3 A, B;
+  }
+
+  export void call() {
+halfOrInt16(U); // All: Resolves to halfOrInt16(uint16_t).
+halfOrInt16(I); // All: Resolves to halfOrInt16(uint16_t).
+  #ifndef IGNORE_ERRORS
+half H = asfloat16(I); // DXC: Fails to resolve overload for int.
+  // Clang: Resolves to asfloat16(uint16_t).
+half H = asfloat16(U); // DXC: Fails to resolve overload for int.
+  // Clang: Resolves to asfloat16(uint16_t).
+  #endif
+half H = asfloat16(0x01); // DXC: Resolves to asfloat16(half).
+  // Clang: Resolves to asfloat16(uint16_t).

bogner wrote:

Not sure how best to present it, since it's a builtin, but it might be nice to 
point out what the overload set of `asfloat16` is to clarify what the actual 
difference in behaviour is here.

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

[clang] [HLSL][Doc] Add doc about expected differences (PR #82395)

[Justin Bogner via cfe-commits]

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


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

[clang] [HLSL][Doc] Add doc about expected differences (PR #82395)

[Justin Bogner via cfe-commits]

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

[clang] [HLSL][Doc] Add doc about expected differences (PR #82395)

[Chris B via cfe-commits]

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

>From 558dd6182a4dc6fc5c5383358cac422289a7a90b Mon Sep 17 00:00:00 2001
From: Chris Bieneman 
Date: Tue, 20 Feb 2024 12:01:16 -0600
Subject: [PATCH 1/2] [HLSL][Doc] Add doc about expected differences

This document covers expected differences between Clang and the HLSL
reference compiler implementations (FXC & DXC). The document is not
intended to be exhaustive, but it should be a best effort to cover known
cases.

This document should document both the behavioral difference and the
explanation of why Clang differs.

The initail document covers known overload resolution differences.
---
 clang/docs/HLSL/ExpectedDifferences.rst | 108 
 clang/docs/HLSL/HLSLDocs.rst|   1 +
 2 files changed, 109 insertions(+)
 create mode 100644 clang/docs/HLSL/ExpectedDifferences.rst

diff --git a/clang/docs/HLSL/ExpectedDifferences.rst 
b/clang/docs/HLSL/ExpectedDifferences.rst
new file mode 100644
index 00..f1d52b52092466
--- /dev/null
+++ b/clang/docs/HLSL/ExpectedDifferences.rst
@@ -0,0 +1,108 @@
+
+Expected Differences vs DXC and FXC
+===
+
+.. contents::
+   :local:
+
+Introduction
+
+
+HLSL currently has two reference compilers, the `DirectX Shader Compiler (DXC)
+`_ and the
+`Effect-Compiler (FXC) 
`_.
+The two reference compilers do not fully agree. Some known disagreements in the
+references are tracked on
+`DXC's GitHub
+`_,
+but many more are known to exist.
+
+HLSL as implemented by Clang will also not fully match either of the reference
+implementations, it is instead being written to match the `draft language
+specification `_.
+
+This document is a non-exhaustive collection the known differences between
+Clang's implementation of HLSL and the existing reference compilers.
+
+General Principles
+--
+
+Most of the intended differences between Clang and the earlier reference
+compilers are focused on increased consistency and correctness. Both reference
+compilers do not always apply language rules the same in all contexts.
+
+Clang also deviates from the reference compilers by providing different
+diagnostics, both in terms of the textual messages and the contexts in which
+diagnostics are produced. While striving for a high level of source
+compatibility with conforming HLSL code, Clang may produce earlier and more
+robust diagnostics for incorrect code or reject code that a reference compiler
+incorrectly accepted.
+
+Language Version
+
+
+Clang targets language compatibility for HLSL 2021 as implemented by DXC.
+Language features that were removed in earlier versions of HLSL may be added on
+a case-by-case basis, but are not planned for the initial implementation.
+
+Overload Resolution
+===
+
+Clang's HLSL implementation adopts C++ overload resolution rules as proposed 
for
+HLSL 202x based on proposal
+`0007 
`_
+and
+`0008 
`_.
+
+Clang's implementation extends standard overload resolution rules to HLSL
+library functionality. This causes subtle changes in overload resolution
+behavior between Clang and DXC. Some examples include:
+
+.. code-block:: c++
+
+  void halfOrInt16(half H);
+  void halfOrInt16(uint16_t I);
+
+  void takesDoubles(double, double, double);
+
+  cbuffer CB {
+uint U;
+uint I;
+float X, Y, Z;
+double3 A, B;
+  }
+
+  export void call() {
+halfOrInt16(U); // All: Resolves to halfOrInt16(uint16_t).
+halfOrInt16(I); // All: Resolves to halfOrInt16(uint16_t).
+  #ifndef IGNORE_ERRORS
+half H = asfloat16(I); // DXC: Fails to resolve overload for int.
+  // Clang: Resolves to halfOrInt16(uint16_t).
+half H = asfloat16(U); // DXC: Fails to resolve overload for int.
+  // Clang: Resolves to halfOrInt16(uint16_t).
+  #endif
+half H = asfloat16(0x01); // DXC: Resolves to halfOrInt16(half).
+  // Clang: Resolves to halfOrInt16(uint16_t).
+
+takesDoubles(X, Y, Z); // Works on all compilers
+  #ifndef IGNORE_ERRORS
+fma(X, Y, Z); // DXC: Fails to resolve no known conversion from float to 
double.
+  // Clang: Resolces to fma(double,double,double).
+  #endif
+
+double D = dot(A, B); // DXC: Resolves to dot(double3, double3), fails 
DXIL Validation.
+  // FXC: Expands to compute double dot product with 
fmul/fadd
+  // 

[clang] [HLSL][Doc] Add doc about expected differences (PR #82395)

[David Peixotto via cfe-commits]

@@ -0,0 +1,108 @@
+
+Expected Differences vs DXC and FXC
+===
+
+.. contents::
+   :local:
+
+Introduction
+
+
+HLSL currently has two reference compilers, the `DirectX Shader Compiler (DXC)
+`_ and the
+`Effect-Compiler (FXC) 
`_.
+The two reference compilers do not fully agree. Some known disagreements in the
+references are tracked on
+`DXC's GitHub
+`_,
+but many more are known to exist.
+
+HLSL as implemented by Clang will also not fully match either of the reference
+implementations, it is instead being written to match the `draft language
+specification `_.
+
+This document is a non-exhaustive collection the known differences between
+Clang's implementation of HLSL and the existing reference compilers.
+
+General Principles
+--
+
+Most of the intended differences between Clang and the earlier reference
+compilers are focused on increased consistency and correctness. Both reference
+compilers do not always apply language rules the same in all contexts.
+
+Clang also deviates from the reference compilers by providing different
+diagnostics, both in terms of the textual messages and the contexts in which
+diagnostics are produced. While striving for a high level of source
+compatibility with conforming HLSL code, Clang may produce earlier and more
+robust diagnostics for incorrect code or reject code that a reference compiler
+incorrectly accepted.
+
+Language Version
+
+
+Clang targets language compatibility for HLSL 2021 as implemented by DXC.
+Language features that were removed in earlier versions of HLSL may be added on
+a case-by-case basis, but are not planned for the initial implementation.
+
+Overload Resolution
+===
+
+Clang's HLSL implementation adopts C++ overload resolution rules as proposed 
for
+HLSL 202x based on proposal
+`0007 
`_
+and
+`0008 
`_.
+
+Clang's implementation extends standard overload resolution rules to HLSL
+library functionality. This causes subtle changes in overload resolution
+behavior between Clang and DXC. Some examples include:
+
+.. code-block:: c++
+
+  void halfOrInt16(half H);
+  void halfOrInt16(uint16_t I);
+
+  void takesDoubles(double, double, double);
+
+  cbuffer CB {
+uint U;
+uint I;
+float X, Y, Z;
+double3 A, B;
+  }
+
+  export void call() {
+halfOrInt16(U); // All: Resolves to halfOrInt16(uint16_t).
+halfOrInt16(I); // All: Resolves to halfOrInt16(uint16_t).
+  #ifndef IGNORE_ERRORS
+half H = asfloat16(I); // DXC: Fails to resolve overload for int.
+  // Clang: Resolves to halfOrInt16(uint16_t).

dmpots wrote:

Looks like there is a typo in the comment here and a few places below: 
`halfOfInt16` -> `asfloat16`

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

[clang] [HLSL][Doc] Add doc about expected differences (PR #82395)

[David Peixotto via cfe-commits]

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


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

[clang] [HLSL][Doc] Add doc about expected differences (PR #82395)

[David Peixotto via cfe-commits]

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

[clang] [HLSL][Doc] Add doc about expected differences (PR #82395)

[Xiang Li via cfe-commits]

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


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

[clang] [HLSL][Doc] Add doc about expected differences (PR #82395)

[via cfe-commits]

llvmbot wrote:




@llvm/pr-subscribers-hlsl

Author: Chris B (llvm-beanz)


Changes

This document covers expected differences between Clang and the HLSL reference 
compiler implementations (FXC  DXC). The document is not intended to be 
exhaustive, but it should be a best effort to cover known cases.

This document should document both the behavioral difference and the 
explanation of why Clang differs.

The initail document covers known overload resolution differences.

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


2 Files Affected:

- (added) clang/docs/HLSL/ExpectedDifferences.rst (+108) 
- (modified) clang/docs/HLSL/HLSLDocs.rst (+1) 


``diff
diff --git a/clang/docs/HLSL/ExpectedDifferences.rst 
b/clang/docs/HLSL/ExpectedDifferences.rst
new file mode 100644
index 00..f1d52b52092466
--- /dev/null
+++ b/clang/docs/HLSL/ExpectedDifferences.rst
@@ -0,0 +1,108 @@
+
+Expected Differences vs DXC and FXC
+===
+
+.. contents::
+   :local:
+
+Introduction
+
+
+HLSL currently has two reference compilers, the `DirectX Shader Compiler (DXC)
+`_ and the
+`Effect-Compiler (FXC) 
`_.
+The two reference compilers do not fully agree. Some known disagreements in the
+references are tracked on
+`DXC's GitHub
+`_,
+but many more are known to exist.
+
+HLSL as implemented by Clang will also not fully match either of the reference
+implementations, it is instead being written to match the `draft language
+specification `_.
+
+This document is a non-exhaustive collection the known differences between
+Clang's implementation of HLSL and the existing reference compilers.
+
+General Principles
+--
+
+Most of the intended differences between Clang and the earlier reference
+compilers are focused on increased consistency and correctness. Both reference
+compilers do not always apply language rules the same in all contexts.
+
+Clang also deviates from the reference compilers by providing different
+diagnostics, both in terms of the textual messages and the contexts in which
+diagnostics are produced. While striving for a high level of source
+compatibility with conforming HLSL code, Clang may produce earlier and more
+robust diagnostics for incorrect code or reject code that a reference compiler
+incorrectly accepted.
+
+Language Version
+
+
+Clang targets language compatibility for HLSL 2021 as implemented by DXC.
+Language features that were removed in earlier versions of HLSL may be added on
+a case-by-case basis, but are not planned for the initial implementation.
+
+Overload Resolution
+===
+
+Clang's HLSL implementation adopts C++ overload resolution rules as proposed 
for
+HLSL 202x based on proposal
+`0007 
`_
+and
+`0008 
`_.
+
+Clang's implementation extends standard overload resolution rules to HLSL
+library functionality. This causes subtle changes in overload resolution
+behavior between Clang and DXC. Some examples include:
+
+.. code-block:: c++
+
+  void halfOrInt16(half H);
+  void halfOrInt16(uint16_t I);
+
+  void takesDoubles(double, double, double);
+
+  cbuffer CB {
+uint U;
+uint I;
+float X, Y, Z;
+double3 A, B;
+  }
+
+  export void call() {
+halfOrInt16(U); // All: Resolves to halfOrInt16(uint16_t).
+halfOrInt16(I); // All: Resolves to halfOrInt16(uint16_t).
+  #ifndef IGNORE_ERRORS
+half H = asfloat16(I); // DXC: Fails to resolve overload for int.
+  // Clang: Resolves to halfOrInt16(uint16_t).
+half H = asfloat16(U); // DXC: Fails to resolve overload for int.
+  // Clang: Resolves to halfOrInt16(uint16_t).
+  #endif
+half H = asfloat16(0x01); // DXC: Resolves to halfOrInt16(half).
+  // Clang: Resolves to halfOrInt16(uint16_t).
+
+takesDoubles(X, Y, Z); // Works on all compilers
+  #ifndef IGNORE_ERRORS
+fma(X, Y, Z); // DXC: Fails to resolve no known conversion from float to 
double.
+  // Clang: Resolces to fma(double,double,double).
+  #endif
+
+double D = dot(A, B); // DXC: Resolves to dot(double3, double3), fails 
DXIL Validation.
+  // FXC: Expands to compute double dot product with 
fmul/fadd
+  // Clang: Resolves to dot(float3, float3), emits 
conversion warnings.
+
+  }
+
+`Compiler Explorer `_
+
+.. note::
+
+  In Clang a conscious decision was made to exclude the 

[clang] [HLSL][Doc] Add doc about expected differences (PR #82395)

[Chris B via cfe-commits]

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

This document covers expected differences between Clang and the HLSL reference 
compiler implementations (FXC & DXC). The document is not intended to be 
exhaustive, but it should be a best effort to cover known cases.

This document should document both the behavioral difference and the 
explanation of why Clang differs.

The initail document covers known overload resolution differences.

>From 558dd6182a4dc6fc5c5383358cac422289a7a90b Mon Sep 17 00:00:00 2001
From: Chris Bieneman 
Date: Tue, 20 Feb 2024 12:01:16 -0600
Subject: [PATCH] [HLSL][Doc] Add doc about expected differences

This document covers expected differences between Clang and the HLSL
reference compiler implementations (FXC & DXC). The document is not
intended to be exhaustive, but it should be a best effort to cover known
cases.

This document should document both the behavioral difference and the
explanation of why Clang differs.

The initail document covers known overload resolution differences.
---
 clang/docs/HLSL/ExpectedDifferences.rst | 108 
 clang/docs/HLSL/HLSLDocs.rst|   1 +
 2 files changed, 109 insertions(+)
 create mode 100644 clang/docs/HLSL/ExpectedDifferences.rst

diff --git a/clang/docs/HLSL/ExpectedDifferences.rst 
b/clang/docs/HLSL/ExpectedDifferences.rst
new file mode 100644
index 00..f1d52b52092466
--- /dev/null
+++ b/clang/docs/HLSL/ExpectedDifferences.rst
@@ -0,0 +1,108 @@
+
+Expected Differences vs DXC and FXC
+===
+
+.. contents::
+   :local:
+
+Introduction
+
+
+HLSL currently has two reference compilers, the `DirectX Shader Compiler (DXC)
+`_ and the
+`Effect-Compiler (FXC) 
`_.
+The two reference compilers do not fully agree. Some known disagreements in the
+references are tracked on
+`DXC's GitHub
+`_,
+but many more are known to exist.
+
+HLSL as implemented by Clang will also not fully match either of the reference
+implementations, it is instead being written to match the `draft language
+specification `_.
+
+This document is a non-exhaustive collection the known differences between
+Clang's implementation of HLSL and the existing reference compilers.
+
+General Principles
+--
+
+Most of the intended differences between Clang and the earlier reference
+compilers are focused on increased consistency and correctness. Both reference
+compilers do not always apply language rules the same in all contexts.
+
+Clang also deviates from the reference compilers by providing different
+diagnostics, both in terms of the textual messages and the contexts in which
+diagnostics are produced. While striving for a high level of source
+compatibility with conforming HLSL code, Clang may produce earlier and more
+robust diagnostics for incorrect code or reject code that a reference compiler
+incorrectly accepted.
+
+Language Version
+
+
+Clang targets language compatibility for HLSL 2021 as implemented by DXC.
+Language features that were removed in earlier versions of HLSL may be added on
+a case-by-case basis, but are not planned for the initial implementation.
+
+Overload Resolution
+===
+
+Clang's HLSL implementation adopts C++ overload resolution rules as proposed 
for
+HLSL 202x based on proposal
+`0007 
`_
+and
+`0008 
`_.
+
+Clang's implementation extends standard overload resolution rules to HLSL
+library functionality. This causes subtle changes in overload resolution
+behavior between Clang and DXC. Some examples include:
+
+.. code-block:: c++
+
+  void halfOrInt16(half H);
+  void halfOrInt16(uint16_t I);
+
+  void takesDoubles(double, double, double);
+
+  cbuffer CB {
+uint U;
+uint I;
+float X, Y, Z;
+double3 A, B;
+  }
+
+  export void call() {
+halfOrInt16(U); // All: Resolves to halfOrInt16(uint16_t).
+halfOrInt16(I); // All: Resolves to halfOrInt16(uint16_t).
+  #ifndef IGNORE_ERRORS
+half H = asfloat16(I); // DXC: Fails to resolve overload for int.
+  // Clang: Resolves to halfOrInt16(uint16_t).
+half H = asfloat16(U); // DXC: Fails to resolve overload for int.
+  // Clang: Resolves to halfOrInt16(uint16_t).
+  #endif
+half H = asfloat16(0x01); // DXC: Resolves to halfOrInt16(half).
+  // Clang: Resolves to halfOrInt16(uint16_t).
+
+takesDoubles(X, Y, Z); // Works on all compilers
+  #ifndef