使用Facet测试WebGPU数据布局
摘要
本文解释了Rust和WebGPU之间结构布局的细微差异,并介绍了使用naga进行单元测试的方法,以验证内存偏移,从而实现更安全的GPU计算着色器配置。
暂无内容
查看缓存全文
缓存时间: 2026/09/30 08:00
# 使用Facet测试WebGPU数据布局
来源:https://www.mattkeeter.com/blog/2026-08-23-wgpu-facet/
在编写GPU计算着色器时,通常需要在主机端与着色器之间共享配置数据片段。以下是一个改编自`fidget-wgpu`(https://docs.rs/fidget-wgpu/latest/fidget_wgpu/)的简单示例:
```
// WGSL
struct Config {
/// 屏幕到模型的变换矩阵
mat: mat3x3f,
/// 图像尺寸(像素)
image_size: vec2u,
/// 渲染图像的Z轴位置
z: f32,
}
```
```
// Rust
#[derive(zerocopy::IntoBytes, zerocopy::Immutable, zerocopy::FromBytes, zerocopy::KnownLayout)]
#[repr(C)]
struct Config {
mat: [[f32; 3]; 3],
image_size: [u32; 2],
z: f32,
}
```
得益于`zerocopy`(https://docs.rs/zerocopy/)的注解,我们可以调用`as_bytes()`将配置数据直接写入WebGPU缓冲区,这非常方便!
但不幸的是,Rust与WebGPU的布局规则常存在细微差异。你知道上述示例的问题出在哪里吗?
更糟糕的是,我正在编写在计算着色器中运行的字节码虚拟机,其故障模式通常是:"恭喜,你的GPU现在拥有持续旋转的线程,只能通过重启计算机才能终止"。在调试最近一次重启后(感谢WGSL偏移量计算工具 https://webgpufundamentals.org/webgpu/lessons/resources/wgsl-offset-computer.html),我决定以更系统的方式解决这个问题。
---
现有方案:`wgsl_to_wgpu`(https://docs.rs/wgsl_to_wgpu)、`wgsl_bindgen`(https://docs.rs/wgsl_bindgen)和`encase`(https://docs.rs/encase/latest/encase/)都与该问题相关。但我决定自己实现以避免更多外部依赖和构建脚本的复杂性。具体而言,我决定编写**单元测试**,从而不为常规构建增加开销。(若要严格来说,使用单元测试确实存在忘记测试新配置对象的故障模式,但我并不太担心)
我们可以使用`naga`(https://docs.rs/naga/)来查找WGSL`struct`的布局(该库已包含在我们的着色器编译依赖中):
```
let module = naga::front::wgsl::parse_str(code).expect("valid WGSL");
let members = module
.types
.iter()
.find_map(|(_, ty)| {
if ty.name.as_deref() == Some("Config")
&& let naga::TypeInner::Struct { members, .. } = &ty.inner
{
Some(members)
} else {
None
}
})
.expect("could not find struct");
```
然后,我们可以交叉验证`struct Config`的每个成员:
```
let expected_offsets = [
("mat", std::mem::offset_of!(Config, mat)),
("image_size", std::mem::offset_of!(Config, image_size)),
("z", std::mem::offset_of!(Config, z)),
];
for (field_name, rust_offset) in expected_offsets {
let wgsl_member = members
.iter()
.find(|m| m.name.as_deref() == Some(field_name))
.unwrap_or_else(|| {
panic!("field `{field_name}` missing in WGSL struct")
});
assert_eq!(
wgsl_member.offset as usize,
rust_offset,
"offset mismatch for field `{field_name}`"
);
}
```
果然,这确实发现了问题!
```
thread 'pixel::test::blog_test' (532515) panicked at fidget-wgpu/src/pixel/mod.rs:1762:13:
assertion `left == right` failed: offset mismatch for field `image_size`
left: 48
right: 36
```
在WGSL中,`mat3x3`的每行有4字节填充,因此每行总长为16字节,整个矩阵为48字节。而在Rust中,`[[f32; 3]; 3]`对象是紧凑打包的,因此仅占36字节。测试虽能运行,但这种方法存在两个问题:
- 首先,我们必须硬编码`Config`的每个成员,这既繁琐又易错!若要测试多个配置对象,需手动编写每个并保持同步。
- 其次,错误信息不够完善,因为我们无法直接比较字段大小。`image_size`偏移错误的原因在于`mat`的尺寸不匹配,我们应报告直接原因。(这也意味着我们不会报告末尾字段的尺寸错误)
---
`facet`(https://facet.rs/)是一个为Rust提供运行时反射的库。通过在`struct`上标注`#[derive(facet::Facet)]`,你会获得可在运行时检查的`SHAPE`关联类型。我们可以用它自动检查`Config`对象!
让我们逐步介绍这个泛型检查器函数,它以`T: facet::Facet`为参数。首先解析着色器并通过名称提取配置`struct`;这与之前基本相同:
```
pub(crate) fn compare_struct_layout<T: facet::Facet>(
shader: &str,
struct_name: &str,
) {
// [1] 解析WGSL(与之前相同)
let module = naga::front::wgsl::parse_str(shader)
.expect("valid WGSL");
let (members, span) = module
.types
.iter()
.find_map(|(_, ty)| {
if ty.name.as_deref() == Some(struct_name)
&& let naga::TypeInner::Struct { members, span } = &ty.inner
{
Some((members, *span))
} else {
None
}
})
.expect("could not find struct");
```
接下来检查整体对象大小。这里有一个细节:我经常在配置对象的末尾使用运行时大小数组(https://www.w3.org/TR/WGSL/#runtime-sized)。(可将其视为C中的弹性数组成员(https://en.wikipedia.org/wiki/Flexible_array_member)或Rust中的动态大小类型(https://doc.rust-lang.org/reference/dynamically-sized-types.html))
在WGSL中的示例:
```
struct VoxelConfig {
mat: mat4x4f,
axes: vec3u,
tape_data_offset: atomic,
render_size: vec3u,
tape_data_capacity: u32,
image_size: vec3u,
root_tape_len: atomic,
tape_data: array<u32>, // <- 运行时大小数组
}
```
编写Rust的`struct`等效体时,会省略最后一个成员。若在`naga`中存在运行时大小数组,我们将不检查`naga`报告的对象总大小,而是检查`tape_data`的`offset`是否与Rust`struct`的大小匹配。以下是该检查部分的代码:
```
// [2] 检查`struct`整体大小
//
// 若结构体最后一个成员是运行时大小数组,
// 我们将数组起始偏移量视为结构体大小。
let dynamic_array_offset = members.last().and_then(|m| {
let ty = &module.types[m.ty];
let naga::TypeInner::Array {
base: _,
size: naga::ir::ArraySize::Dynamic,
stride: _,
} = &ty.inner else {
return None;
};
Some(m.offset)
});
if let Some(dynamic_array_offset) = dynamic_array_offset {
assert_eq!(
dynamic_array_offset as usize,
std::mem::size_of::<T>()
);
} else {
assert_eq!(span as usize, std::mem::size_of::<T>());
}
```
接下来,我们检查字段大小和偏移。这与之前手动逐字段检查的思路相同,但使用Facet的内省数据在运行时执行检查(同时也检查成员大小)。
```
// [3] 检查Rust与WGSL之间的字段大小和偏移
let facet::Type::User(facet::UserType::Struct(shape)) = T::SHAPE.ty
else {
panic!("must build a struct");
};
let mut shape_field_names = HashSet::new(); // 用于后续步骤
for field in shape.fields {
let field_name = field.name;
shape_field_names.insert(field_name);
let wgsl_member = members
.iter()
.find(|m| m.name.as_deref() == Some(field_name))
.unwrap_or_else(|| {
panic!("field `{field_name}` missing in WGSL struct")
});
assert_eq!(
wgsl_member.offset as usize,
field.offset,
"offset mismatch for field `{field_name}`"
);
assert_eq!(
module.types[wgsl_member.ty]
.inner
.size(&module.to_ctx()) as usize,
field
.shape()
.layout
.sized_layout()
.unwrap()
.size(),
"size mismatch for field `{field_name}`"
);
}
```
最后,我们反向检查,确认每个WGSL成员都出现在Rust`struct`中(末尾的运行时大小数组除外):
```
// [4] 检查所有WGSL成员是否在Rust中存在
let slice_len = if dynamic_array_offset.is_some() {
members.len() - 1
} else {
members.len()
};
for m in &members[..slice_len] {
assert!(
shape_field_names.contains(
m.name
.as_ref()
.expect("cannot check unnamed WGSL fields")
.as_str()
),
"field `{field_name}` missing in Rust struct"
);
}
```
这个泛型检查器函数编写起来稍有些复杂,但一旦完成,就可以轻松应用于我的所有配置对象。我仅在单元测试中条件性地派生`Facet`,例如:
```
#[derive(zerocopy::IntoBytes, zerocopy::Immutable, zerocopy::FromBytes, zerocopy::KnownLayout)]
#[cfg_attr(test, derive(facet::Facet))] // <- 仅在测试中派生
#[repr(C)]
struct Config {
mat: [[f32; 3]; 3],
image_size: [u32; 2],
z: f32,
}
```
然后,我几乎免费获得了这些测试:
```
#[test]
fn color_config_layout() {
crate::test::compare_struct_layout::<ColorConfig>(
&color_shader(16),
"ColorConfig",
);
}
#[test]
fn merge_config_layout() {
crate::test::compare_struct_layout::<MergeConfig>(
&merge_shader(),
"MergeConfig",
);
}
#[test]
fn shade_config_layout() {
crate::test::compare_struct_layout::<ShadeConfig>(
&shade_shader(),
"ShadeConfig",
);
}
#[test]
fn ssao_config_layout() {
crate::test::compare_struct_layout::<SsaoConfig>(
&ssao_shader(),
"SsaoConfig",
);
}
#[test]
fn blur_config_layout() {
crate::test::compare_struct_layout::<BlurConfig>(
&blur_shader(),
"BlurConfig",
);
}
```
幸运的是,这些测试并未发现我的配置对象中任何预存问题——这并不奇怪,因为一切运行正常。尽管如此,下次我添加新的计算着色器时,对数据加载正确性的信心将更足!
很容易想象将此类测试用于其他CPU-GPU数据交换,虽然在此处意义不大(我系统中的所有其他数据类型都很简单),但对其他项目可能很相关!
最后一点,Facet(https://facet.rs/)非常出色,人们应该更广泛地使用它。我可能应该写另一篇博文介绍它在Fidget中的其他应用;它为从Rust形状定义到Rhai(https://rhai.rs/)函数的某些真正可怕的自动生成绑定提供了基础。如果这听起来有趣,欢迎通过RSS(https://www.mattkeeter.com/atom.xml)订阅或在社交媒体(https://bsky.app/profile/mattkeeter.com)(https://hachyderm.io/@mjk)上关注我。
相似文章
Show HN: cuTile Rust:在Rust中编写安全、无数据竞争的GPU内核
NVIDIA Labs发布了cuTile Rust,这是一个基于瓦片的系统,用于用地道的Rust编写内存安全、无数据竞争的GPU内核。它将Rust的所有权模型扩展到GPU内核,通过JIT将Rust的AST编译为GPU代码,并实现接近原生CUDA的性能。
Rust 中的 GPU 卸载:可移植、安全且快速
本文介绍了一种零开销、多厂商的 GPU 编译框架,该框架内置于 Rust 编译器中,利用 Rust 的所有权模型确保内存安全,并实现与原生 CUDA 和 HIP 基准相媲美的性能。
GPU上的无畏并发:在Rust中进行安全的GPU推理,与vLLM/SGLang竞争 [R]
cuTile Rust 引入了一种基于块(tile)的编程模型,利用 Rust 的所有权机制来保证 GPU 内核的内存安全和无数据竞争,基于该模型构建的 Grout 推理引擎在 Qwen3 模型上实现了与 vLLM/SGLang 相当的吞吐量。
@tom_doerr: 基于 Rust 的模块化 GraphRAG 实现,支持 WebGPU 加速。https://github.com/automataIA/graphrag-rs…
一种模块化、高性能的 GraphRAG(基于图的检索增强生成)Rust 实现,支持 WebGPU 加速,并提供三种部署架构:仅服务器、仅 WASM(客户端)以及混合模式。
引入 CUDA Rust:编写 GPU 内核的两种途径
NVIDIA 推出 CUDA Rust,提供两种途径(SIMT 和 Tile),用于原生用 Rust 编写 GPU 内核,从而提升 AI 系统的性能和开发体验。