[PATCH] D123278: [Clang] [Docs] Add HLSLSupport page

[Chris Bieneman via Phabricator via cfe-commits]

This revision was landed with ongoing or failed builds.
This revision was automatically updated to reflect the committed changes.
Closed by commit rG9e3678e16155: [Clang] [Docs] Add HLSLSupport page (authored 
by beanz).

Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D123278/new/

https://reviews.llvm.org/D123278

Files:
  clang/docs/HLSLSupport.rst
  clang/docs/index.rst

Index: clang/docs/index.rst
===
--- clang/docs/index.rst
+++ clang/docs/index.rst
@@ -45,6 +45,7 @@
OpenCLSupport
OpenMPSupport
SYCLSupport
+   HLSLSupport
ThinLTO
APINotes
CommandGuide/index
Index: clang/docs/HLSLSupport.rst
===
--- /dev/null
+++ clang/docs/HLSLSupport.rst
@@ -0,0 +1,240 @@
+
+HLSL Support
+
+
+.. contents::
+   :local:
+
+Introduction
+
+
+HLSL Support is under active development in the Clang codebase. This document
+describes the high level goals of the project, the guiding principles, as well
+as some idiosyncrasies of the HLSL language and how we intend to support them in
+Clang.
+
+Project Goals
+=
+
+The long term goal of this project is to enable Clang to function as a
+replacement for the `DirectXShaderCompiler (DXC)
+`_ in all its supported
+use cases. Accomplishing that goal will require Clang to be able to process most
+existing HLSL programs with a high degree of source compatibility.
+
+Non-Goals
+-
+
+HLSL ASTs do not need to be compatible between DXC and Clang. We do not expect
+identical code generation or that features will resemble DXC's implementation or
+architecture. In fact, we explicitly expect to deviate from DXC's implementation
+in key ways.
+
+Guiding Principles
+==
+
+This document lacks details for architectural decisions that are not yet
+finalized. Our top priorities are quality, maintainability, and flexibility. In
+accordance with community standards we are expecting a high level of test
+coverage, and we will engineer our solutions with long term maintenance in mind.
+We are also working to limit modifications to the Clang C++ code paths and
+share as much functionality as possible.
+
+Architectural Direction
+===
+
+HLSL support in Clang is expressed as C++ minus unsupported C and C++ features.
+This is different from how other Clang languages are implemented. Most languages
+in Clang are additive on top of C.
+
+HLSL is not a formally or fully specified language, and while our goals require
+a high level of source compatibility, implementations can vary and we have some
+flexibility to be more or less permissive in some cases. For modern HLSL DXC is
+the reference implementation.
+
+The HLSL effort prioritizes following similar patterns for other languages,
+drivers, runtimes and targets. Specifically, We will maintain separation between
+HSLS-specific code and the rest of Clang as much as possible following patterns
+in use in Clang code today (i.e. ParseHLSL.cpp, SemaHLSL.cpp, CGHLSL*.cpp...).
+We will use inline checks on language options where the code is simple and
+isolated, and prefer HLSL-specific implementation files for any code of
+reasonable complexity.
+
+In places where the HLSL language is in conflict with C and C++, we will seek to
+make minimally invasive changes guarded under the HLSL language options. We will
+seek to make HLSL language support as minimal a maintenance burden as possible.
+
+DXC Driver
+--
+
+A DXC driver mode will provide command-line compatibility with DXC, supporting
+DXC's options and flags. The DXC driver is HLSL-specific and will create an
+HLSLToolchain which will provide the basis to support targeting both DirectX and
+Vulkan.
+
+Parser
+--
+
+Following the examples of other parser extensions HLSL will add a ParseHLSL.cpp
+file to contain the implementations of HLSL-specific extensions to the Clang
+parser. The HLSL grammar shares most of its structure with C and C++, so we will
+use the existing C/C++ parsing code paths.
+
+Sema
+
+
+HLSL's Sema implementation will also provide an ``ExternalSemaSource``. In DXC,
+an ``ExternalSemaSource`` is used to provide definitions for HLSL built-in data
+types and built-in templates. Clang is already designed to allow an attached
+``ExternalSemaSource`` to lazily complete data types, which is a **huge**
+performance win for HLSL.
+
+CodeGen
+---
+
+Like OpenCL, HLSL relies on capturing a lot of information into IR metadata.
+*hand wave* *hand wave* *hand wave* As a design principle here we want our IR to
+be idiomatic Clang IR as much as possible. We will use IR attributes wherever we
+can, and use metadata as sparingly as possible. One example of a difference from
+DXC already implemented in Clang is the use of target triples to communicate

[PATCH] D123278: [Clang] [Docs] Add HLSLSupport page

[Aaron Ballman via Phabricator via cfe-commits]

aaron.ballman accepted this revision.
aaron.ballman added a comment.

LGTM!




Comment at: clang/docs/HLSLSupport.rst:150-152
+HLSL has a ``precise`` qualifier that behaves unlike anything else in the C
+language. The support for this qualifier in DXC is buggy, so our bar for
+compatibility is low.

beanz wrote:
> aaron.ballman wrote:
> > beanz wrote:
> > > aaron.ballman wrote:
> > > > beanz wrote:
> > > > > aaron.ballman wrote:
> > > > > > Is it worth supporting at all (I know you want source 
> > > > > > compatibility...)? Type system changes are generally expensive and 
> > > > > > invasive, largely because changing the type system in C++ is 
> > > > > > complicated. For example, does this qualifier impact overload sets 
> > > > > > or template specializations? Does it get name mangled? That sort of 
> > > > > > thing.
> > > > > Unfortunately we do need to implement it to some degree. In DXC it is 
> > > > > implemented as an attribute rather than a qualifier, so it shouldn't 
> > > > > impact overloads, template specialization or mangling.
> > > > > 
> > > > > I call it a qualifier here because it is syntactically more like a 
> > > > > qualifier, but I'm honestly not sure how we should implement it. In 
> > > > > DXC, we emit IR metadata denoting the underlying value as "precise", 
> > > > > then in an IR pass propagate disabling fast math.
> > > > > Unfortunately we do need to implement it to some degree. In DXC it is 
> > > > > implemented as an attribute rather than a qualifier, so it shouldn't 
> > > > > impact overloads, template specialization or mangling.
> > > > 
> > > > Okay, I kind of figured you needed it.
> > > > 
> > > > > I call it a qualifier here because it is syntactically more like a 
> > > > > qualifier, but I'm honestly not sure how we should implement it. In 
> > > > > DXC, we emit IR metadata denoting the underlying value as "precise", 
> > > > > then in an IR pass propagate disabling fast math.
> > > > 
> > > > This smells more like an attribute than a qualifier to me, but I'd like 
> > > > to see if I understand first (please ignore if I get syntax wrong):
> > > > ```
> > > > // Initialization
> > > > precise float f = 1.0 / 3.0 * sinf(3.14f); // value computation is 
> > > > precise
> > > > // Assignment
> > > > f = 1.0 / 3.0 * sinf(3.14f); // value computation is NOT precise (not a 
> > > > declaration)?
> > > > // RHS of expression
> > > > float f2 = f * 2.0; // value computation is NOT precise (f2 is not 
> > > > marked precise)?
> > > > ```
> > > > 
> > > Yea, your syntax and behavior is correct with the added complication that 
> > > precise upward propagates. The upward propagation is the part that is 
> > > wonky and problematic.
> > > 
> > > ```
> > > float f = 1.0 * sinf(3.14f); // precise
> > > precise float f2 = f / 2.0f; // precise
> > > float f3 = f * f2; // not precise
> > > ```
> > > 
> > Sorry if I'm being dense, but I'm still lost. Why is `f` precise in your 
> > example?
> > 
> > But more interestingly, is this a property of the *initialization* of the 
> > variable of that type only, or is it a property of the type itself where 
> > arbitrary expressions involving that type need to care whether it's precise 
> > or not?
> > 
> > If it's just about the initialization, then I think a declaration attribute 
> > is the clear winner for the semantic support. If it needs to be tracked 
> > through arbitrary expressions involving the type, it's probably better as a 
> > qualifier sort of like the nullability ones. e.g.,
> > ```
> > template 
> > void func(Ty Val) {
> >   Val += 1.0f // Does this get precise semantics?
> > }
> > 
> > int main() {
> >   precise float f = 1.0f;
> >   func(f);
> > }
> > ```
> > 
> > 
> `precise` behaves unlike anything I've ever encountered in a programming 
> language before. It neither follows the type nor the declared value.
> 
> `precise` never propagates down (so a use of a `precise` value does not make 
> subsequent things `precise`. It does propagate up to values that contribute 
> to the `precise`, which is just... weird.
> 
> I don't know whether HLSL or GLSL (or some other SL) did it first, but GLSL 
> has a spec which states:
> 
> > The **precise** qualifier ensures that operations contributing to a 
> > variable's value are done  in their stated order and with operator 
> > consistency.
> 
> The GLSL spec expands into a whole lot more details and examples:
> https://www.khronos.org/registry/OpenGL/specs/gl/GLSLangSpec.4.60.pdf
> 
> HLSL's behavior //should// match GLSL (and some other vendor-specific 
> languages), but frequently doesn't.
(I need to shower after learning this cursed knowledge, and I fear I will never 
be clean again.)

Thank you for the discussion on this (both here and on IRC). It sounds like we 
could get away with using a declaration attribute and then punt all the 
complexity back to the backend which handles it entirely from the 
initialization of the marked-precise 

[PATCH] D123278: [Clang] [Docs] Add HLSLSupport page

[Chris Bieneman via Phabricator via cfe-commits]

beanz added inline comments.



Comment at: clang/docs/HLSLSupport.rst:150-152
+HLSL has a ``precise`` qualifier that behaves unlike anything else in the C
+language. The support for this qualifier in DXC is buggy, so our bar for
+compatibility is low.

aaron.ballman wrote:
> beanz wrote:
> > aaron.ballman wrote:
> > > beanz wrote:
> > > > aaron.ballman wrote:
> > > > > Is it worth supporting at all (I know you want source 
> > > > > compatibility...)? Type system changes are generally expensive and 
> > > > > invasive, largely because changing the type system in C++ is 
> > > > > complicated. For example, does this qualifier impact overload sets or 
> > > > > template specializations? Does it get name mangled? That sort of 
> > > > > thing.
> > > > Unfortunately we do need to implement it to some degree. In DXC it is 
> > > > implemented as an attribute rather than a qualifier, so it shouldn't 
> > > > impact overloads, template specialization or mangling.
> > > > 
> > > > I call it a qualifier here because it is syntactically more like a 
> > > > qualifier, but I'm honestly not sure how we should implement it. In 
> > > > DXC, we emit IR metadata denoting the underlying value as "precise", 
> > > > then in an IR pass propagate disabling fast math.
> > > > Unfortunately we do need to implement it to some degree. In DXC it is 
> > > > implemented as an attribute rather than a qualifier, so it shouldn't 
> > > > impact overloads, template specialization or mangling.
> > > 
> > > Okay, I kind of figured you needed it.
> > > 
> > > > I call it a qualifier here because it is syntactically more like a 
> > > > qualifier, but I'm honestly not sure how we should implement it. In 
> > > > DXC, we emit IR metadata denoting the underlying value as "precise", 
> > > > then in an IR pass propagate disabling fast math.
> > > 
> > > This smells more like an attribute than a qualifier to me, but I'd like 
> > > to see if I understand first (please ignore if I get syntax wrong):
> > > ```
> > > // Initialization
> > > precise float f = 1.0 / 3.0 * sinf(3.14f); // value computation is precise
> > > // Assignment
> > > f = 1.0 / 3.0 * sinf(3.14f); // value computation is NOT precise (not a 
> > > declaration)?
> > > // RHS of expression
> > > float f2 = f * 2.0; // value computation is NOT precise (f2 is not marked 
> > > precise)?
> > > ```
> > > 
> > Yea, your syntax and behavior is correct with the added complication that 
> > precise upward propagates. The upward propagation is the part that is wonky 
> > and problematic.
> > 
> > ```
> > float f = 1.0 * sinf(3.14f); // precise
> > precise float f2 = f / 2.0f; // precise
> > float f3 = f * f2; // not precise
> > ```
> > 
> Sorry if I'm being dense, but I'm still lost. Why is `f` precise in your 
> example?
> 
> But more interestingly, is this a property of the *initialization* of the 
> variable of that type only, or is it a property of the type itself where 
> arbitrary expressions involving that type need to care whether it's precise 
> or not?
> 
> If it's just about the initialization, then I think a declaration attribute 
> is the clear winner for the semantic support. If it needs to be tracked 
> through arbitrary expressions involving the type, it's probably better as a 
> qualifier sort of like the nullability ones. e.g.,
> ```
> template 
> void func(Ty Val) {
>   Val += 1.0f // Does this get precise semantics?
> }
> 
> int main() {
>   precise float f = 1.0f;
>   func(f);
> }
> ```
> 
> 
`precise` behaves unlike anything I've ever encountered in a programming 
language before. It neither follows the type nor the declared value.

`precise` never propagates down (so a use of a `precise` value does not make 
subsequent things `precise`. It does propagate up to values that contribute to 
the `precise`, which is just... weird.

I don't know whether HLSL or GLSL (or some other SL) did it first, but GLSL has 
a spec which states:

> The **precise** qualifier ensures that operations contributing to a 
> variable's value are done  in their stated order and with operator 
> consistency.

The GLSL spec expands into a whole lot more details and examples:
https://www.khronos.org/registry/OpenGL/specs/gl/GLSLangSpec.4.60.pdf

HLSL's behavior //should// match GLSL (and some other vendor-specific 
languages), but frequently doesn't.



Comment at: clang/docs/HLSLSupport.rst:197
+* Any use of the ``virtual`` keyword
+* Most features C++11 and later

aaron.ballman wrote:
> beanz wrote:
> > aaron.ballman wrote:
> > > beanz wrote:
> > > > aaron.ballman wrote:
> > > > > Same question here as above with C on whether we expect to support 
> > > > > those as extensions or diagnose them as invalid.
> > > > I didn't really answer that above. I am inclined to do a mix of both. 
> > > > Anything that we can support and lower I'd like to treat as extensions. 
> > > > Some things we just can't.
> > > > 
> > > > We don't 

[PATCH] D123278: [Clang] [Docs] Add HLSLSupport page

[Aaron Ballman via Phabricator via cfe-commits]

aaron.ballman added inline comments.



Comment at: clang/docs/HLSLSupport.rst:150-152
+HLSL has a ``precise`` qualifier that behaves unlike anything else in the C
+language. The support for this qualifier in DXC is buggy, so our bar for
+compatibility is low.

beanz wrote:
> aaron.ballman wrote:
> > beanz wrote:
> > > aaron.ballman wrote:
> > > > Is it worth supporting at all (I know you want source 
> > > > compatibility...)? Type system changes are generally expensive and 
> > > > invasive, largely because changing the type system in C++ is 
> > > > complicated. For example, does this qualifier impact overload sets or 
> > > > template specializations? Does it get name mangled? That sort of thing.
> > > Unfortunately we do need to implement it to some degree. In DXC it is 
> > > implemented as an attribute rather than a qualifier, so it shouldn't 
> > > impact overloads, template specialization or mangling.
> > > 
> > > I call it a qualifier here because it is syntactically more like a 
> > > qualifier, but I'm honestly not sure how we should implement it. In DXC, 
> > > we emit IR metadata denoting the underlying value as "precise", then in 
> > > an IR pass propagate disabling fast math.
> > > Unfortunately we do need to implement it to some degree. In DXC it is 
> > > implemented as an attribute rather than a qualifier, so it shouldn't 
> > > impact overloads, template specialization or mangling.
> > 
> > Okay, I kind of figured you needed it.
> > 
> > > I call it a qualifier here because it is syntactically more like a 
> > > qualifier, but I'm honestly not sure how we should implement it. In DXC, 
> > > we emit IR metadata denoting the underlying value as "precise", then in 
> > > an IR pass propagate disabling fast math.
> > 
> > This smells more like an attribute than a qualifier to me, but I'd like to 
> > see if I understand first (please ignore if I get syntax wrong):
> > ```
> > // Initialization
> > precise float f = 1.0 / 3.0 * sinf(3.14f); // value computation is precise
> > // Assignment
> > f = 1.0 / 3.0 * sinf(3.14f); // value computation is NOT precise (not a 
> > declaration)?
> > // RHS of expression
> > float f2 = f * 2.0; // value computation is NOT precise (f2 is not marked 
> > precise)?
> > ```
> > 
> Yea, your syntax and behavior is correct with the added complication that 
> precise upward propagates. The upward propagation is the part that is wonky 
> and problematic.
> 
> ```
> float f = 1.0 * sinf(3.14f); // precise
> precise float f2 = f / 2.0f; // precise
> float f3 = f * f2; // not precise
> ```
> 
Sorry if I'm being dense, but I'm still lost. Why is `f` precise in your 
example?

But more interestingly, is this a property of the *initialization* of the 
variable of that type only, or is it a property of the type itself where 
arbitrary expressions involving that type need to care whether it's precise or 
not?

If it's just about the initialization, then I think a declaration attribute is 
the clear winner for the semantic support. If it needs to be tracked through 
arbitrary expressions involving the type, it's probably better as a qualifier 
sort of like the nullability ones. e.g.,
```
template 
void func(Ty Val) {
  Val += 1.0f // Does this get precise semantics?
}

int main() {
  precise float f = 1.0f;
  func(f);
}
```





Comment at: clang/docs/HLSLSupport.rst:197
+* Any use of the ``virtual`` keyword
+* Most features C++11 and later

beanz wrote:
> aaron.ballman wrote:
> > beanz wrote:
> > > aaron.ballman wrote:
> > > > Same question here as above with C on whether we expect to support 
> > > > those as extensions or diagnose them as invalid.
> > > I didn't really answer that above. I am inclined to do a mix of both. 
> > > Anything that we can support and lower I'd like to treat as extensions. 
> > > Some things we just can't.
> > > 
> > > We don't currently have any way to allocate memory dynamically, so 
> > > there's really no way to support new/delete. RTTI and exceptions are 
> > > another case where we just don't have the support we would need in the 
> > > driver specifications.
> > Okay, that seems reasonable enough. Should we issue "this is a Clang 
> > extension" diagnostics in the places where you're supporting something as 
> > an extension? Also, I presume you intend to add error diagnostics for all 
> > the cases that are not supported?
> I think issuing clang extension diagnostics will be super valuable to our 
> users. My expectation is that it will take a few years to transition all of 
> our users from DXC to Clang, and in the meantime if they are supporting both 
> compilers in their codebases diagnostics for extension use will be immensely 
> helpful.
> 
> For unsupported features, I think the immovable priority is that we can't 
> succeed compiling and generate invalid code (in our primary case that would 
> be code that can't be run under one of our driver specifications).
> 

[PATCH] D123278: [Clang] [Docs] Add HLSLSupport page

[Chris Bieneman via Phabricator via cfe-commits]

beanz updated this revision to Diff 421524.
beanz added a comment.

Updating based on feedback :)


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D123278/new/

https://reviews.llvm.org/D123278

Files:
  clang/docs/HLSLSupport.rst
  clang/docs/index.rst

