FacetでWebGPUデータレイアウトをテストする
Testing WebGPU data layouts with Facet (mattkeeter.com)
要約
GPUコンピューティングシェーダーでは、ホストとシェーダー間で設定データを共有することが一般的ですが、RustとWebGPUのレイアウト規則には微妙な違いが存在することがあります。この記事では、これらのレイアウトの不一致を体系的にデバッグするために、RustのライブラリであるFacetを使用して、WGSL構造体とRust構造体のフィールドサイズとオフセットを自動的に比較するテスト手法を紹介しています。これにより、開発者はGPUコードの信頼性を高めることができます。
全文翻訳
Facet を使った WebGPU データレイアウトのテスト
GPU コンピュートシェーダーを開発していると、ホストとシェーダー間で設定データを共有したい場面がよくあります。これは 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 アノテーションのおかげで、as_bytes() を呼び出し、設定データを直接 WebGPU バッファに書き込むことができます。これは非常に便利です!
残念ながら、Rust と WebGPU のレイアウト規則の間には、しばしば微妙な違いが存在します。上記の例で何が間違っているか分かりますか?
さらに残念なことに、私はバイトコード VM をコンピュートシェーダー内で実行しており、その失敗モードはしばしば「おめでとうございます、あなたの GPU は再起動しないとキルできない、永続的に回転するスレッドを持つようになりました」というものです。
直近の再起動(WGSL オフセットコンピューターのおかげで)をデバッグした後、より体系的な方法で問題を修正することにしました。
既存の選択肢としては、wgsl_to_wgpu、wgsl_bindgen、encase などがこの問題に関連しています。しかし、私は外部依存関係やビルドスクリプトの煩雑さを避けるために、独自のものを書くことにしました。具体的には、単体テストを書いて、通常のビルドにオーバーヘッドを追加しないようにしました。
(厳密に言えば、単体テストを使用することには、新しい設定オブジェクトをテストし忘れるという失敗モードがありますが、私はそれほど心配していません)
WGSL の struct レイアウトは naga を使って見つけることができます。これはすでにシェーダーコンパイルのための依存関係ツリーに含まれています。
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 バイトしか占有しません。
テストは成功しましたが、このアプローチには 2 つの問題があります。
- 第一に、
Configの各メンバーをハードコーディングする必要があり、これは扱いにくく、間違いやすいです!複数の設定オブジェクトをテストしたい場合、それぞれを手書きで作成し、同期させる必要があります。 - 第二に、フィールドのサイズを直接比較できないため、エラーメッセージが良くありません。
image_sizeが間違ったオフセットを持つ理由は、matのサイズが一致しないためです。近接原因を報告すべきです。(これは、最後のメンバーのサイズが間違っていても報告されないことを意味します)
どうすればよいでしょうか?
facet は、実行時リフレクションを提供する Rust のライブラリです。構造体に #[derive(facet::Facet)] をアノテーションすることで、実行時に検査できる SHAPE 関連型が得られます。
これを使用して Config オブジェクトを自動的にチェックできます!
ジェネリックチェッカー関数を、T: facet::Facet でパラメータ化して見ていきましょう。まず、シェーダーを解析し、名前で設定 struct を抽出します。これは基本的に以前と同じです。
pub(crate) fn compare_struct_layout<T: facet::Facet<'static>>(
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");
次に、オブジェクト全体のサイズをチェックします。ここには 1 つの微妙な点があります。私は、設定オブジェクトの最後のメンバーとして、実行時サイズ配列 を利用することがよくあります。(これは C における フレキシブル配列メンバー や、Rust における 動的サイズ型 のようなものです)
WGSL では次のようになります。
struct VoxelConfig {
mat: mat4x4f,
axes: vec3u,
tape_data_offset: atomic<u32>,
render_size: vec3u,
tape_data_capacity: u32,
image_size: vec3u,
root_tape_len: atomic<u32>,
tape_data: array<TapeWord>, // <- 実行時サイズ配列
}
対応する 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 は素晴らしいライブラリであり、もっと多くの人に使うべきです。おそらく、Fidget の他の場所でどのように使用されているかについて、別のブログ記事を書くべきでしょう。それは、Rust の形状定義から Rhai 関数への、真に恐ろしい自動生成バインディングのバックボーンを提供します。もしそれが興味深いと思ったら、RSS で購読したり、ソーシャルメディア や メディア でフォローしてください。