New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

runtime: document (and support) cpu options in GODEBUG #27218

Open
martisch opened this Issue Aug 25, 2018 · 17 comments

Comments

Projects
None yet
7 participants
@martisch
Member

martisch commented Aug 25, 2018

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.

@gopherbot gopherbot added this to the Proposal milestone Aug 25, 2018

@gopherbot gopherbot added the Proposal label Aug 25, 2018

@martisch

This comment has been minimized.

Member

martisch commented Aug 25, 2018

@randall77

This comment has been minimized.

Contributor

randall77 commented Aug 25, 2018

It might be nice to support on as well, so you can do GODEBUGCPU=all=off,sse2=on.

@martisch

This comment has been minimized.

Member

martisch commented Aug 25, 2018

@randall77 makes sense. Added that on should be supported in the initial version of GODEBUGCPU too.

@rsc

This comment has been minimized.

Contributor

rsc commented Sep 19, 2018

Ping @aclements, @randall77 for decision.

@rsc rsc changed the title from proposal: officially support changing of cpu feature usage through internal/cpu to proposal: runtime: document (and support) GODEBUGCPU Sep 19, 2018

@randall77

This comment has been minimized.

Contributor

randall77 commented Sep 19, 2018

Sounds fine to me. GODEBUGCPU is a good name.

@aclements

This comment has been minimized.

Member

aclements commented Sep 20, 2018

Sounds good to me. A few nits:

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.

I'm not sure what you mean by this. It would make sense to me if all was itself a feature name that aliased with all features, so you can say GODEBUGCPU=all=off (like in your later example). But as written, this sounds like GODEBUGCPU=all turns off all features, which would seem counter-intuitive and probably not what you intended.

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.

@rsc

This comment has been minimized.

Contributor

rsc commented Oct 3, 2018

@aclements are you saying that GODEBUGCPU=foo means implicitly foo=off? Perhaps that should change to require a =value?

@rsc

This comment has been minimized.

Contributor

rsc commented Oct 3, 2018

Proposal accepted pending @aclements and @randall77 working through details.

@rsc rsc changed the title from proposal: runtime: document (and support) GODEBUGCPU to runtime: document (and support) GODEBUGCPU Oct 3, 2018

@bradfitz bradfitz modified the milestones: Proposal, Go1.12 Oct 3, 2018

@aclements

This comment has been minimized.

Member

aclements commented Oct 3, 2018

@aclements are you saying that GODEBUGCPU=foo means implicitly foo=off? Perhaps that should change to require a =value?

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.

@martisch

This comment has been minimized.

Member

martisch commented Oct 3, 2018

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?

@aclements

This comment has been minimized.

Member

aclements commented Oct 3, 2018

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.

@gopherbot

This comment has been minimized.

gopherbot commented Oct 12, 2018

Change https://golang.org/cl/141817 mentions this issue: internal/cpu: enable support for GODEBUGCPU in non-experimental builds

gopherbot pushed a commit that referenced this issue Oct 12, 2018

internal/cpu: enable support for GODEBUGCPU in non-experimental builds
Enabling GODEBUGCPU without the need to set GOEXPERIMENT=debugcpu  enables
trybots and builders to run tests for GODEBUGCPU features in upcoming CLs
that will implement the new syntax and features for non-experimental
GODEBUGCPU support from proposal golang.org/issue/27218.

Updates #27218

Change-Id: Icc69e51e736711a86b02b46bd441ffc28423beba
Reviewed-on: https://go-review.googlesource.com/c/141817
Run-TryBot: Martin Möhrmann <moehrmann@google.com>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
@gopherbot

This comment has been minimized.

gopherbot commented Oct 12, 2018

Change https://golang.org/cl/141818 mentions this issue: internal/cpu: use 'off' for disabling cpu capabilities instead of '0'

gopherbot pushed a commit that referenced this issue Oct 12, 2018

internal/cpu: use 'off' for disabling cpu capabilities instead of '0'
Updates #27218

Change-Id: I4ce20376fd601b5f958d79014af7eaf89e9de613
Reviewed-on: https://go-review.googlesource.com/c/141818
Run-TryBot: Martin Möhrmann <moehrmann@google.com>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
@gopherbot

This comment has been minimized.

gopherbot commented Oct 12, 2018

Change https://golang.org/cl/141800 mentions this issue: internal/cpu: add invalid option warnings and support to enable cpu features

gopherbot pushed a commit that referenced this issue Oct 15, 2018

internal/cpu: add invalid option warnings and support to enable cpu f…
…eatures

This CL adds the ability to enable the cpu feature FEATURE by specifying
FEATURE=on in GODEBUGCPU. Syntax support to enable cpu features is useful
in combination with a preceeding all=off to disable all but some specific
cpu features. Example:

GODEBUGCPU=all=off,sse3=on

This CL implements printing of warnings for invalid GODEBUGCPU settings:
- requests enabling features that are not supported with the current CPU
- specifying values different than 'on' or 'off' for a feature
- settings for unkown cpu feature names

Updates #27218

Change-Id: Ic13e5c4c35426a390c50eaa4bd2a408ef2ee21be
Reviewed-on: https://go-review.googlesource.com/c/141800
Run-TryBot: Martin Möhrmann <moehrmann@google.com>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Keith Randall <khr@golang.org>
@gopherbot

This comment has been minimized.

gopherbot commented Oct 23, 2018

Change https://golang.org/cl/144107 mentions this issue: internal/cpu: add options and warnings for required cpu features

gopherbot pushed a commit that referenced this issue Oct 24, 2018

internal/cpu: add options and warnings for required cpu features
Updates #27218

Change-Id: I8603f3a639cdd9ee201c4f1566692e5b88877fc4
Reviewed-on: https://go-review.googlesource.com/c/144107
Run-TryBot: Martin Möhrmann <martisch@uos.de>
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
@gopherbot

This comment has been minimized.

gopherbot commented Oct 28, 2018

Change https://golang.org/cl/145281 mentions this issue: runtime: support GODEBUGCPU for more Unix-like operating systems

gopherbot pushed a commit that referenced this issue Oct 28, 2018

runtime: support GODEBUGCPU for more Unix-like operating systems
Adds AIX, DragonFly BSD, FreeBSD, NetBSD, OpenBSD and Solaris
to the list of operating systems where the GODEBUGCPU environment
variable will be parsed and interal/cpu features can be enabled
and disabled.

Updates #27218

Change-Id: I9cd99142e2a5147cb00ca57b581f049ea6ce8508
Reviewed-on: https://go-review.googlesource.com/c/145281
Reviewed-by: Brad Fitzpatrick <bradfitz@golang.org>
Run-TryBot: Martin Möhrmann <martisch@uos.de>
TryBot-Result: Gobot Gobot <gobot@golang.org>
@gopherbot

This comment has been minimized.

gopherbot commented Nov 14, 2018

Change https://golang.org/cl/149579 mentions this issue: all: document GODEBUG options to disable use of instruction set extensions

@martisch martisch changed the title from runtime: document (and support) GODEBUGCPU to runtime: document (and support) cpu options in GODEBUG Nov 22, 2018

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