Index: clang/docs/index.rst
===
--- clang/docs/index.rst
+++ clang/docs/index.rst
@@ -45,6 +45,7 @@
OpenCLSupport
OpenMPSupport
SYCLSupport
+   HLSLSupport
ThinLTO
APINotes
CommandGuide/index
Index: clang/docs/HLSLSupport.rst
===
--- /dev/null
+++ clang/docs/HLSLSupport.rst
@@ -0,0 +1,240 @@
+
+HLSL Support
+
+
+.. contents::
+   :local:
+
+Introduction
+
+
+HLSL Support is under active development in the Clang codebase. This document
+describes the high level goals of the project, the guiding principles, as well
+as some idiosyncrasies of the HLSL language and how we intend to support them in
+Clang.
+
+Project Goals
+=
+
+The long term goal of this project is to enable Clang to function as a
+replacement for the `DirectXShaderCompiler (DXC)
+`_ in all its supported
+use cases. Accomplishing that goal will require Clang to be able to process most
+existing HLSL programs with a high degree of source compatibility.
+
+Non-Goals
+-
+
+HLSL ASTs do not need to be compatible between DXC and Clang. We do not expect
+identical code generation or that features will resemble DXC's implementation or
+architecture. In fact, we explicitly expect to deviate from DXC's implementation
+in key ways.
+
+Guiding Principles
+==
+
+This document lacks details for architectural decisions that are not yet
+finalized. Our top priorities are quality, maintainability, and flexibility. In
+accordance with community standards we are expecting a high level of test
+coverage, and we will engineer our solutions with long term maintenance in mind.
+We are also working to limit modifications to the Clang C++ code paths and
+share as much functionality as possible.
+
+Architectural Direction
+===
+
+HLSL support in Clang is expressed as C++ minus unsupported C and C++ features.
+This is different from how other Clang languages are implemented. Most languages
+in Clang are additive on top of C.
+
+HLSL is not a formally or fully specified language, and while our goals require
+a high level of source compatibility, implementations can vary and we have some
+flexibility to be more or less permissive in some cases. For modern HLSL DXC is
+the reference implementation.
+
+The HLSL effort prioritizes following similar patterns for other languages,
+drivers, runtimes and targets. Specifically, We will maintain separation between
+HSLS-specific code and the rest of Clang as much as possible following patterns
+in use in Clang code today (i.e. ParseHLSL.cpp, SemaHLSL.cpp, CGHLSL*.cpp...).
+We will use inline checks on language options where the code is simple and
+isolated, and prefer HLSL-specific implementation files for any code of
+reasonable complexity.
+
+In places where the HLSL language is in conflict with C and C++, we will seek to
+make minimally invasive changes guarded under the HLSL language options. We will
+seek to make HLSL language support as minimal a maintenance burden as possible.
+
+DXC Driver
+--
+
+A DXC driver mode will provide command-line compatibility with DXC, supporting
+DXC's options and flags. The DXC driver is HLSL-specific and will create an
+HLSLToolchain which will provide the basis to support targeting both DirectX and
+Vulkan.
+
+Parser
+--
+
+Following the examples of other parser extensions HLSL will add a ParseHLSL.cpp
+file to contain the implementations of HLSL-specific extensions to the Clang
+parser. The HLSL grammar shares most of its structure with C and C++, so we will
+use the existing C/C++ parsing code paths.
+
+Sema
+
+
+HLSL's Sema implementation will also provide an ``ExternalSemaSource``. In DXC,
+an ``ExternalSemaSource`` is used to provide definitions for HLSL built-in data
+types and built-in templates. Clang is already designed to allow an attached
+``ExternalSemaSource`` to lazily complete data types, which is a **huge**
+performance win for HLSL.
+
+CodeGen
+---
+
+Like OpenCL, HLSL relies on capturing a lot of information into IR metadata.
+*hand wave* *hand wave* *hand wave* As a design principle here we want our IR to
+be idiomatic Clang IR as much as possible. We will use IR attributes wherever we
+can, and use metadata as sparingly as possible. One example of a difference from
+DXC already implemented in Clang is the use of target triples to communicate
+shader model versions and shader stages.
+
+Our HLSL CodeGen implementation should also have an eye toward generating IR

[PATCH] D123278: [Clang] [Docs] Add HLSLSupport page

[Jakub Kuderski via Phabricator via cfe-commits]

kuhar accepted this revision.
kuhar added a comment.
This revision is now accepted and ready to land.

LGTM




Comment at: clang/docs/HLSLSupport.rst:223
+* References
+* goto or labels
+* Variable Length Arrays

nit, for consistency with the other list items: make goto verbatim



Comment at: clang/docs/HLSLSupport.rst:225
+* Variable Length Arrays
+* _Complex and _Imaginary
+* C Threads or Atomics (or Obj-C blocks)

nit: also verbatim?



Comment at: clang/docs/HLSLSupport.rst:237
+* Anonymous or inline namespaces
+* ``new`` & ``delete`` operators in all of their forms (array, placement, etc)
+* Constructors & destructors

ubernit: & -> and, for consistency with the other list items


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D123278/new/

https://reviews.llvm.org/D123278

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D123278: [Clang] [Docs] Add HLSLSupport page

[Chris Bieneman via Phabricator via cfe-commits]

beanz marked 30 inline comments as done.
beanz added inline comments.



Comment at: clang/docs/HLSLSupport.rst:150-152
+HLSL has a ``precise`` qualifier that behaves unlike anything else in the C
+language. The support for this qualifier in DXC is buggy, so our bar for
+compatibility is low.

aaron.ballman wrote:
> beanz wrote:
> > aaron.ballman wrote:
> > > Is it worth supporting at all (I know you want source compatibility...)? 
> > > Type system changes are generally expensive and invasive, largely because 
> > > changing the type system in C++ is complicated. For example, does this 
> > > qualifier impact overload sets or template specializations? Does it get 
> > > name mangled? That sort of thing.
> > Unfortunately we do need to implement it to some degree. In DXC it is 
> > implemented as an attribute rather than a qualifier, so it shouldn't impact 
> > overloads, template specialization or mangling.
> > 
> > I call it a qualifier here because it is syntactically more like a 
> > qualifier, but I'm honestly not sure how we should implement it. In DXC, we 
> > emit IR metadata denoting the underlying value as "precise", then in an IR 
> > pass propagate disabling fast math.
> > Unfortunately we do need to implement it to some degree. In DXC it is 
> > implemented as an attribute rather than a qualifier, so it shouldn't impact 
> > overloads, template specialization or mangling.
> 
> Okay, I kind of figured you needed it.
> 
> > I call it a qualifier here because it is syntactically more like a 
> > qualifier, but I'm honestly not sure how we should implement it. In DXC, we 
> > emit IR metadata denoting the underlying value as "precise", then in an IR 
> > pass propagate disabling fast math.
> 
> This smells more like an attribute than a qualifier to me, but I'd like to 
> see if I understand first (please ignore if I get syntax wrong):
> ```
> // Initialization
> precise float f = 1.0 / 3.0 * sinf(3.14f); // value computation is precise
> // Assignment
> f = 1.0 / 3.0 * sinf(3.14f); // value computation is NOT precise (not a 
> declaration)?
> // RHS of expression
> float f2 = f * 2.0; // value computation is NOT precise (f2 is not marked 
> precise)?
> ```
> 
Yea, your syntax and behavior is correct with the added complication that 
precise upward propagates. The upward propagation is the part that is wonky and 
problematic.

```
float f = 1.0 * sinf(3.14f); // precise
precise float f2 = f / 2.0f; // precise
float f3 = f * f2; // not precise
```




