[core] Validate shader stages after applying pipeline overrides.

The WebGPU specification requires pipeline creation to validate
properties of shader stages, like workgroup sizes, that may depend on
the values of pipeline-overridable constants. Previously, wgpu-core
validated stages using an `Interface` built from the module before
overrides were applied, with results contrary to spec. Override
processing was then carried out by `wgpu_hal`, after all validation
had supposedly been taken care of.

This commit has `create_shader_module` save the validated Naga module
instead of creating a `wgpu_hal` shader module. At pipeline creation
time, `StageCompiler::compile` now applies the stage's override values
with `process_overrides`, validates the stage using an `Interface`
built from the result, and, if that validation succeeds, returns a
`CompiledStage` holding the `wgpu_hal` `ShaderModule` created from it.
Dropping the `CompiledStage` destroys that module once the pipeline
has been created.

Since the override values have already been applied, we pass
`wgpu_hal` empty sets of constants for these modules.

Since the `naga::back::pipeline_constants` module is now used by
`wgpu_core` rather than `wgpu_hal` backends, it can't be conditionally
available based on Naga's backend features. Include it
unconditionally.

This change removes `Interface::finalize_entry_point_name`, since we
no longer build an `Interface` at shader module creation. Instead, we
choose entry points from the `naga::Module` directly.

Add new tests: `tests/tests/wgpu-validation/api/overrides.rs`

Fixes #9774.
This commit is contained in:
Jim Blandy authored and mergify[bot] committed 2026-10-26 23:42:33 +00:00
1 parent e136c379cb
commit ad5a70aea1
8 files changed
+298 -110

No files matched your search

