doc/go1.18: clarify when/why to set GOAMD64 architecture values

[kevinburkesegment]

Reading the Go 1.18 release notes, there are sort of two naive models that you could have about this:

Go 1.18 introduces the new GOAMD64 environment variable, which selects a mininum target version of the AMD64 architecture. Allowed values are v1, v2, v3, or v4. Each higher level requires, and takes advantage of, additional processor features. A detailed description can be found here.

The GOAMD64 environment variable defaults to v1.

Model 1: Setting these variables at compile time means Go will replace the worse CPU instructions with the better CPU instructions in the generated binary.

Model 2: Both instructions are compiled into the binary, and at runtime Go will read the GOAMD64 environment variable and use the better CPU instructions instead of the worse CPU instructions, if they are available.

I would guess that Model 1 is what you are going for. But that's also a little confusing to me because I believe that the compiler does CPU feature detection already to determine which instructions are supported, at least I think I've seen commits to that effect. So reading the documentation, I am confused why we now need an environment variable. My colleague also tried to read through the code to figure out where Go was using any of the new CPU instructions and couldn't find anything.

I think the doc could benefit from another sentence or two explaining a bit more context about why this is necessary now, or linking to more information.

[ALTree]

Scenario II is ruled out by the word requires in the sentence

Each higher level requires, and takes advantage of, additional processor features.

If GOAMD64=V3 binaries had runtime detection and a fallback to V1 instructions, you wouldn't say that each level requires the processor to support newer instructions. So yes, scenario I is the correct interpretation.

Regarding why a compile time variable is needed: runtime detection and selection of the supported instruction is expensive, and sometimes negates the speed advantage that using newer AMD64 instructions would bring. Setting V3 instructs the compiler to assume, instead of it having to detect and switch between 2 code paths. The release notes link to https://github.com/golang/go/wiki/MinimumRequirements#microarchitecture-support, which somewhat explain this.

How would you suggest changing the release notes (or the linked wiki section) to clarify this?

[ianlancetaylor]

CC @randall77

[ALTree]

Side note:

tried to read through the code to figure out where Go was using any of the new CPU instructions and couldn't find anything.

Take:

package p

import "encoding/binary"

var sink uint64

func f(b []byte) {
	sink = binary.BigEndian.Uint64(b)
}

GOAMD64=v1:

0x0019 00025 ($GOROOT/src/encoding/binary/binary.go:127)	MOVQ	(AX), AX
0x001c 00028 ($GOROOT/src/encoding/binary/binary.go:127)	BSWAPQ	AX

GOAMD64=v3:

0x0019 00025 ($GOROOT/src/encoding/binary/binary.go:127)	MOVBEQ	(AX), AX

[randall77]

@ALTree is correct. If we had only runtime detection (which was the case up through 1.17), then GOAMD64 would not be needed.

Maybe "at compile time" would be a good thing to add to the release notes? It at least clarifies that this isn't a runtime thing. I think users of other platforms are very familiar with the subarch selector, but for amd64-only people this is something new.

For code that uses it, look for GOAMD64 in src/cmd/compile/internal/ssagen/ssa.go.

[kevinburkesegment]

How would you suggest changing the release notes (or the linked wiki section) to clarify this?

How about

Go 1.18 introduces the new GOAMD64 environment variable, which selects a mininum target version of the AMD64 architecture. Allowed values are v1, v2, v3, or v4. Each higher level requires, and takes advantage of, additional processor features. While Go can detect supported CPU instruction sets implicitly, setting an environment variable allows the compiler to make faster decisions about which instruction sets should be used. A detailed description can be found here.

The GOAMD64 environment variable defaults to v1.

I guess another question is are there any plans to release Go binaries that are compiled with different levels of optimization? Presumably these could lead to speedups in compile times as well?

[randall77]

We have no plans to compile any distributions with GOAMD64>v1.

[gopherbot]

Change https://golang.org/cl/378179 mentions this issue: doc: mention that GOAMD64 is a compile-time setting