Proposal

Remove the experimental status of the debugcpu experiment feature in go1.12 and document the use of the environment variable GODEBUGCPU as an official feature. This will allow for masking CPU features at Go program start for debugging, manual and buildbot testing, and benchmarking the use of different Go code paths that use internal/cpu CPU feature variables.

Example invocation of go test with GODEBUGCPU: GODEBUGCPU=sse3=off,sse2=off go test

Background

Go's CPU feature detection migration to use only the std lib package internal/cpu will be finished with go1.12. internal/cpu exports structs with bool variables that are used to guard the use of CPU instructions that are not guaranteed to be supported or are minimum requirements for the GOARCH the Go binary was compiled for.

Currently all CPU features that are supported on the current CPU executing the Go binary may be used.

Compiling go1.11 with GOEXPERIMENT=debugcpu enables an experiment to use the environment variable GODEBUGCPU to mask (disable) CPU features such that the corresponding CPU feature variable in internal/cpu is set to false even if the current CPU supports the feature. Therefore different code paths in the standard library and for code the compiler emits (e.g. POPCNT) that check for internal/cpu feature variables can be exercised.

Environment variable

An environment variable is chosen to easily mask CPU features for all go programs executed with a common environment, not interfere with any program arguments and because environment variable values are available early in the GO runtime's startup. Other low level runtime options such as GOMAXPROCS, GOGC and GOTRACEBACK are also modeled as environment variables.

The name GODEBUGCPU is chosen to signal that this feature is intended for debugging, performance analysis, experimentation and testing but could be easily changed to have another name if a more a more suitable one is found.

Option Syntax

For each architecture a set of CPU feature options with names matching CPU architecture documentation or the Linux kernel naming of that CPU feature is exposed. The same option name might be used by multiple CPU architectures. Only those CPU features can be changed that are not in the minimum requirements needed for the architecture to run Go programs. For example SSE2 instructions on amd64 are mandatory. All option names are to be lower case. Some CPU feature option names for amd64 are for example sse41 and popcnt.

To provide compatibility between different Go versions supporting different CPU features options a CPU feature option name that is not known is ignored. e.g. currently avx512 is not an option name.

The general syntax to mask a CPU feature and to change the corresponding internal/cpu feature variables is option=valuewhere option is the CPU feature option name such as sse2 and value will be restricted to only have a meaning for off and on in this proposal. Other values will be ignored. Note that the current experimental implementation in go1.11 only supports 0 instead of off and no on. Specifying options that are not followed by =value is not supported.

An internal/cpu feature variables will never be set to true if the corresponding CPU feature was not detected as present for the CPU executing the go binary. Setting a CPU feature option to on will therefore never enable the use of unsupported CPU features.

The special option name all is reserved to set all internal/cpu CPU feature variables to false that are not in the minimum requirements for the Go architecture.

Changing a list of option names including the option all is possible by concatenation of options with the separator,. Using the same option name multiple times is permitted and options specified last (to the right) take precedence over earlier (to the left) specified options.

An example of setting SSE3 and SSE2 support to false on GOARCH=386 for running tests could therefore look like:
GODEBUGCPU=sse3=off,sse2=off go test

Only enabling sse3 if it is supported and required CPU features can be done with:
GODEBUGCPU=all=off,sse3=on go test

Alternative Option Values

Instead of off the option value 0 (and 1 instead of on) could be considered instead to disable the use of specific CPU features.

Optional Debug mode

Optionally the debugcpu feature may be released together with support for GODEBUGCPU=debug,option=value,.... which makes the go program print a diagnostic to stderr of which CPU features were detected and which internal/cpu variables were altered based on the options given.

Misc Notes

• The x/sys/cpu package can be made to interpret GODEBUGCPU in the same way as internal/cpu. While this would be good for consistency this is not part of this proposal.
• Settings in GODEBUGCPU have no effect on the instructions compiled into the binary.
• Settings in GODEBUGCPU have no effect on code paths not guarded by internal/cpu feature variables.
• Settings in GODEBUGCPU will only be considered once on program startup. The proposal is not meant to allow changing the use of CPU features dynamically during the runtime after startup of the program.