Comment at: clang/docs/HLSLSupport.rst:197
+* Any use of the ``virtual`` keyword
+* Most features C++11 and later

aaron.ballman wrote:
> beanz wrote:
> > aaron.ballman wrote:
> > > Same question here as above with C on whether we expect to support those 
> > > as extensions or diagnose them as invalid.
> > I didn't really answer that above. I am inclined to do a mix of both. 
> > Anything that we can support and lower I'd like to treat as extensions. 
> > Some things we just can't.
> > 
> > We don't currently have any way to allocate memory dynamically, so there's 
> > really no way to support new/delete. RTTI and exceptions are another case 
> > where we just don't have the support we would need in the driver 
> > specifications.
> Okay, that seems reasonable enough. Should we issue "this is a Clang 
> extension" diagnostics in the places where you're supporting something as an 
> extension? Also, I presume you intend to add error diagnostics for all the 
> cases that are not supported?
I think issuing clang extension diagnostics will be super valuable to our 
users. My expectation is that it will take a few years to transition all of our 
users from DXC to Clang, and in the meantime if they are supporting both 
compilers in their codebases diagnostics for extension use will be immensely 
helpful.

For unsupported features, I think the immovable priority is that we can't 
succeed compiling and generate invalid code (in our primary case that would be 
code that can't be run under one of our driver specifications).

Having nice, targeted diagnostics for each unsupported case is the ideal, but 
there are cases (like with Microsoft attribute parsing on templates), where we 
fail the compile with diagnostics that are "good enough" or even just in parity 
to DXC which we may take as an opportunity for future improvement and not a 
requirement.

Does that make sense? I'm trying not to back myself into a corner of having 
perfect be the enemy of "better than what we have today".


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D123278/new/

https://reviews.llvm.org/D123278

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D123278: [Clang] [Docs] Add HLSLSupport page

[Aaron Ballman via Phabricator via cfe-commits]

aaron.ballman added inline comments.



Comment at: clang/docs/HLSLSupport.rst:150-152
+HLSL has a ``precise`` qualifier that behaves unlike anything else in the C
+language. The support for this qualifier in DXC is buggy, so our bar for
+compatibility is low.

beanz wrote:
> aaron.ballman wrote:
> > Is it worth supporting at all (I know you want source compatibility...)? 
> > Type system changes are generally expensive and invasive, largely because 
> > changing the type system in C++ is complicated. For example, does this 
> > qualifier impact overload sets or template specializations? Does it get 
> > name mangled? That sort of thing.
> Unfortunately we do need to implement it to some degree. In DXC it is 
> implemented as an attribute rather than a qualifier, so it shouldn't impact 
> overloads, template specialization or mangling.
> 
> I call it a qualifier here because it is syntactically more like a qualifier, 
> but I'm honestly not sure how we should implement it. In DXC, we emit IR 
> metadata denoting the underlying value as "precise", then in an IR pass 
> propagate disabling fast math.
> Unfortunately we do need to implement it to some degree. In DXC it is 
> implemented as an attribute rather than a qualifier, so it shouldn't impact 
> overloads, template specialization or mangling.

Okay, I kind of figured you needed it.

> I call it a qualifier here because it is syntactically more like a qualifier, 
> but I'm honestly not sure how we should implement it. In DXC, we emit IR 
> metadata denoting the underlying value as "precise", then in an IR pass 
> propagate disabling fast math.

This smells more like an attribute than a qualifier to me, but I'd like to see 
if I understand first (please ignore if I get syntax wrong):
```
// Initialization
precise float f = 1.0 / 3.0 * sinf(3.14f); // value computation is precise
// Assignment
f = 1.0 / 3.0 * sinf(3.14f); // value computation is NOT precise (not a 
declaration)?
// RHS of expression
float f2 = f * 2.0; // value computation is NOT precise (f2 is not marked 
precise)?
```




Comment at: clang/docs/HLSLSupport.rst:197
+* Any use of the ``virtual`` keyword
+* Most features C++11 and later

beanz wrote:
> aaron.ballman wrote:
> > Same question here as above with C on whether we expect to support those as 
> > extensions or diagnose them as invalid.
> I didn't really answer that above. I am inclined to do a mix of both. 
> Anything that we can support and lower I'd like to treat as extensions. Some 
> things we just can't.
> 
> We don't currently have any way to allocate memory dynamically, so there's 
> really no way to support new/delete. RTTI and exceptions are another case 
> where we just don't have the support we would need in the driver 
> specifications.
Okay, that seems reasonable enough. Should we issue "this is a Clang extension" 
diagnostics in the places where you're supporting something as an extension? 
Also, I presume you intend to add error diagnostics for all the cases that are 
not supported?


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D123278/new/

https://reviews.llvm.org/D123278

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D123278: [Clang] [Docs] Add HLSLSupport page

[Chris Bieneman via Phabricator via cfe-commits]

beanz updated this revision to Diff 421373.
beanz added a comment.

Updating with edits based on review feedback.


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D123278/new/

https://reviews.llvm.org/D123278

Files:
  clang/docs/HLSLSupport.rst
  clang/docs/index.rst

Index: clang/docs/index.rst
===
--- clang/docs/index.rst
+++ clang/docs/index.rst
@@ -45,6 +45,7 @@
OpenCLSupport
OpenMPSupport
SYCLSupport
+   HLSLSupport
ThinLTO
APINotes
CommandGuide/index
Index: clang/docs/HLSLSupport.rst
===
--- /dev/null
+++ clang/docs/HLSLSupport.rst
@@ -0,0 +1,240 @@
+
+HLSL Support
+
+
+.. contents::
+   :local:
+
+Introduction
+
+
+HLSL Support is under active development in the Clang codebase. This document
+describes the high level goals of the project, the guiding principles, as well
+as some idiosyncrasies of the HLSL language and how we intend to support them in
+Clang.
+
+Project Goals
+=
+
+The long term goal of this project is to enable Clang to function as a
+replacement for the `DirectXShaderCompiler (DXC)
+`_ in all its supported
+use cases. Accomplishing that goal will require Clang to be able to process most
+existing HLSL programs with a high degree of source compatibility.
+
+Non-Goals
+-
+
+HLSL ASTs do not need to be compatible between DXC and Clang. We do not expect
+identical code generation or that features will resemble DXC's implementation or
+architecture. In fact, we explicitly expect to deviate from DXC's implementation
+in key ways.
+
+Guiding Principles
+==
+
+This document lacks details for architectural decisions that are not yet
+finalized. Our top priorities are quality, maintainability, and flexibility. In
+accordance with community standards we are expecting a high level of test
+coverage, and we will engineer our solutions with long term maintenance in mind.
+We are also working to limit modifications to the Clang C++ code paths and
+share as much functionality as possible.
+
+Architectural Direction
+===
+
+HLSL support in Clang is expressed as C++ minus unsupported C and C++ features.
+This is different from how other Clang languages are implemented. Most languages
+in Clang are additive on top of C.
+
+HLSL is not a formally or fully specified language, and while our goals require
+a high level of source compatibility, implementations can vary and we have some
+flexibility to be more or less permissive in some cases. For modern HLSL DXC is
+the reference implementation.
+
+The HLSL effort prioritizes following similar patterns for other languages,
+drivers, runtimes and targets. Specifically, We will maintain separation between
+HSLS-specific code and the rest of Clang as much as possible following patterns
+in use in Clang code today (i.e. ParseHLSL.cpp, SemaHLSL.cpp, CGHLSL*.cpp...).
+We will use inline checks on language options where the code is simple and
+isolated, and prefer HLSL-specific implementation files for any code of
+reasonable complexity.
+
+In places where the HLSL language is in conflict with C and C++, we will seek to
+make minimally invasive changes guarded under the HLSL language options. We will
+seek to make HLSL language support as minimal a maintenance burden as possible.
+
+DXC Driver
+--
+
+A DXC driver mode will provide command-line compatibility with DXC, supporting
+DXC's options and flags. The DXC driver is HLSL-specific and will create an
+HLSLToolchain which will provide the basis to support targeting both DirectX and
+Vulkan.
+
+Parser
+--
+
+Following the examples of other parser extensions HLSL will add a ParseHLSL.cpp
+file to contain the implementations of HLSL-specific extensions to the Clang
+parser. The HLSL grammar shares most of its structure with C and C++, so we will
+use the existing C/C++ parsing code paths.
+
+Sema
+
+
+HLSL's Sema implementation will also provide an ``ExternalSemaSource``. In DXC,
+an ``ExternalSemaSource`` is used to provide definitions for HLSL built-in data
+types and built-in templates. Clang is already designed to allow an attached
+``ExternalSemaSource`` to lazily complete data types, which is a **huge**
+performance win for HLSL.
+
+CodeGen
+---
+
+Like OpenCL, HLSL relies on capturing a lot of information into IR metadata.
+*hand wave* *hand wave* *hand wave* As a design principle here we want our IR to
+be idiomatic Clang IR as much as possible. We will use IR attributes wherever we
+can, and use metadata as sparingly as possible. One example of a difference from
+DXC already implemented in Clang is the use of target triples to communicate
+shader model versions and shader stages.
+
+Our HLSL CodeGen implementation should also have an eye toward 

[PATCH] D123278: [Clang] [Docs] Add HLSLSupport page

[Chris Bieneman via Phabricator via cfe-commits]

beanz added a comment.

I'll do an edit pass tonight and update. I've also gone through and replied to 
some of the questions and comments inline.

Thank you!




Comment at: clang/docs/HLSLSupport.rst:22-23
+`_. in all its supported
+use cases. Accomplishing that goal will require a high level of source
+compatibility.
+

kuhar wrote:
> What do you mean by source compatibility in this case? In terms of the input 
> source language (HLSL), or the source code of both implementations?
> 
> Perhaps we could make it more direct? E.g., 'This requires us to add the HLSL 
> language support to Clang.'
I see the confusion there. I mean in terms of the input source, not the 
implementation. We do vend the compiler as a library too with a COM API to 
invoke the compiler on in-memory sources (which is slightly terrifying to me).

I don't yet know how much flexibility we have to radically change the API, but 
that shouldn't have any impact on the implementations in clang because we'll do 
it in a wrapper library.



Comment at: clang/docs/HLSLSupport.rst:50-52
+HLSL is not a formally or fully specified language, and while our goals require
+a high level of source compatibility, implementations can vary and we have some
+flexibility to be more or less permissive in some cases.

kuhar wrote:
> Is DXC the reference implementation?
Yes, with the caveat that it doesn't actually support older language versions 
(for that we have FXC).



Comment at: clang/docs/HLSLSupport.rst:73
+Following the examples of other parser extensions HLSL will add a ParseHLSL.cpp
+file to contain the implementations of HLSL-specific extensions to the clang
+parser.

aaron.ballman wrote:
> Probably also worth pointing out that most HLSL parsing is expected to be the 
> usual C and C++ code paths, or is that not your expectation?
Yea, that is the expectation.



Comment at: clang/docs/HLSLSupport.rst:90-91
+metadata. *hand wave* *hand wave* *hand wave* As a design principle here we 
want
+our IR to be idiomatic Clang IR as much as possible. We will use IR attributes
+wherever we can, and use metadata as sparingly as possible. One example of a
+difference from DXC already implemented in Clang is the use of target triples 
to

kuhar wrote:
> Are all attributes guaranteed to be preserved? I thought some might get 
> dropped by opt.
Some attributes do get dropped in optimization. We are going to need to 
evaluate a bit case by case. DXC (and DXIL) puts a lot of information in 
metadata, which is a pain to work with through compiler layers. We actually 
have a set of helpers to read data in and out of the IR metadata... I'm trying 
to avoid needing any of that.



Comment at: clang/docs/HLSLSupport.rst:121-122
+operators (unary ``*``, and ``->``), as well as the address of operator (unary
+&). While HLSL disallows pointers and references in the syntax, HLSL does use
+reference types in the AST.
+

aaron.ballman wrote:
> Presumably it also uses pointer types in the AST for things like array and 
> function decay?
That is my plan for in Clang. In DXC they prevent array->pointer decay in the 
AST which IMO causes more problems than it solves, especially since the IR 
decays to pointers anyways.



Comment at: clang/docs/HLSLSupport.rst:143-145
+In HLSL 2018 and earlier, HLSL supported logical operators (and the ternary
+operator) on vector types. This behavior required that operators not short
+circuit.

aaron.ballman wrote:
> It's not clear whether the behavior will vary for all types or just vector 
> types. Also, does this apply in preprocessor conditionals the same as runtime 
> expressions?
It only applies in runtime expressions, and does apply to all types not just 
vectors. Vectors are the motivation for it because short circuiting would be 
unwieldy for vector types.

With HLSL 2021, operators follow C short circuit rules and are not allowed to 
operate on vector types, instead there are builtin functions to handle the 
vector cases.



Comment at: clang/docs/HLSLSupport.rst:150-152
+HLSL has a ``precise`` qualifier that behaves unlike anything else in the C
+language. The support for this qualifier in DXC is buggy, so our bar for
+compatibility is low.

aaron.ballman wrote:
> Is it worth supporting at all (I know you want source compatibility...)? Type 
> system changes are generally expensive and invasive, largely because changing 
> the type system in C++ is complicated. For example, does this qualifier 
> impact overload sets or template specializations? Does it get name mangled? 
> That sort of thing.
Unfortunately we do need to implement it to some degree. In DXC it is 
implemented as an attribute rather than a qualifier, so it shouldn't impact 
overloads, template 

[PATCH] D123278: [Clang] [Docs] Add HLSLSupport page

[Jakub Kuderski via Phabricator via cfe-commits]

kuhar added inline comments.



Comment at: clang/docs/HLSLSupport.rst:190
+* RTTI
+* Exceptions
+* Multiple inheritance

How about goto and labels? Irreducible control flow? Are infinite loops valid?


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D123278/new/

https://reviews.llvm.org/D123278

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D123278: [Clang] [Docs] Add HLSLSupport page

[Jakub Kuderski via Phabricator via cfe-commits]

kuhar added a comment.

Looks good to me overall, I just left some local comments. Please take my 
writing suggestions with a pinch of salt, English is my second language.




Comment at: clang/docs/HLSLSupport.rst:13
+describes the high level goals of the project, the guiding principals, as well
+as some of the idiosyncrasies of the HLSL language and how we intend to support
+them in Clang.

ubernit: some of the idiosyncrasies -> some idiosyncrasies



Comment at: clang/docs/HLSLSupport.rst:22-23
+`_. in all its supported
+use cases. Accomplishing that goal will require a high level of source
+compatibility.
+

What do you mean by source compatibility in this case? In terms of the input 
source language (HLSL), or the source code of both implementations?

Perhaps we could make it more direct? E.g., 'This requires us to add the HLSL 
language support to Clang.'



Comment at: clang/docs/HLSLSupport.rst:28-31
+HLSL ASTs do not need to be compatible between DXC and Clang. We do not expect
+identical code generation or that features will resemble DXC's implementation 
or
+architecture. In fact, we explicitly expect to deviate from DXC's 
implementation
+in key ways.

It's great you made this so explicit!



Comment at: clang/docs/HLSLSupport.rst:36
+
+This document lacks precise details for architectural decisions that are not 
yet
+finalized. Our top priorities are quality, maintainability, and flexibility. In

ubernit: how about just 'details'?



Comment at: clang/docs/HLSLSupport.rst:50-52
+HLSL is not a formally or fully specified language, and while our goals require
+a high level of source compatibility, implementations can vary and we have some
+flexibility to be more or less permissive in some cases.

Is DXC the reference implementation?



Comment at: clang/docs/HLSLSupport.rst:55-56
+The HLSL effort prioritizes following similar patterns for other languages,
+drivers, runtimes and targets. Specifically, HLSL will create separate
+implementation files to contain the HLSL-specific behavior wherever it makes
+sense (i.e. ParseHLSL.cpp, SemaHLSL.cpp, CGHLSL*.cpp...). We will use inline

This is a bit awkward, as if the language HSLS created files on disk on 
something :P. 

Maybe something like: We will maintain separation between HSLS-specific code 
and the rest of Clang as much as possible (e.g., ParseHSLS.cpp, ...)



Comment at: clang/docs/HLSLSupport.rst:90-91
+metadata. *hand wave* *hand wave* *hand wave* As a design principle here we 
want
+our IR to be idiomatic Clang IR as much as possible. We will use IR attributes
+wherever we can, and use metadata as sparingly as possible. One example of a
+difference from DXC already implemented in Clang is the use of target triples 
to

Are all attributes guaranteed to be preserved? I thought some might get dropped 
by opt.



Comment at: clang/docs/HLSLSupport.rst:128
+HLSL does support member functions, and (in HLSL 2021) limited operator
+overloading. With member function support HLSL also has a ``this`` keyword. The
+``this`` keyword is an example of one of the places where HLSL relies on

nit: With member function support*,* HLSL also



Comment at: clang/docs/HLSLSupport.rst:135
+
+This is a simple one, but it deviates from C so is worth mentioning. HLSL
+bitshifts are defined to mask the shift count by the size of the type. In DXC,

nit: so *it* is worth?



Comment at: clang/docs/HLSLSupport.rst:137
+bitshifts are defined to mask the shift count by the size of the type. In DXC,
+the semantics of LLVM IR were altered to accomodate this, in Clang we intend to
+generate the mask explicitly in the IR.

accommodate



Comment at: clang/docs/HLSLSupport.rst:187
+
+HLSL does not support the following C++ features:
+

These are C++ language features. I assume that all library features are also 
out of the window?


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D123278/new/

https://reviews.llvm.org/D123278

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D123278: [Clang] [Docs] Add HLSLSupport page

[Thorsten via Phabricator via cfe-commits]

tschuett added a comment.

Thanks. I let Aaron go over the details.


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D123278/new/

https://reviews.llvm.org/D123278

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D123278: [Clang] [Docs] Add HLSLSupport page

[Aaron Ballman via Phabricator via cfe-commits]

aaron.ballman added a comment.

Thanks for getting a start on this documentation, I appreciate it!




Comment at: clang/docs/HLSLSupport.rst:11
+
+HLSL Support is a new initiative underway in the Clang codebase. This document
+describes the high level goals of the project, the guiding principals, as well

I can't wait to read "is a new initiative underway" four years from now. :-D 
(We may want to prevent that by making it a less temporal statement.)



Comment at: clang/docs/HLSLSupport.rst:12
+HLSL Support is a new initiative underway in the Clang codebase. This document
+describes the high level goals of the project, the guiding principals, as well
+as some of the idiosyncrasies of the HLSL language and how we intend to support





Comment at: clang/docs/HLSLSupport.rst:19-23
+The long term goal of this project is to enable clang to function as a
+replacement for the `DirectXShaderCompiler (DXC)
+`_. in all its supported
+use cases. Accomplishing that goal will require a high level of source
+compatibility.





Comment at: clang/docs/HLSLSupport.rst:33
+
+Guiding Principals
+==





Comment at: clang/docs/HLSLSupport.rst:46-48
+HLSL support in clang is expressed as C++ minus unsupported C and C++ features.
+This is different from how other clang languages are implemented. Most 
languages
+in Clang are additive on top of C.





Comment at: clang/docs/HLSLSupport.rst:59
+checks on language options where the code is simple and isolated, and prefer
+HLSL-specific implementation files for any code of reasonable complexity.
+

I think it would be good to also mention what happens when HLSL is in conflict 
with either C or C++, at a high level.



Comment at: clang/docs/HLSLSupport.rst:73
+Following the examples of other parser extensions HLSL will add a ParseHLSL.cpp
+file to contain the implementations of HLSL-specific extensions to the clang
+parser.

Probably also worth pointing out that most HLSL parsing is expected to be the 
usual C and C++ code paths, or is that not your expectation?



Comment at: clang/docs/HLSLSupport.rst:121-122
+operators (unary ``*``, and ``->``), as well as the address of operator (unary
+&). While HLSL disallows pointers and references in the syntax, HLSL does use
+reference types in the AST.
+

Presumably it also uses pointer types in the AST for things like array and 
function decay?



Comment at: clang/docs/HLSLSupport.rst:143-145
+In HLSL 2018 and earlier, HLSL supported logical operators (and the ternary
+operator) on vector types. This behavior required that operators not short
+circuit.

It's not clear whether the behavior will vary for all types or just vector 
types. Also, does this apply in preprocessor conditionals the same as runtime 
expressions?



Comment at: clang/docs/HLSLSupport.rst:150-152
+HLSL has a ``precise`` qualifier that behaves unlike anything else in the C
+language. The support for this qualifier in DXC is buggy, so our bar for
+compatibility is low.

Is it worth supporting at all (I know you want source compatibility...)? Type 
system changes are generally expensive and invasive, largely because changing 
the type system in C++ is complicated. For example, does this qualifier impact 
overload sets or template specializations? Does it get name mangled? That sort 
of thing.



Comment at: clang/docs/HLSLSupport.rst:166
+HLSL uses templates to define builtin types and methods, but disallowed
+user-defined templates until HLSL 2021. HLSL also allows omiting empty template
+parameter lists when all template parameters are defaulted. This is an 
ambiguous





Comment at: clang/docs/HLSLSupport.rst:168
+parameter lists when all template parameters are defaulted. This is an 
ambiguous
+syntax in C++, however clang detects the case and issues a diagnostic, so
+supporting it is minimally invasive.





Comment at: clang/docs/HLSLSupport.rst:175
+HLSL uses the OpenCL vector extensions, and also provides C++-style 
constructors
+for vectors that are not supported by clang.
+





Comment at: clang/docs/HLSLSupport.rst:185
+* ``union`` types `(in progress for HLSL 202x) 
`_
+* Most features C11 and later
+

From C99:
VLAs?
_Complex/_Imaginary?

From C11:
Threads/Atomics?
Language features like `_Generic` (or `[[]]` attributes in C2x)?

Also, it's not clear whether you expect these unsupported features to be 
diagnosed or supported as extensions in HLSL, etc.



Comment 

[PATCH] D123278: [Clang] [Docs] Add HLSLSupport page

[Chris Bieneman via Phabricator via cfe-commits]

beanz created this revision.
beanz added reviewers: tschuett, aaron.ballman, jaebaek, antiagainst, kuhar.
Herald added a subscriber: arphaman.
Herald added a project: All.
beanz requested review of this revision.
Herald added a project: clang.
Herald added a subscriber: cfe-commits.

This document is a first-stab at addressing some of the questions about
HLSL support in Clang.


Repository:
  rG LLVM Github Monorepo

https://reviews.llvm.org/D123278

Files:
  clang/docs/HLSLSupport.rst
  clang/docs/index.rst

Index: clang/docs/index.rst
===
--- clang/docs/index.rst
+++ clang/docs/index.rst
@@ -45,6 +45,7 @@
OpenCLSupport
OpenMPSupport
SYCLSupport
+   HLSLSupport
ThinLTO
APINotes
CommandGuide/index
Index: clang/docs/HLSLSupport.rst
===
--- /dev/null
+++ clang/docs/HLSLSupport.rst
@@ -0,0 +1,197 @@
+
+HLSL Support
+
+
+.. contents::
+   :local:
+
+Introduction
+
+
+HLSL Support is a new initiative underway in the Clang codebase. This document
+describes the high level goals of the project, the guiding principals, as well
+as some of the idiosyncrasies of the HLSL language and how we intend to support
+them in Clang.
+
+Project Goals
+=
+
+The long term goal of this project is to enable clang to function as a
+replacement for the `DirectXShaderCompiler (DXC)
+`_. in all its supported
+use cases. Accomplishing that goal will require a high level of source
+compatibility.
+
+Non-Goals
+-
+
+HLSL ASTs do not need to be compatible between DXC and Clang. We do not expect
+identical code generation or that features will resemble DXC's implementation or
+architecture. In fact, we explicitly expect to deviate from DXC's implementation
+in key ways.
+
+Guiding Principals
+==
+
+This document lacks precise details for architectural decisions that are not yet
+finalized. Our top priorities are quality, maintainability, and flexibility. In
+accordance with community standards we are expecting a high level of test
+coverage, and we will engineer our solutions with long term maintenance in mind.
+We are also working to limit modifications to the Clang C++ code paths and
+share as much functionality as possible.
+
+Architectural Direction
+===
+
+HLSL support in clang is expressed as C++ minus unsupported C and C++ features.
+This is different from how other clang languages are implemented. Most languages
+in Clang are additive on top of C.
+
+HLSL is not a formally or fully specified language, and while our goals require
+a high level of source compatibility, implementations can vary and we have some
+flexibility to be more or less permissive in some cases.
+
+The HLSL effort prioritizes following similar patterns for other languages,
+drivers, runtimes and targets. Specifically, HLSL will create separate
+implementation files to contain the HLSL-specific behavior wherever it makes
+sense (i.e. ParseHLSL.cpp, SemaHLSL.cpp, CGHLSL*.cpp...). We will use inline
+checks on language options where the code is simple and isolated, and prefer
+HLSL-specific implementation files for any code of reasonable complexity.
+
+DXC Driver
+--
+
+A DXC driver mode will provide command-line compatibility with DXC, supporting
+DXC's options and flags. The DXC driver is HLSL-specific and will create an
+HLSLToolchain which will provide the basis to support targeting both DirectX and
+Vulkan.
+
+Parser
+--
+
+Following the examples of other parser extensions HLSL will add a ParseHLSL.cpp
+file to contain the implementations of HLSL-specific extensions to the clang
+parser.
+
+Sema
+
+
+HLSL's Sema implementation will also provide an ``ExternalSemaSource``. In DXC,
+an ``ExternalSemaSource`` is used to provide definitions for HLSL built-in data
+types and built-in templates. Clang is already designed to allow an attached
+``ExternalSemaSource`` to lazily complete data types, which is a **huge**
+performance win for HLSL.
+
+CodeGen
+---
+
+Similar to OpenCL, HLSL relies on capturing a lot of information into IR
+metadata. *hand wave* *hand wave* *hand wave* As a design principle here we want
+our IR to be idiomatic Clang IR as much as possible. We will use IR attributes
+wherever we can, and use metadata as sparingly as possible. One example of a
+difference from DXC already implemented in Clang is the use of target triples to
+communicate shader model versions and shader stages.
+
+Our HLSL CodeGen implementation should also have an eye toward generating IR
+that will map directly to targets other than DXIL. While IR itself is generally
+not re-targetable, we want to share the Clang CodeGen implementation for HLSL
+with other GPU graphics targets like SPIR-V and possibly other GPU and even CPU
+targets.
+
+HLSL Language