internal/goexperiment,cmd: consolidate GOEXPERIMENTs into a new package

Currently there's knowledge about the list of GOEXPERIMENTs in a few
different places. This CL introduces a new package and consolidates
the list into one place: the internal/goexperiment.Flags struct type.

This package gives us a central place to document the experiments as
well as the GOEXPERIMENT environment variable itself. It will also
give us a place to put built-time constants derived from the enabled
experiments.

Now the objabi package constructs experiment names by reflecting over
this struct type rather than having a separate list of these names
(this is similar to how the compiler handles command-line flags and
debug options). We also expose a better-typed API to the toolchain for
propagating enabled experiments.

Change-Id: I06e026712b59fe2bd7cd11a869aedb48ffe5a4b7
Reviewed-on: https://go-review.googlesource.com/c/go/+/307817
Trust: Austin Clements <austin@google.com>
Run-TryBot: Austin Clements <austin@google.com>
TryBot-Result: Go Bot <gobot@golang.org>
Reviewed-by: Matthew Dempsky <mdempsky@google.com>

1 files changed, 72 insertions, 0 deletions

diff --git a/src/internal/goexperiment/flags.go b/src/internal/goexperiment/flags.go
new file mode 100644
index 0000000000..46800b4e0f
--- /dev/null
+++ b/src/internal/goexperiment/flags.go
@@ -0,0 +1,72 @@
+// Copyright 2021 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// Package goexperiment implements support for toolchain experiments.
+//
+// Toolchain experiments are controlled by the GOEXPERIMENT
+// environment variable. GOEXPERIMENT is a comma-separated list of
+// experiment names. GOEXPERIMENT can be set at make.bash time, which
+// sets the default experiments for binaries built with the tool
+// chain; or it can be set at build time. GOEXPERIMENT can also be set
+// to "none", which disables any experiments that were enabled at
+// make.bash time.
+//
+// Experiments are exposed to the build in the following ways:
+//
+// - Build tag goexperiment.x is set if experiment x (lower case) is
+// enabled.
+//
+// - In runtime assembly, the macro GOEXPERIMENT_x is defined if
+// experiment x (lower case) is enabled.
+//
+// - TODO(austin): More to come.
+//
+// In the toolchain, the set of experiments enabled for the current
+// build should be accessed via objabi.Experiment.
+//
+// For the set of experiments supported by the current toolchain, see
+// go doc internal/experiment.Flags.
+package goexperiment
+
+// Flags is the set of experiments that can be enabled or disabled in
+// the current toolchain.
+//
+// When specified in the GOEXPERIMENT environment variable or as build
+// tags, experiments use the strings.ToLower of their field name.
+type Flags struct {
+	FieldTrack        bool
+	PreemptibleLoops  bool
+	StaticLockRanking bool
+
+	// Regabi is split into several sub-experiments that can be
+	// enabled individually. GOEXPERIMENT=regabi implies the
+	// subset that are currently "working". Not all combinations work.
+	Regabi bool
+	// RegabiWrappers enables ABI wrappers for calling between
+	// ABI0 and ABIInternal functions. Without this, the ABIs are
+	// assumed to be identical so cross-ABI calls are direct.
+	RegabiWrappers bool
+	// RegabiG enables dedicated G and zero registers in
+	// ABIInternal.
+	//
+	// Requires wrappers because it makes the ABIs incompatible.
+	RegabiG bool
+	// RegabiReflect enables the register-passing paths in
+	// reflection calls. This is also gated by intArgRegs in
+	// reflect and runtime (which are disabled by default) so it
+	// can be used in targeted tests.
+	RegabiReflect bool
+	// RegabiDefer enables desugaring defer and go calls
+	// into argument-less closures.
+	RegabiDefer bool
+	// RegabiArgs enables register arguments/results in all
+	// compiled Go functions.
+	//
+	// Requires wrappers (to do ABI translation), g (because
+	// runtime assembly that's been ported to ABIInternal uses the
+	// G register), reflect (so reflection calls use registers),
+	// and defer (because the runtime doesn't support passing
+	// register arguments to defer/go).
+	RegabiArgs bool
+}