Repository navigation
simd/archsimd: clean up "emulated" doc comments #81568
Copy link
Copy link
Labels
NeedsFixThe path to resolution is known, but the work has not been done.The path to resolution is known, but the work has not been done.compiler/runtimeIssues related to the Go compiler and/or runtime.Issues related to the Go compiler and/or runtime.
Milestone
Description
Today, we have various operations in archsimd marked "Emulated" as such:
// GreaterEqual returns a mask whose elements indicate whether x >= y.
//
// Emulated, CPU Feature: AVX
func (x Int8x16) GreaterEqual(y Int8x16) Mask8x16There are several things that could be better about this:
- It doesn't follow the same convention as other implementation notes, which (almost) all start with "Keyword:", like "Asm:", "CPU Feature:", or a few others. I'm in the process of building the tooling to combine semantics-level doc comments from spec with implementation-level doc comments like this and the inconsistency makes this messy.
- It's not very informative. We don't do an emulation if it would be expensive, but you might care whether it's emulated with 2 instructions or 10.
- Sometimes we mark operations as emulated that are literally a single operation. For example, x.Less(y) is "emulated" as y.Greater(x). That means we don't have an "Asm:" block, but is this really an "emulation"?
I spent a while exploring solutions, but reached my time-box. A few options:
- Assume that, if a user cares, they'll just look at the body to see how it's emulated. It would be nice to fit the "Keyword:" convention, but it's really just a flag.
- List the methods it's defined in terms of, like "Emulated: Xor, Greater", excluding no-op conversions. This stays pretty high-level, which is nice, and gives a direct sense of the emulation complexity/cost. But it's surprisingly annoying to hand write: It can drift easily from the implementation if we're not careful; a bunch of these emulations are generated from complex, branchy-templates, which means doc comment needs the same template branches; and emulations are often written atop other emulations and ideally this would be the transitive closure, but that's even messier to maintain by hand. It's possible we could fully automate generating these comments with a little syntactic analysis.
- List the assembly operations it's defined in terms of, akin to the current "Asm:" comments. Most detailed, but basically impossible to write or maintain by hand. This also has the danger of giving actively wrong information if the compiler optimizes across the boundaries.
Reactions are currently unavailable
Metadata
Metadata
Assignees
Labels
NeedsFixThe path to resolution is known, but the work has not been done.The path to resolution is known, but the work has not been done.compiler/runtimeIssues related to the Go compiler and/or runtime.Issues related to the Go compiler and/or runtime.
Type
Projects
- StatusShow more project fieldsTodo
Activity
gabyhelp commentedon Sep 16, 2026
Related Code Changes
Related Discussions
(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)
arfa79 commentedon Sep 30, 2026
I’d like to work on this.
My initial approach would be to generate
Emulated: ...from the expanded Go implementation rather than maintain a second hand-written dependency list. I’d start with a small prototype that collects direct public SIMD operations, excludes no-op conversions/helpers, and verifies the generated comments stay synchronized with the implementation.Before proceeding, would you prefer direct dependencies, such as
Emulated: Greater, Not, or their transitive closure? Also, should single reversed operations such asx.Less(y) = y.Greater(x)still be labeledEmulated: Greater, or use a different implementation note?gopherbot commentedon Oct 3, 2026
Change https://go.dev/cl/844365 mentions this issue:
simd/archsimd: document emulation dependenciesdr2chase commentedon Oct 3, 2026
As mentioned elsewhere -- we need to wait on this, Austin has some automated project underway and this will probably generate conflicts with it. Sorry to not notice your earlier message and say something then.