Repository navigation
simd: unify API generation around executable spec #81819
Description
TL;DR: This is a tracking issue for transitioning the myriad SIMD API generators to build around a single, shared, executable API specification to ensure API consistency.
The central rule of the SIMD project is "one name means one thing": a given function or method need not exist on across all SIMD packages or platforms, but wherever it does exist, it must denote the same operation, with the same signature and the same semantics.
However, nothing currently enforces this. The closest thing we have is the apisum tool, which audits after the fact and requires human review of the audit. The original intent was that the simdgen tool would be the sole API generator, and that simdgen's categories.yaml files would enforce consistency, but this has proven flawed in three ways: 1. simdgen is not a good approach for some API generation, so we now have several other generators and they have no idea how to read the unifier dialect that categories.yaml is in; 2. categories.yaml only enforces consistency of API names and documentation, not types or argument names; 3. since categories.yaml is just another unifier input, nothing prevents architecture-specific information from leaking into it or architecture-independent information from leaking out of it.
Hence, I've been working on a new approach based on an executable API specification. This specification is hand-written in Go, but in a particular style that lets it compress the repetition across types, while being easy to map to the SIMD API. For example, there's a single description of the Add method that gets expanded to all of the SIMD types. This single API description provides: 1) the name of the operation, 2) the argument/result names and types, 3) the doc comment, and 4) a pure Go implementation that can be used as a conformance test. The spec is maximalist: it may describe operations on types that no platform actually implements today.
This API description will be parsed by an internal/specgen package with a lightweight API, so it can be used directly by all of the generators to ensure conformance.
The goals of this transition are to unify documentation across the SIMD API and to ensure semantic consistency.
Activity
gabyhelp commentedon Sep 28, 2026
Related Issues
Related Code Changes
(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)
gopherbot commentedon Sep 28, 2026
Change https://go.dev/cl/838629 mentions this issue:
simd/archsimd/{_gen/specdoc,cmd/specfill}: reporting of major API mismatchesgopherbot commentedon Sep 28, 2026
Change https://go.dev/cl/838626 mentions this issue:
simd/archsimd/_gen/specgen: add doc comment classification and handlinggopherbot commentedon Sep 28, 2026
Change https://go.dev/cl/832924 mentions this issue:
simd/archsimd/_gen: plan for transitioning to specgopherbot commentedon Sep 28, 2026
Change https://go.dev/cl/838627 mentions this issue:
simd/archsimd/_gen/specgen: add a (receiver, name) indexgopherbot commentedon Sep 28, 2026
Change https://go.dev/cl/835527 mentions this issue:
simd/archsimd/_gen: mark doc-explore done in SPEC-TRANSITION.mdgopherbot commentedon Sep 28, 2026
Change https://go.dev/cl/835525 mentions this issue:
simd/internal/spec: implement all of ops/AddSubgopherbot commentedon Sep 28, 2026
Change https://go.dev/cl/840445 mentions this issue:
simd/archsimd/_gen: complete taskspecfill``gopherbot commentedon Sep 28, 2026
Change https://go.dev/cl/835526 mentions this issue:
simd/internal/spec: add ShiftSaturated, ShiftAllRight, and ShiftRightgopherbot commentedon Sep 28, 2026
Change https://go.dev/cl/838628 mentions this issue:
simd/archsimd/_gen/specexpr: generalize signature formatting56 remaining items
gopherbot commentedon Oct 8, 2026
Change https://go.dev/cl/847730 mentions this issue:
simd/archsimd/_gen/cmd/specfill: accept files on command linegopherbot commentedon Oct 8, 2026
Change https://go.dev/cl/847728 mentions this issue:
simd/internal/spec: implement all common operationsgopherbot commentedon Oct 8, 2026
Change https://go.dev/cl/847733 mentions this issue:
simd/archsimd/_gen: complete taskcomments-yaml``gopherbot commentedon Oct 8, 2026
Change https://go.dev/cl/847731 mentions this issue:
simd/archsimd/_gen/midway: drop spec-covered docs from comments.yamlgopherbot commentedon Oct 9, 2026
Change https://go.dev/cl/848165 mentions this issue:
simd/archsimd: naming cleanups in wasmsimd/internal/spec: make scalable width adjustable, complete task `wi…
simd/archsimd/_gen/cmd/specstats: exclude ToArch/FromArch
simd: fix argument/receiver names that vary between platforms
simd/archsimd: naming cleanups in wasm
simd/internal/spec: implement all common operations
simd/archsimd/_gen: complete task `simd-common`
simd/archsimd/_gen/cmd/specfill: accept files on command line
simd/archsimd/_gen/midway: drop spec-covered docs from comments.yaml
simd: rewrite simd_emulated.go docs from spec
simd/archsimd/_gen: complete task `comments-yaml`