From 324603f2faf9c1d6ee75bc8e95859ddfe52f8160 Mon Sep 17 00:00:00 2001 From: Helena Kotas Date: Wed, 24 Apr 2024 13:56:45 -0700 Subject: [PATCH] [INF-0001] Add environment parameter for per-stage availability annotations (#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 --- .../INF-0001-availability-diagnostics.md | 64 +++++++++++++------ 1 file changed, 44 insertions(+), 20 deletions(-) diff --git a/proposals/infra/INF-0001-availability-diagnostics.md b/proposals/infra/INF-0001-availability-diagnostics.md index 1f10bb45..72c278cb 100644 --- a/proposals/infra/INF-0001-availability-diagnostics.md +++ b/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 ```