+1
View File
@@ -250,6 +250,7 @@ By @sagudev in [#10307](https://github.com/gfx-rs/wgpu/pull/10307).
- Relaxed requirement that the pipeline scalar type for a color output be at least as wide as the shader output type. Now, only the scalar kind must match. By @andyleiserson in [#9999](https://github.com/gfx-rs/wgpu/pull/9999).
- Disallow array types in `var<immediate>`. By @beicause in [#10081](https://github.com/gfx-rs/wgpu/pull/10081).
- Mesh shader draws in a multiview render pass now require the highest view in the multiview mask to be less than `Limits::max_mesh_multiview_view_count`. Previously one view past the limit was accepted. By @apollo-2006 in [#10496](https://github.com/gfx-rs/wgpu/pull/10496).
- `wgpu_core` now validates pipeline stage interfaces after pipeline constant values have been applied, per spec. For example, workgroup sizes set by overrides are now checked against device limits. By @jimblandy in [#10430](https://github.com/gfx-rs/wgpu/pull/10430).
#### Naga
-1
View File
@@ -24,7 +24,6 @@ pub mod spv;
#[cfg(wgsl_out)]
pub mod wgsl;
#[cfg(any(hlsl_out, msl_out, spv_out, glsl_out))]
pub mod pipeline_constants;
#[cfg(any(hlsl_out, glsl_out))]
+1
View File
@@ -11,6 +11,7 @@ mod external_texture;
mod immediates;
mod instance;
mod mesh_shader;
mod overrides;
mod ray_tracing_pipeline;
mod render_bundle;
mod render_pipeline;
@@ -0,0 +1,115 @@
//! Validation tests for pipeline-overridable constants.
use wgpu_test::{fail, valid};
fn compute_pipeline(
device: &wgpu::Device,
module: &wgpu::ShaderModule,
constants: &[(&str, f64)],
) -> wgpu::ComputePipeline {
device.create_compute_pipeline(&wgpu::ComputePipelineDescriptor {
label: None,
layout: None,
module,
entry_point: None,
compilation_options: wgpu::PipelineCompilationOptions {
constants,
..Default::default()
},
cache: None,
})
}
/// Workgroup size limits must be checked after override values are applied.
#[test]
fn workgroup_size_from_override() {
let (device, _queue) = wgpu::Device::noop(&Default::default());
let module = device.create_shader_module(wgpu::ShaderModuleDescriptor {
label: None,
source: wgpu::ShaderSource::Wgsl(
"
override size: u32 = 1;
@compute @workgroup_size(size) fn main() {}
"
.into(),
),
});
valid(&device, || compute_pipeline(&device, &module, &[]));
valid(&device, || {
compute_pipeline(&device, &module, &[("size", 64.0)])
});
fail(
&device,
|| compute_pipeline(&device, &module, &[("size", 1024.0)]),
Some("must be less or equal to the per-dimension limit"),
);
}
#[test]
fn unknown_override() {
let (device, _queue) = wgpu::Device::noop(&Default::default());
let module = device.create_shader_module(wgpu::ShaderModuleDescriptor {
label: None,
source: wgpu::ShaderSource::Wgsl("@compute @workgroup_size(1) fn main() {}".into()),
});
fail(
&device,
|| compute_pipeline(&device, &module, &[("nonexistent", 1.0)]),
Some("pipeline constant error"),
);
}
#[test]
fn missing_override_value_in_render_pipeline() {
let (device, _queue) = wgpu::Device::noop(&Default::default());
let module = device.create_shader_module(wgpu::ShaderModuleDescriptor {
label: None,
source: wgpu::ShaderSource::Wgsl(
"
override depth: f32;
@vertex fn vs() -> @builtin(position) vec4f { return vec4f(0.0, 0.0, depth, 1.0); }
@fragment fn fs() -> @location(0) vec4f { return vec4f(1.0); }
"
.into(),
),
});
let render_pipeline = |constants: &[(&str, f64)]| {
device.create_render_pipeline(&wgpu::RenderPipelineDescriptor {
label: None,
layout: None,
vertex: wgpu::VertexState {
module: &module,
entry_point: None,
compilation_options: wgpu::PipelineCompilationOptions {
constants,
..Default::default()
},
buffers: &[],
},
primitive: Default::default(),
depth_stencil: None,
multisample: Default::default(),
fragment: Some(wgpu::FragmentState {
module: &module,
entry_point: None,
compilation_options: Default::default(),
targets: &[Some(wgpu::TextureFormat::Rgba8Unorm.into())],
}),
multiview_mask: None,
cache: None,
})
};
valid(&device, || render_pipeline(&[("depth", 0.5)]));
fail(
&device,
|| render_pipeline(&[]),
Some("pipeline constant error"),
);
}
+14 -27
View File
@@ -2692,33 +2692,18 @@ impl Device {
})
})?;
let interface = validation::Interface::new(&module, &info, self.limits.clone());
let hal_shader = hal::ShaderInput::Naga(hal::NagaShader {
module,
info,
debug_source,
});
let hal_desc = hal::ShaderModuleDescriptor {
label: desc.label.to_hal(self.instance_flags),
runtime_checks: desc.runtime_checks,
};
let raw = match unsafe { self.raw().create_shader_module(&hal_desc, hal_shader) } {
Ok(raw) => raw,
Err(error) => {
return Err(match error {
hal::ShaderError::Device(error) => {
pipeline::CreateShaderModuleError::Device(self.handle_hal_error(error))
}
hal::ShaderError::Compilation(ref msg) => {
log::error!("Shader error: {msg}");
pipeline::CreateShaderModuleError::Generation
}
})
}
};
// Defer creating the `wgpu_hal` shader module until pipeline creation,
// when we can apply the pipeline's override values and validate the
// result.
let module = pipeline::ShaderModule {
state: ResourceState::Valid(pipeline::ShaderModuleState::NagaModule { raw, interface }),
state: ResourceState::Valid(pipeline::ShaderModuleState::NagaModule {
shader: hal::NagaShader {
module,
info,
debug_source,
},
runtime_checks: desc.runtime_checks,
}),
device: self.clone(),
label: desc.label.to_string(),
compilation_info: wgt::CompilationInfo::default(),
@@ -4600,12 +4585,13 @@ impl Device {
let raw = unsafe { self.raw().create_compute_pipeline(&pipeline_desc) }
.map_err(|error| self.handle_hal_pipeline_error(error))?;
drop(compute_stage);
let pipeline = pipeline::ComputePipeline {
state: ResourceState::Valid(pipeline::ComputePipelineState {
raw: ManuallyDrop::new(raw),
layout: pipeline_layout.clone(),
_shader_module: desc.stage.module.clone(),
_shader_module: desc.stage.module,
}),
device: self.clone(),
late_sized_buffer_groups,
@@ -5300,6 +5286,7 @@ impl Device {
unsafe { self.raw().create_render_pipeline(&pipeline_desc) }
.map_err(|err| self.handle_hal_pipeline_error(err))?
};
drop((vertex_stage, task_stage, mesh_stage, fragment_stage));
let pass_context = RenderPassContext {
attachments: AttachmentData {
+134 -35
View File
@@ -1,16 +1,23 @@
/*! The [`StageCompiler`] type, for validating programmable stages. */
/*! The [`StageCompiler`] type, for validating and compiling programmable stages. */
use alloc::{string::String, sync::Arc};
use alloc::{
borrow::Cow,
boxed::Box,
string::{String, ToString as _},
sync::Arc,
};
use core::mem::ManuallyDrop;
use crate::{
binding_model::PipelineLayout,
device::Device,
hal_label,
pipeline::{self, CreatePipelineError, ShaderModuleState},
resource::ParentDevice as _,
validation,
};
/// State for validating a pipeline's programmable stages.
/// State for validating and compiling a pipeline's programmable stages.
///
/// Lifecycle:
///
@@ -18,15 +25,19 @@ use crate::{
///
/// - For each programmable stage, in processing order:
///
/// - Call [`StageCompiler::compile`] to validate the stage. On success,
/// this updates the IO tracking to reflect the stage's outputs and
/// returns a [`CompiledStage`] referring to the hal module from the
/// descriptor.
/// - Call [`StageCompiler::compile`] to validate the stage and compile a
/// hal module for it. On success, this updates the IO tracking to
/// reflect the stage's outputs and returns a [`CompiledStage`] owning
/// the hal module. (For passthrough shaders, this just borrows a
/// reference to the provided hal module.)
///
/// - Construct your `wgpu_hal` pipeline, populating the descriptor with
/// [`wgpu_hal::ProgrammableStage`]s obtained by calling [`to_hal`] on each
/// `CompiledStage`.
///
/// - Drop the `CompiledStage` values, to free any hal shader modules we
/// generated just for this pipeline.
///
/// [`to_hal`]: CompiledStage::to_hal
pub(super) struct StageCompiler<'d> {
device: &'d Arc<Device>,
@@ -37,7 +48,7 @@ pub(super) struct StageCompiler<'d> {
/// Resource usage accumulated across all of the pipeline's stages.
pub resources: validation::PipelineResources,
/// The outputs of the last stage passed to `compile`.
/// The outputs of the most recently compiled stage.
pub io: validation::StageIo,
/// Stages checked against their Naga module's interface.
@@ -46,19 +57,45 @@ pub(super) struct StageCompiler<'d> {
/// A validated pipeline stage, ready to be passed to `wgpu_hal`.
///
/// This borrows some stage's hal module while we create a pipeline
/// that uses it. Call [`to_hal`] to borrow a
/// [`wgpu_hal::ProgrammableStage`] from this that you can use in the
/// hal pipeline descriptor.
/// For non-passthrough modules, this owns some stage's hal module while we
/// create a pipeline that uses it. Call [`to_hal`] to borrow a
/// [`wgpu_hal::ProgrammableStage`] from this that you can use in the hal
/// pipeline descriptor.
///
/// [`to_hal`]: Self::to_hal
pub(super) struct CompiledStage<'a> {
module: &'a dyn hal::DynShaderModule,
module: StageModule<'a>,
pub entry_point: String,
constants: &'a naga::back::PipelineConstants,
constants: Cow<'a, naga::back::PipelineConstants>,
zero_initialize_workgroup_memory: bool,
}
/// A `wgpu_hal` shader module, either owned or borrowed.
///
/// For ordinary shader stages, this owns the hal module we generated especially
/// for that stage. For passthrough modules, this borrows a reference to the
/// provided hal module.
enum StageModule<'a> {
Generated(GeneratedModule<'a>),
Passthrough(&'a dyn hal::DynShaderModule),
}
/// A `wgpu_hal` shader module generated at pipeline creation time.
///
/// Dropping this value takes care of destroying the hal module.
struct GeneratedModule<'a> {
device: &'a Device,
raw: ManuallyDrop<Box<dyn hal::DynShaderModule>>,
}
impl Drop for GeneratedModule<'_> {
fn drop(&mut self) {
// SAFETY: We never use `self.raw` again.
let raw = unsafe { ManuallyDrop::take(&mut self.raw) };
unsafe { self.device.raw().destroy_shader_module(raw) };
}
}
impl<'d> StageCompiler<'d> {
/// Begin validating a pipeline's stages.
///
@@ -83,21 +120,25 @@ impl<'d> StageCompiler<'d> {
}
}
/// Validate the next stage of the pipeline.
/// Validate and compile the next stage of the pipeline.
///
/// For Naga shader modules, validate the module, and update `self` to
/// reflect this stage's outputs and resource usage.
/// For Naga shader modules, validate the module using the provided override
/// values, and generate a `wgpu_hal` shader module from it. Update `self`
/// to reflect this stage's outputs and resource usage.
///
/// Passthrough modules cannot be checked, and are an error if the
/// pipeline's layout is being derived.
///
/// In either case, on success, return a [`CompiledStage`] that borrows the
/// hal module.
/// In either case, on success, return a [`CompiledStage`] that owns (in the
/// Naga case) or borrows (in the passthrough case) the hal module.
pub fn compile<'a>(
&mut self,
desc: &'a pipeline::ProgrammableStageDescriptor<'_>,
stage: validation::ShaderStageForValidation,
) -> Result<CompiledStage<'a>, CreatePipelineError> {
) -> Result<CompiledStage<'a>, CreatePipelineError>
where
'd: 'a,
{
let stage_bit = stage.to_wgt_bit();
let stage_err = |error| CreatePipelineError::Stage {
stage: stage_bit,
@@ -115,11 +156,24 @@ impl<'d> StageCompiler<'d> {
.finalize_entry_point_name(stage.to_naga(), desc.entry_point.as_deref())
.map_err(stage_err)?;
let module = match *state {
match *state {
ShaderModuleState::NagaModule {
ref interface,
ref raw,
ref shader,
runtime_checks,
} => {
let (module, info) = naga::back::pipeline_constants::process_overrides(
&shader.module,
&shader.info,
Some((stage.to_naga(), &entry_point)),
&desc.constants,
)
.map_err(|error| CreatePipelineError::PipelineConstants {
stage: stage_bit,
message: error.to_string(),
})?;
let interface =
validation::Interface::new(&module, &info, self.device.limits.clone());
self.io = interface
.check_stage(
&mut self.resources,
@@ -130,7 +184,50 @@ impl<'d> StageCompiler<'d> {
)
.map_err(stage_err)?;
self.validated |= stage_bit;
&**raw
// `process_overrides` returns a fresh copy when the module has overrides
// or more than one entry point; otherwise these `into_owned` calls clone
// it. That's not ideal: `wgpu_hal` doesn't actually need the `Module` or
// `ModuleInfo` any more once it's created the pipeline, so it should be
// satisfied with a borrow. But since `wgpu_hal::ShaderModule` owns its
// contents, we can't avoid this until wgpu#10543 is fixed.
let hal_shader = hal::ShaderInput::Naga(hal::NagaShader {
module: Cow::Owned(module.into_owned()),
info: info.into_owned(),
debug_source: shader.debug_source.clone(),
});
let hal_desc = hal::ShaderModuleDescriptor {
label: hal_label(
Some(shader_module.label.as_str()).filter(|label| !label.is_empty()),
self.device.instance_flags,
),
runtime_checks,
};
let raw = unsafe {
self.device
.raw()
.create_shader_module(&hal_desc, hal_shader)
}
.map_err(|error| match error {
hal::ShaderError::Device(error) => {
CreatePipelineError::Device(self.device.handle_hal_error(error))
}
hal::ShaderError::Compilation(message) => CreatePipelineError::Internal {
stage: stage_bit,
message,
},
})?;
Ok(CompiledStage {
module: StageModule::Generated(GeneratedModule {
device: self.device,
raw: ManuallyDrop::new(raw),
}),
entry_point,
// The overrides have already been applied.
constants: Cow::Owned(Default::default()),
zero_initialize_workgroup_memory: desc.zero_initialize_workgroup_memory,
})
}
ShaderModuleState::Passthrough { ref raw, .. } => {
if let validation::BindingLayoutSource::Derived(_) = self.resources.layout {
@@ -138,25 +235,27 @@ impl<'d> StageCompiler<'d> {
pipeline::ImplicitLayoutError::Passthrough(stage_bit),
));
}
&**raw
Ok(CompiledStage {
module: StageModule::Passthrough(&**raw),
entry_point,
constants: Cow::Borrowed(&desc.constants),
zero_initialize_workgroup_memory: desc.zero_initialize_workgroup_memory,
})
}
};
Ok(CompiledStage {
module,
entry_point,
constants: &desc.constants,
zero_initialize_workgroup_memory: desc.zero_initialize_workgroup_memory,
})
}
}
}
impl CompiledStage<'_> {
pub fn to_hal(&self) -> hal::ProgrammableStage<'_, dyn hal::DynShaderModule> {
let module = match self.module {
StageModule::Generated(ref generated) => &**generated.raw,
StageModule::Passthrough(raw) => raw,
};
hal::ProgrammableStage {
module: self.module,
module,
entry_point: &self.entry_point,
constants: self.constants,
constants: &self.constants,
zero_initialize_workgroup_memory: self.zero_initialize_workgroup_memory,
}
}
+33 -6
View File
@@ -76,9 +76,11 @@ pub struct PassthroughInterface {
#[expect(clippy::large_enum_variant)]
#[derive(Debug)]
pub enum ShaderModuleState {
/// A Naga module, from which we generate a `wgpu_hal` shader module
/// for each pipeline stage that uses it.
NagaModule {
raw: Box<dyn hal::DynShaderModule>,
interface: validation::Interface,
shader: hal::NagaShader,
runtime_checks: wgt::ShaderRuntimeChecks,
},
Passthrough {
raw: Box<dyn hal::DynShaderModule>,
@@ -113,8 +115,8 @@ impl Drop for ShaderModule {
return;
};
match state {
ShaderModuleState::NagaModule { raw, .. }
| ShaderModuleState::Passthrough { raw, .. } => unsafe {
ShaderModuleState::NagaModule { .. } => {}
ShaderModuleState::Passthrough { raw, .. } => unsafe {
self.device.raw().destroy_shader_module(raw);
},
}
@@ -174,8 +176,8 @@ impl ShaderModule {
) -> Result<String, validation::StageError> {
let state = self.state()?;
match state {
ShaderModuleState::NagaModule { ref interface, .. } => {
interface.finalize_entry_point_name(stage, entry_point)
ShaderModuleState::NagaModule { ref shader, .. } => {
finalize_naga_entry_point_name(&shader.module, stage, entry_point)
}
ShaderModuleState::Passthrough { ref interface, .. } => {
finalize_passthrough_entry_point_name(interface, entry_point)
@@ -184,6 +186,31 @@ impl ShaderModule {
}
}
fn finalize_naga_entry_point_name(
module: &naga::Module,
stage: naga::ShaderStage,
entry_point: Option<&str>,
) -> Result<String, validation::StageError> {
let mut candidates = module.entry_points.iter().filter(|ep| ep.stage == stage);
if let Some(name) = entry_point {
return match candidates.find(|ep| ep.name == name) {
Some(ep) => Ok(ep.name.clone()),
None => Err(validation::StageError::NoEntryPointWithNameForStage {
stage,
name: name.to_owned(),
}),
};
}
let Some(first) = candidates.next() else {
return Err(validation::StageError::NoEntryPointForStage(stage));
};
if candidates.next().is_some() {
return Err(validation::StageError::AmbiguousEntryPointForStage(stage));
}
Ok(first.name.clone())
}
fn finalize_passthrough_entry_point_name(
interface: &PassthroughInterface,
entry_point: Option<&str>,
-41
View File
@@ -1514,47 +1514,6 @@ impl Interface {
.unwrap_or_default()
}
/// Select an entry point name, given an optional name and a shader stage.
///
/// See [`ShaderModule::finalize_entry_point_name`] for details.
///
/// [`ShaderModule::finalize_entry_point_name`]: crate::pipeline::ShaderModule::finalize_entry_point_name
pub fn finalize_entry_point_name(
&self,
stage: naga::ShaderStage,
entry_point_name: Option<&str>,
) -> Result<String, StageError> {
match entry_point_name {
Some(name) => {
// Ensure that there is an entry point for `stage` with the
// given name, and return the name.
let key = EntryPointKey(stage, name.to_string());
if !self.entry_points.contains_key(&key) {
return Err(StageError::NoEntryPointWithNameForStage {
stage,
name: name.to_string(),
});
}
Ok(key.1)
}
None => {
// Ensure that there is exactly one entry point for `stage`, and
// return its name.
let mut entry_points = self
.entry_points
.keys()
.filter(|&&EntryPointKey(key_stage, _)| key_stage == stage);
let Some(EntryPointKey(_, first_name)) = entry_points.next() else {
return Err(StageError::NoEntryPointForStage(stage));
};
if entry_points.next().is_some() {
return Err(StageError::AmbiguousEntryPointForStage(stage));
}
Ok(first_name.clone())
}
}
}
/// Analyze and validate an entry point for use as a given shader stage.
///
/// Validate the entry point named `entry_point_name` for use in