diff --git a/.claude/skills/cts-triage/SKILL.md b/.claude/skills/cts-triage/SKILL.md new file mode 100644 index 000000000..f50b6c8c9 --- /dev/null +++ b/.claude/skills/cts-triage/SKILL.md @@ -0,0 +1,276 @@ +--- +name: cts-triage +description: Run CTS test suites and investigate failures +--- + +# Triage Process + +When working on a category of CTS tests, follow this systematic process to identify issues, prioritize fixes, and document findings. + +## Step 0: Divide Into Manageable Chunks + +List all the tests matching a selector: + +```bash +cargo xtask cts -- --list 'webgpu:api,validation,*' 2>&1 | wc -l +``` + +If there is a reasonable number of tests matching the selector (less than a +couple hundred or so, but this isn't a hard cutoff), then you can proceed with +triage. Otherwise, make a list of more detailed wildcards that match fewer +tests, verify that each wildcard matches a reasonable number of tests, and +triage each wildcard separately. + +## Step 1: Get Overall Statistics + +Run the full test suite for the category to understand the scope: + +```bash +cargo xtask cts 'webgpu:api,validation,category:*' 2>&1 | grep -E "(Summary|Passed|Failed)" | tail -5 +``` + +This gives you the pass rate and number of failures. Document this as your baseline. + +## Step 2: Identify Test Subcategories + +Review the output from the running the CTS (with or without `--list`) to +identify any subcategories that may exist within the suite being analyzed. +Subcategories typically have an additional `:`- or `,`-delimited word in the +test name. Running tests by subcategory may be more manageable than running +with the entire suite at once or running individual tests. + +## Step 3: Run Each Subcategory + +Test each subcategory individually to identify which ones are passing vs failing: + +```bash +cargo xtask cts 'webgpu:api,validation,category:subcategory:*' 2>&1 | grep -E "(Passed|Failed|Skipped)" | tail -3 +``` + +Track the pass rate for each subcategory. This helps you identify: +- What's already working (don't break it!) +- Where the failures are concentrated +- Which issues affect multiple categories + +## Step 4: Analyze Failure Patterns + +For failing subcategories, look at what tests are failing: + +```bash +cargo xtask cts 'webgpu:api,validation,category:subcategory:*' 2>&1 | grep "\[fail\]" | head -20 +``` + +Look for patterns: +- **Format-specific failures**: May indicate missing format capability checks +- **Parameter-specific failures**: Validation missing for specific parameter combinations + +## Step 5: Examine Specific Failures + +Pick a representative failing test and run it individually to see the error: + +```bash +cargo xtask cts 'webgpu:api,validation,category:subcategory:specific_test' 2>&1 | tail -30 +``` + +Look for: +- **"EXPECTATION FAILED: DID NOT REJECT"**: wgpu is accepting invalid input (validation gap) +- **"Validation succeeded unexpectedly"**: Similar to above +- **"Unexpected validation error occurred"**: wgpu is rejecting valid input +- **Error message content**: Tells you what validation is triggering or missing + +## Step 6: Check CTS Test Source + +To understand what the test expects, read the TypeScript source: + +```bash +grep -A 40 "test_name" cts/src/webgpu/api/validation/path/file.spec.ts +``` + +The test source shows: +- What configurations are being tested +- What the expected behavior is (pass/fail) +- The validation rules from the WebGPU spec +- Comments explaining the rationale + +## Step 7: Categorize Issues + +Group failures into categories: + +**High Priority - Validation Gaps:** +- wgpu accepts invalid configurations that should fail +- Security or correctness implications +- Example: Accepting wrong texture formats, missing aspect checks + +**Medium Priority - Spec Compliance:** +- Edge cases not handled correctly +- Optional field validation issues +- Example: depthCompare optional field handling + +**Low Priority - Minor Gaps:** +- Less common scenarios +- Limited real-world impact +- Example: Depth bias with non-triangle topologies + +**Known Issues - Skip:** +- Known failure patterns (documented in AGENTS.md) +- Track count but don't try to fix + +## Step 8: Identify Root Causes + +For validation gaps, find where validation should happen: + +1. **Search for existing validation:** + ```bash + grep -n "relevant_keyword" wgpu-core/src/device/resource.rs + ``` + +2. **Look for render/compute pipeline creation:** + - Render pipeline: `wgpu-core/src/device/resource.rs` around `create_render_pipeline` + - Compute pipeline: Similar location + - Look for existing validation patterns you can follow + +3. **Check for helper functions:** + ```bash + grep "fn is_" wgpu-types/src/texture/format.rs + ``` + +4. **Find error enums:** + ```bash + grep "pub enum.*Error" wgpu-core/src/pipeline.rs + ``` + +## Step 9: Implement Fixes + +When implementing fixes: + +1. **Add error variants if needed** (in `wgpu-core/src/pipeline.rs`) +2. **Add helper methods** (in `wgpu-types` if checking properties) +3. **Add validation checks** (in `wgpu-core/src/device/resource.rs`) +4. **Test the fix** with specific failing tests +5. **Run full subcategory** to verify all related tests pass +6. **Check you didn't break passing tests** + +## Step 10: Document Findings + +Create or update a triage document (e.g., `category_triage.md`). + +Do not write information about changes you have made to the triage document. Only capture the state of the tests and any investigation into open issues. + +````markdown +# Category CTS Tests - Triage Report + +**Overall Status:** XP/YF/ZS (%/%/%) + +## Passing Sub-suites ✅ +[List sub-suites that have no failures (all pass or skip)] + +## Remaining Issues ⚠️ +[List sub-suites that have failures and if it can be stated concisely, a summary of the issue] + +## Issue Detail +[List detail of any investigation into failures. Do not go into detail about passed suites, just list the failures.] + +### 1. title, e.g. a distinguishing word from the test selector +**Test selector:** `webgpu:api,validation,render_pipeline,depth_stencil_state:format:*` +**What it tests:** [Description] +**Example failure:** +[a selector for a single failing test, e.g.:] +``` +webgpu:api,validation,render_pipeline,depth_stencil_state:depthCompare_optional:isAsync=false;format="stencil8" +``` + +**Error:** +[error message from the failing tests, e.g.:] +``` +Unexpected validation error occurred: Depth/stencil state is invalid: +Format Stencil8 does not have a depth aspect, but depth test/write is enabled +``` + +**Root cause:** +[Your analysis of the root cause. Do not speculate. Only include the results of specific investigation you have done.] +The validation is triggering incorrectly. When `depthCompare` is undefined/missing in JavaScript, it's getting translated to a default value that makes `is_depth_enabled()` return true, even for stencil-only formats. + +**Fix needed:** +[Your proposed fix. Again, do not speculate. Only state the fix if it is obvious from the root cause analysis, or if you have done specific investigation into how to fix it.] + +### 2. title +[repeat as needed for additional issues] +```` + +## Step 11: Update test.lst + +For fixed tests that are now passing, add them to `cts_runner/test.lst`: + +1. **Use wildcards** to minimize lines: + ``` + webgpu:api,validation,category:subcategory:isAsync=false;* + ``` + +2. **Group related tests** when possible: + - If multiple subcategories all pass, use a higher-level wildcard + - Example: `webgpu:api,validation,category:*` if all subcategories pass + +3. **Maintain alphabetical order** roughly in the file + +## Step 12: Verify and Build + +Before finishing: + +```bash +# Format code +cargo fmt + +# Check for errors +cargo clippy --tests + +# Build to ensure no compilation errors +cargo build + +# Run the tests you added to test.lst +cargo xtask cts 'webgpu:api,validation,category:subcategory:isAsync=false;*' +``` + +# Common Patterns + +If the user asked to investigate a failure, and the cause of the failure is +noted here with "do not attempt to fix", then stop and ask the user before +attempting to fix. + +**Pattern: Format-specific failures** +- Check if format validation is missing +- Look for `is_depth_stencil_format()`, `is_color_format()` etc. +- May need to add format capability checks + +**Pattern: Aspect-related failures** +- Check if code validates format aspects (DEPTH, STENCIL, COLOR) +- Use `hal::FormatAspects::from(format)` to check +- Validate operations match available aspects + +**Pattern: Optional field failures** +- May be WebGPU optional field semantics issue +- Check if undefined in JS becomes a default value in Rust +- May need to distinguish "not set" from "set to default" + +**Pattern: Atomics accepted incorrectly** +- Naga allows referencing an atomic directly in an expression +- Should only allow accessing via `atomicLoad`, `atomicStore`, etc. +- Only investigate as necessary to confirm this is the issue. Do not attempt to fix. Refer user to https://github.com/gfx-rs/wgpu/issues/5474. + +**Pattern: Error reporting for destroyed resources** +- Tests that check for validation errors when a destroyed resource is used. `wgpu` often reports these errors later than WebGPU requires, causing the tests to fail. +- `wgpu` may report these errors earlier than it should, causing the test to fail with an unexpected validation error. +- Look for: + - Tests with `state="destroyed"` parameter + - Tests checking that operations on destroyed buffers or textures should fail +- Example failing tests: + - `webgpu:api,validation,encoding,cmds,compute_pass:indirect_dispatch_buffer_state:` with `state="destroyed"` subcases +- Only investigate as necessary to confirm this is the issue. Do not attempt to fix. Refer user to https://github.com/gfx-rs/wgpu/issues/7881. + +# Tips + +- **Start with high-impact fixes**: Validation gaps with security implications +- **Look for existing patterns**: Other validation code shows the style +- **Test incrementally**: Fix one category at a time, verify it works +- **Document as you go**: Don't wait until the end to write the triage +- **Ask for clarification**: If test expectations are unclear, check the WebGPU spec or test source +- **Track your progress**: Update pass rates as you fix issues diff --git a/.claude/skills/webgpu-specs/SKILL.md b/.claude/skills/webgpu-specs/SKILL.md new file mode 100644 index 000000000..ddbb58695 --- /dev/null +++ b/.claude/skills/webgpu-specs/SKILL.md @@ -0,0 +1,29 @@ +--- +name: webgpu-specs +description: Download WebGPU and WGSL specifications for use as a reference +allowed-tools: "Bash(sh .claude/skills/webgpu-specs/download.sh)" +--- + +Run `sh .claude/skills/webgpu-specs/download.sh` to download the +WebGPU and WGSL specifications if they are not present or if they have +been updated. You do not need to change directory before running the script. + +After the specs are downloaded, you can search in `target/claude/webgpu-spec.bs` +and `target/claude/wgsl-spec.bs` for relevant sections of the specification. + +When referencing the specifications, prefer to use named anchors rather than +line numbers. For example, to reference the "Object Descriptors" section, which has the +following header: + +``` +### Object Descriptors ### {#object-descriptors} +``` + +Use the URL so the user +can click to navigate directly to that section. + +For the WGSL specification, the base URL is . + +If necessary, read additional content from the file to find the header preceding +the text you want to reference. You may provide line numbers as additional +context, but always make every effort to provide the user with a clickable link. diff --git a/.claude/skills/webgpu-specs/download.sh b/.claude/skills/webgpu-specs/download.sh new file mode 100644 index 000000000..dc09ee6a2 --- /dev/null +++ b/.claude/skills/webgpu-specs/download.sh @@ -0,0 +1,23 @@ +#!/bin/sh + +set -e + +TARGET_DIR="$(cargo metadata --format-version 1 | jq -r ".target_directory")" + +WEBGPU="$TARGET_DIR/claude/webgpu-spec" +WGSL="$TARGET_DIR/claude/wgsl-spec" +mkdir -p "$TARGET_DIR/claude" + +if [ -f "$WEBGPU.etag" ]; then + curl --etag-save "$WEBGPU.etag.new" --etag-compare "$WEBGPU.etag" -fsSL https://raw.githubusercontent.com/gpuweb/gpuweb/main/spec/index.bs -o "$WEBGPU.bs" + [ -s "$WEBGPU.etag.new" ] && mv "$WEBGPU.etag.new" "$WEBGPU.etag" || rm "$WEBGPU.etag.new" +else + curl --etag-save "$WEBGPU.etag" https://raw.githubusercontent.com/gpuweb/gpuweb/main/spec/index.bs -o "$WEBGPU.bs" +fi + +if [ -f "$WGSL.etag" ]; then + curl --etag-save "$WGSL.etag.new" --etag-compare "$WGSL.etag" -fsSL https://raw.githubusercontent.com/gpuweb/gpuweb/main/wgsl/index.bs -o "$WGSL.bs" + [ -s "$WGSL.etag.new" ] && mv "$WGSL.etag.new" "$WGSL.etag" || rm "$WGSL.etag.new" +else + curl --etag-save "$WGSL.etag" https://raw.githubusercontent.com/gpuweb/gpuweb/main/wgsl/index.bs -o "$WGSL.bs" +fi diff --git a/.gitignore b/.gitignore index 179184f57..6ff4904f4 100644 --- a/.gitignore +++ b/.gitignore @@ -44,3 +44,6 @@ wgpu/red.png # Temporary clone location for wasm-bindgen mirroring wgpu/src/backend/webgpu/webgpu_sys/wasm_bindgen_clone_tmp + +# LLM-related +.claude/settings.local.json diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..38a8c7ee1 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,197 @@ +# Global instructions + +## Code Style +- Limit the amount of comments you put in the code to a strict minimum. You should almost never add comments, except sometimes on non-trivial code, function definitions if the arguments aren't self-explanatory, and class definitions and their members. +- Do not use emoji. + +## Workflow + +- You can test that the code builds by running `cargo build`. Don't pass `--release` unless there's a specific need to test a release build, it's much slower. +- After making code changes, ensure the code is formatted by using `cargo fmt`, linted by using `cargo clippy --tests`. If there are no errors, you can use `cargo xtask test` and `cargo xtask cts --backend ` to run tests (to fully validate a change, run both). On MacOS, the backend is `metal`. On Windows, the backend is `dx12`. On Linux, the backend is `vulkan`. +- Do not perform commits yourself, ever. +- Use the WebGPU and WGSL specifications as a reference to determine the correct behavior. Do not assume that a behavior is correct just because the CTS expects it. + +## Changelog + +We maintain a changelog in CHANGELOG.md. Changes should be noted in the +changelog if they are user-visible (changes to documented public APIs, +significant bug fixes, or new functionality). Changelog descriptions should be +concise. If you are not sure whether something should be in the CHANGELOG or +you are not sure how to describe the change, ask the user for guidance. + +## More information about tests + +There is some more detailed information about tests in @docs/testing.md. + +# CTS + +## Listing and Running Individual Tests + +Each line is a selector that will run multiple subtests. You can run a test with: + +```bash +cargo xtask cts 'webgpu:selector/path:test:*' +``` + +For fixing problems, it may be useful to run specific cases. You can get a list of the subtests with: + +```bash +cargo xtask cts -- --list 'webgpu:selector,path:test:*' +``` + +Then you can pass individual subtests on the command line as the selector. + +## Running Suites + +To run a suite of CTS tests and keep just the summary at the end: + +```bash +cargo xtask cts 'webgpu:selector,path:test:*' 2>&1 | grep -E "(Summary|Passed|Failed)" | tail -5 +``` + +To run a suite of tests and keep just the failing tests: + +```bash +cargo xtask cts 'webgpu:selector,path:test:*' 2>&1 | grep "\[fail\]" +``` + +## Keeping Track of Results + +We maintain three files listing CTS test selectors that are expected to pass, +not pass, or to be entirely skipped. These files are respectively +cts_runner/test.lst, cts_runner/fail.lst, and cts_runner/skip.lst. + +If you fix a CTS test, add the selector to test.lst. Be aware that the file is +not an exhaustive list of passing tests. + +CI expects every test in test.lst to pass, so only add suites that have zero +failures to test.lst. Do not add any suites that are not 100% pass/skip, even +if they are ≥99% passing. + +List suites with failures in fail.lst. You can put a comment `// xx%` +noting the pass rate, especially in cases where the pass rate is high. + +List suites that are ≥90% skips in skip.lst + +When adding to a lst file, use wildcards to identify the tests with as few lines +as possible. In some cases when adding tests it may be possible to combine with +existing lines to use a higher level wildcard. Only use a higher level wildcard +when all the tests it will match go in the same file. Do not use a higher level +wildcard if it would match tests that belong in a different file. + +## Source for the CTS Tests + +The TypeScript sources for the CTS are under cts/src. There is also generated JavaScript in cts/out. +Do not assume that a behavior is correct just because a CTS test expects it. Verify the correct +behavior in the WebGPU or WGSL specification. + +# Overview of the Code + +See `docs/big-picture.png` for an overview of the system. + +The major components are: + +* `wgpu-hal` implements a backend for each supported graphics API (Vulkan, DX12, Metal, GLES). + +* `wgpu-core` implements the WebGPU API, including resource management and validation. + It calls the platform graphics APIs via `wgpu-hal`, and uses `naga` for shader translation. + +* `wgpu` is the native Rust API. In addition to providing bindings to `wgpu-core`, the `wgpu` + crate can also be compiled to WASM and built against the "WebGPU" backend, where it uses + whatever WebGPU implementation is provided by the WASM environment. `wgpu` is not used + by Deno and Firefox. + +* `naga` is the shader translator. It reads shaders in WGSL, GLSL, or SPIR-V, + translates to Naga IR, and then writes shaders in GLSL, HLSL, MSL (Metal Shading Language), SPIR-V, or WGSL. + It is responsible for validating that WGSL shaders are valid according to the WGSL language specification. + +* `wgpu-types` contains some type definitions that are applicable both to `wgpu-core` and to + the `wgpu` "WebGPU" backend. + +* `deno_webgpu` contains WebGPU bindings for the Deno Javascript runtime. + We also use Deno as a test environment for running the WebGPU CTS. + Only make a change in the Deno bindings if you are sure that the issue + doesn't apply to other clients (Firefox or `wgpu` Rust API). If it does + apply to other clients, the issue should probably be fixed in `wgpu-core`. + + +For a more detailed discussion of the `wgpu` architecture, refer to +. + +## Naga + +### Constant Evaluator (`naga/src/proc/constant_evaluator.rs`) + +The constant evaluator is responsible for evaluating constant expressions at compile time in WGSL/GLSL shaders. + +**Key Components:** + +1. **Expression Handling** (~line 1228): The `try_eval_and_append_impl` method handles different expression types and evaluates them if possible. + +2. **Type Conversions**: + - `cast()` (~line 2256): Handles type conversions with `Expression::As` where `convert` is `Some(width)` + - `bitcast()` (~line 2449): Handles bit reinterpretation with `Expression::As` where `convert` is `None` + - Key insight: For bitcast, the target width equals the source width (bit-preserving operation) + +3. **Helper Macros**: + - `gen_component_wise_extractor!`: Generates functions for component-wise operations on scalars/vectors + - `component_wise_scalar!`, `component_wise_float!`: Convenience macros for applying operations to each component + +4. **Borrow Checker Patterns**: + - When implementing methods that need to call themselves recursively or make multiple mutable borrows, extract all needed data from `self` fields before the recursive calls + - Clone vectors before iterating if you need to mutably borrow `self` during iteration + +## Expression Types and Type Inference + +- `Expression::As` with `convert: None` represents bitcast operations +- The validator (`naga/src/valid/expression.rs` ~line 1132) determines result types by: + - Getting source type's scalar + - Updating the `kind` to target kind + - Keeping the same `width` for bitcast (no conversion) + +# Other + +This is stuff that Claude wrote for itself. It can probably be improved. + +## Naga Tests + +**Test Structure:** + +1. **Unit Tests**: In the same file as the code being tested + - Example: `naga/src/proc/constant_evaluator.rs` has tests in a `#[cfg(test)] mod tests` block + - Pattern: Create arenas, build expressions, evaluate, assert results + +2. **Snapshot Tests**: + - Input files: `naga/tests/in/wgsl/*.wgsl` + - Output files: `naga/tests/out/wgsl/*.wgsl` + - Run with: `cargo test -p naga --test naga snapshots::convert_snapshots_wgsl` + - The output shows how constant expressions are evaluated at compile time + +3. **Adding Integration Tests**: + - Add test WGSL code to `naga/tests/in/wgsl/const-exprs.wgsl` for const expression tests + - The test automatically parses, validates, and generates output in `naga/tests/out/wgsl/wgsl-const-exprs.wgsl` + - Verify constant evaluation by checking the output file + +**Running Tests:** +```bash +# Unit tests only +cargo test -p naga --lib + +# Specific test +cargo test -p naga --lib bitcast + +# All naga tests (including integration) +cargo test -p naga + +# WGSL snapshot tests +cargo test -p naga --test naga snapshots::convert_snapshots_wgsl +``` + +## WGSL Specification Implementation + +When implementing WGSL built-in functions: + +1. **Read the spec carefully**: WGSL spec section numbers are usually commented in code (e.g., "17.2.1. bitcast") +2. **Check parameterization**: The spec lists exactly which type combinations are valid +3. **Don't assume types**: For bitcast, only `i32`, `u32`, `f32` are specified - not 64-bit types +4. **AbstractInt special cases**: Some operations have special handling for abstract integers