runtime: document (and support) cpu options in GODEBUG #27218
Remove the experimental status of the debugcpu experiment feature in go1.12 and document the use of the environment variable
Example invocation of go test with GODEBUGCPU:
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
Currently all CPU features that are supported on the current CPU executing the Go binary may be used.
Compiling go1.11 with
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
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
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
The general syntax to mask a CPU feature and to change the corresponding internal/cpu feature variables is
An internal/cpu feature variables will never be set to
The special option name
Changing a list of option names including the option
An example of setting
Only enabling sse3 if it is supported and required CPU features can be done with:
Alternative Option Values
Optional Debug mode
Optionally the debugcpu feature may be released together with support for
changed the title
proposal: officially support changing of cpu feature usage through internal/cpu
Sep 19, 2018
Sounds good to me. A few nits:
I'm not sure what you mean by this. It would make sense to me if
What if the user tries to turn off a feature that is a minimum requirement? I worry it would surprise users if their request was silently ignored. But there also aren't any error cases in the current proposal, and you do specify that requests to turn on unavailable features are silently ignored.
I'm definitely not saying "=off" should be implicit. :) I'm saying the opposite: that the "=value" part should be required, even for the "all" key.
My objection was to saying "all" without an "=value" part. I just wasn't clear on whether the proposal was proposing that. I think the "=value" should be required in all cases.
My intention with "The general syntax to mask a CPU feature and to change the corresponding internal/cpu feature variables is option=value" was to require =value. I will modify the proposal text to make this explicit.
As for silently ignoring errors: Would it be ok for the runtime to log a message to stderr for each option request (on or off) that can not be fullfilled due to missing cpu support or minimum go requirements?
That's a good question. I'm inclined to say that yes, it should log to stderr. While the runtime generally doesn't log anything except when it's crashing, there are several other GODEBUG variables that do enable logging to stderr. So it seems okay to me for GODEBUGCPU to do so as well.