[jowens]

This is the next step in moving per-primitive boilerplate into core: WGSL helpers that bring their own dependencies.

Problem

Each kernel listed its WGSL helpers, and everything they need, by hand, in an order that compiles:

• enableSubgroupsIfAppropriate first, then commonDefinitions, subgroupEmulation, binop.wgslfn, subgroupInclusiveOpScan, wgScan, and so on;
• HierarchicalScan and both MultisplitPerm modules repeated the same six lines, DLDFScan listed twelve, and OneSweep spread its list through its module;
• leaving one out failed to compile, and so did listing one twice.

Workgroup memory was counted by hand too. MultisplitPerm's local finish subtracted a magic 3,328 bytes.

Change

• fnDeclarations.include(...helpers):

  • emits each helper and its dependencies once, with enable first;
  • takes [name, args] for helpers with arguments;
  • for inline (statement-level) helpers, adds only what they need at module scope.

  A dependency is satisfied by any inclusion of that helper, whatever its arguments. A helper listed explicitly is emitted once per distinct set of arguments, so exclusive and inclusive wgScan can coexist.

  ${this.fnDeclarations.include(
    "wgScan",
    ["wgHistogram", { name: "cnt", numBins: RADIX, workgroupSize: W }],
    "computeLinearizedGridParametersSplit",
  )}

• fnDeclarations.workgroupBytes(...helpers): the workgroup memory those helpers declare, for the subgroup or emulated variant.

• All five primitives use include():

  • MultisplitPerm's local finish computes its reserve (localFinishReservedBytes: its own arrays plus workgroupBytes) instead of using 3,328 bytes;
  • Histogram's workgroupBins uses workgroupBytes.

• The no-subgroup wgScan, a Hillis–Steele scan in workgroup memory, no longer pulls in subgroup emulation, which it never used.

Checked

• Kernels compared with DLDFScan and OneSweep declare their buffers once; UniformStruct slots #83's, with and without subgroups (61 kernels each). They're unchanged except for two intended differences:

  • Histogram's module now starts with enable subgroups;;
  • emulated HierarchicalScan and MultisplitPerm modules no longer carry the unused emulation code.

  All 122 compile.

• New regression test for include(). It covers:

  • no duplicate binop or builtins;
  • exclusive and inclusive wgScan together;
  • a helper listed after it already arrived as a dependency. This case caught a bug in my first version: that helper was emitted twice. It's fixed;
  • enable first;
  • the module compiling;
  • workgroupBytes.

• Simulated RDNA4: 84 of 84 tests pass. Lavapipe: everything passes except the existing 8-lane sort failures. The package test passes.

Note on localFinishCap

The computed reserve is smaller than 3,328 (2,316 bytes with subgroups, 3,084 without). The cap can therefore only grow, and only when the device's workgroup memory is what limits it, which none of the defaults hit. localFinishCap keeps 3,328 as its default for callers that don't pass a reserve.

---

Generated by Claude Code