Rule 8.7

Chapter 8, Functions and entry points Test

@compute carries the workgroup size as an array literal of one to three whole numbers, x, y and z, a missing y or z being 1, and the default is 64; every extent reaches the emitted @workgroup_size and the reflection, and a shape over WebGPU’s default compute limits must be reported as a warning.

The rule text and the parts under it are the compiler's own English, as the design document writes them.

Rationale

an argument the decorator cannot read must not fall through to a default the author did not ask for, and an extent the author wrote must not be dropped. The limits are the device’s, not the language’s: a device requested with raised limits runs a larger workgroup, so a shape over the defaults compiles, and the warning says which limit the host has to raise.

Derives from

workgroup_size; WebGPU Limits (maxComputeWorkgroupSizeX and Y 256, Z 64, maxComputeInvocationsPerWorkgroup 256); #118.

How it is verified

Checked by a test. A test, a gate script or a CI workflow names this rule, and the traceability check fails when a file listed below stops naming it.

Where the rule says the compiler enforces it:

TS8037 WORKGROUP_ARG, where a bare @compute emits @workgroup_size(64) and the object form is refused (@compute takes an array of one to three whole numbers, "@compute([64, 1, 1])", or no argument for the default of 64; "{ workgroup: [64, 1, 1] }" is not a workgroup shape.);
TS8026 WORKGROUP_SHAPE, a warning naming the first default limit the shape exceeds;
SD0111, which keeps a portable kernel’s workgroup one-dimensional, since the WebGL2 lowering has no workgroup;
surface §3’s bullets on the payload of @compute, under the entry example, which state the default of 64, the emitted spelling of a two- or three-dimensional shape, the limits warning, and the refused object form.

The files that verify it at commit 26de7be8, each at the first line that names the rule:

src/compiler/ts/stage3.test.ts:6

Explained in

The sections of the surface document that explain this rule, at commit 26de7be8:

§3 Entries — function decorators and explicit builtins

Error codes that enforce it

The diagnostic codes the rule names under Enforced by, or whose registry text names the rule:

SD0111: portable kernel outside the gather-only tier
TS8026 WORKGROUP_SHAPE: A warning: @compute([x, y, z]) exceeds one of WebGPU's default compute limits (x and y 256, z 64, 256 invocations in all), so a device requested without raising that limit refuses the pipeline.
TS8037 WORKGROUP_ARG: @compute(...) with an argument that is not an array literal of one to three whole numbers: an object, a bare number, an identifier, an empty or four-wide array.

Source

The rule at commit 26de7be8:

docs/language-design.md:664 (the design document)
reqs/rules/RULE-0807.md (its traceability item)

Edit this page Report a problem