Skip to content

simd/archsimd: clean up "emulated" doc comments #81568

Description

@aclements

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) Mask8x16

There are several things that could be better about this:

  1. 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.
  2. 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.
  3. 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:

  1. 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.
  2. 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.
  3. 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.

Activity

  1. added theissue type on Sep 16, 2026
  2. gabyhelp commented on Sep 16, 2026

    @gabyhelp

    Related Code Changes

    Related Discussions

    (Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)

  3. added
    NeedsFixThe path to resolution is known, but the work has not been done.
    on Sep 18, 2026
  4. added this to the Go1.28 milestone on Sep 18, 2026
  5. arfa79 commented on Sep 30, 2026

    @arfa79

    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 as x.Less(y) = y.Greater(x) still be labeled Emulated: Greater, or use a different implementation note?

  6. gopherbot commented on Oct 3, 2026

    @gopherbot
    Contributor

    Change https://go.dev/cl/844365 mentions this issue: simd/archsimd: document emulation dependencies

  7. dr2chase commented on Oct 3, 2026

    @dr2chase
    Contributor

    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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    NeedsFixThe path to resolution is known, but the work has not been done.compiler/runtimeIssues related to the Go compiler and/or runtime.

    Type

    Projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions