[INF-0001] Add environment parameter for per-stage availability annot…

…ations (#204)

Add environment parameter to the Clang availability attribute and use it for per-stage availability annotations. Also rename intrinsic -> function to keep the naming consistent.

Fixes #189

proposals/infra/INF-0001-availability-diagnostics.md

@@ -52,16 +52,6 @@ __attribute__((availability(shadermodel, introduced = 6.0)))
 __attribute__((availability(vulkan, introduced = 1.0)))
 __attribute__((clang_builtin_alias(__builtin_hlsl_wave_active_count_bits)))
 uint WaveActiveCountBits(bool Bit);
-
-// This function is available starting in SM 2.0 for pixel shaders, but SM 6.6
-// for compute, mesh and amplification shaders.
-__attribute__((availability(shadermodel_pixel, introduced = 2.0)))
-__attribute__((availability(shadermodel_compute, introduced = 6.6)))
-__attribute__((availability(shadermodel_mesh, introduced = 6.6)))
-__attribute__((availability(shadermodel_amplification, introduced = 6.6)))
-__attribute__((availability(vulkan, introduced = 1.0)))
-__attribute__((clang_builtin_alias(__builtin_hlsl_wave_active_count_bits)))
-float ddx(float val);
 ```
 
 > Note: the actual header uses macros to condense the attribute descriptions.
@@ -72,6 +62,40 @@ model 6.0+. This AST annotation allows clangd to communicate to users the
 availability information to language server protocol clients. This can drive
 more informed auto-complete, refactoring, and in-editor diagnostics.
 
+The Clang availability attribute works well when a function's availability
+depends only on the shader model version. However, the availability of some HLSL
+functions depends not only on the shader model version but also on the target
+shader stage. For example the derivative functions `ddx` and `ddy` were
+introduced in Shader Model 2.0 for use only in pixel shaders. In Shader Model
+6.6 their support was extended to compute, mesh and amplification shaders, and
+they are not available in any other shader stage.
+
+In order to encode this information we propose adding a new `environment`
+parameter to the Clang availability attribute. The allowed values would be
+identical to the environment component of the `llvm::Triple`. If the
+`environment` parameters is present, the declared availability attribute would
+apply only for targets with the same environment.
+
+Using the new `environment` parameter, the per-stage availability annotation for
+the derivative function `ddx` would look like this:
+
+```
+__attribute__((availability(shadermodel, introduced = 2.0, environment = pixel)))
+__attribute__((availability(shadermodel, introduced = 6.6, environment = compute)))
+__attribute__((availability(shadermodel, introduced = 6.6, environment = mesh)))
+__attribute__((availability(shadermodel, introduced = 6.6, environment = amplification)))
+__attribute__((availability(vulkan, introduced = 1.0)))
+__attribute__((clang_builtin_alias(__builtin_hlsl_ddx)))
+float ddx(float val);
+```
+
+If the `environment` parameter is not present, it means the function is available
+for all shader stages starting with the specified shader model version. If the
+parameter is present, then for non-library shaders it will be checked against the
+environment component of the target triple. For library shaders the
+`environment` parameter will be checked against the `[shader("...")]` attribute
+on the shader entry function.
+
 ### Diagnostic Modes
 
 This proposal introduces three new modes for diagnosing API availability:
@@ -270,26 +294,26 @@ may produce warnings or errors with Clang.
 
 ### Diagnostic text
 
-The diagnostic message should reflect whether the intrisic is not available
-just for the particular target shader stage or the whole shader model version.
-In other words, it should be relevant to the entry point type. 
+The diagnostic message should reflect whether the function is not available for
+the shader model version or just for the specific shader stage. In other words,
+it should be relevant to the entry point type. 
 
-If intrinsic `a` is available in a shader model higher than the target shader
+If function `a` is available in a shader model higher than the target shader
 model regardless of target shader stage the diagnostic message should be:
 ```
-'a' is available beginning with Shader Model x.y
+'a' is only available on Shader Model x.y or newer
 ```
 
-If intrinsic `a` is not available in shader stage `S` regardless of shader model
+If function `a` is not available in shader stage `S` regardless of shader model
 version the diagnostic message should be:
 ```
-'a' is not available in S shaders
+'a' is not available in S shader environment on Shader Model x.y
 ```
 
-If intrinsic `a` is available in shader stage `S` in shader model higher than
-the target shader model the diagnostic message should be:
+If function `a` is available in shader stage `S` in shader model higher than the
+target shader model the diagnostic message should be:
 ```
-'a' is available in S shaders beginning with Shader Model x.y
+'a' is only available in S shader environment on Shader Model x.y or newer
 ```
 
 <!-- {% endraw %} -->