all: document legacy //go:linkname for modules with ≥2,000 dependents

For #67401.

Change-Id: I3ae93042dffd0683b7e6d6225536ae667749515b
Reviewed-on: https://go-review.googlesource.com/c/go/+/587221
Reviewed-by: Cherry Mui <cherryyz@google.com>
Auto-Submit: Russ Cox <rsc@golang.org>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>

diff --git a/src/reflect/badlinkname.go b/src/reflect/badlinkname.go
index e05208ead7598da7db31148263eac2252d32bebb..e2e1d4abc93d5e22219292d4133737fa724cee10 100644 (file)
--- a/src/reflect/badlinkname.go
+++ b/src/reflect/badlinkname.go
@@ -17,9 +17,6 @@ import (
 // See go.dev/issue/67401
 // and go.dev/issue/67279.
 
-//go:linkname add
-//go:linkname typesByString
-
 // ifaceIndir reports whether t is stored indirectly in an interface value.
 // It is no longer used by this package and is here entirely for the
 // linkname uses.

diff --git a/src/reflect/type.go b/src/reflect/type.go
index 7789aa2f914e762327715f27feef0fbc3ec4479e..1c9260124f5301be8e2bc5fa47236b1a49d53c2d 100644 (file)
--- a/src/reflect/type.go
+++ b/src/reflect/type.go
@@ -935,6 +935,16 @@ func canRangeFunc2(t *abi.Type) bool {
 // record why the addition is safe, which is to say why the addition
 // does not cause x to advance to the very end of p's allocation
 // and therefore point incorrectly at the next block in memory.
+//
+// add should be an internal detail (and is trivially copyable),
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/vmware/govmomi
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname add
 func add(p unsafe.Pointer, x uintptr, whySafe string) unsafe.Pointer {
        return unsafe.Pointer(uintptr(p) + x)
 }
@@ -1649,6 +1659,16 @@ func rtypeOff(section unsafe.Pointer, off int32) *abi.Type {
 // the given string representation.
 // It may be empty (no known types with that string) or may have
 // multiple elements (multiple types with that string).
+//
+// typesByString should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/aristanetworks/goarista
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname typesByString
 func typesByString(s string) []*abi.Type {
        sections, offset := typelinks()
        var ret []*abi.Type

diff --git a/src/runtime/alg.go b/src/runtime/alg.go
index 9469681572f3cb8e4814f679fca54ba05f4608ac..4886db944c7666728742fae25408c8a86952c4d0 100644 (file)
--- a/src/runtime/alg.go
+++ b/src/runtime/alg.go
@@ -63,6 +63,7 @@ func memhash64(p unsafe.Pointer, h uintptr) uintptr
 // strhash should be an internal detail,
 // but widely used packages access it using linkname.
 // Notable members of the hall of shame include:
+//   - github.com/aristanetworks/goarista
 //   - github.com/bytedance/sonic
 //
 // Do not remove or change the type signature.
@@ -136,6 +137,15 @@ func interhash(p unsafe.Pointer, h uintptr) uintptr {
        }
 }
 
+// nilinterhash should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/aristanetworks/goarista
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname nilinterhash
 func nilinterhash(p unsafe.Pointer, h uintptr) uintptr {
        a := (*eface)(p)
        t := a._type

diff --git a/src/runtime/badlinkname.go b/src/runtime/badlinkname.go
index 4d99ef48b6a9f7d2309cdb228a63aaaa7d34e204..47ebbad9a430b2607e18e1dff7b3f3252a51f688 100644 (file)
--- a/src/runtime/badlinkname.go
+++ b/src/runtime/badlinkname.go
@@ -27,8 +27,6 @@ import _ "unsafe"
 //go:linkname gopark
 //go:linkname goready
 //go:linkname goyield
-//go:linkname nilinterhash
-//go:linkname noescape
 //go:linkname procPin
 //go:linkname procUnpin
 //go:linkname sched

diff --git a/src/runtime/cgo.go b/src/runtime/cgo.go
index 40c8c748d3e56ed5c1b2fb0d6c2f2fb200e55827..8285d87fcf673b0357ea61958a55d15ee08a79b4 100644 (file)
--- a/src/runtime/cgo.go
+++ b/src/runtime/cgo.go
@@ -35,9 +35,28 @@ var (
 )
 
 // iscgo is set to true by the runtime/cgo package
+//
+// iscgo should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/ebitengine/purego
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname iscgo
 var iscgo bool
 
 // set_crosscall2 is set by the runtime/cgo package
+// set_crosscall2 should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/ebitengine/purego
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname set_crosscall2
 var set_crosscall2 func()
 
 // cgoHasExtraM is set on startup when an extra M is created for cgo.

diff --git a/src/runtime/cgocall.go b/src/runtime/cgocall.go
index 071643614bd8ebcae3444e24c80924fe81ff02be..b943b1c2d6b4f84a2c11e5e101c692d1f0d8cb43 100644 (file)
--- a/src/runtime/cgocall.go
+++ b/src/runtime/cgocall.go
@@ -121,6 +121,15 @@ var ncgocall uint64 // number of cgo calls in total for dead m
 // platforms. Syscalls may have untyped arguments on the stack, so
 // it's not safe to grow or scan the stack.
 //
+// cgocall should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/ebitengine/purego
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname cgocall
 //go:nosplit
 func cgocall(fn, arg unsafe.Pointer) int32 {
        if !iscgo && GOOS != "solaris" && GOOS != "illumos" && GOOS != "windows" {

diff --git a/src/runtime/env_posix.go b/src/runtime/env_posix.go
index 0eb4f0d7a3b8b25c3201d66376ed7f5564ee5456..323ce7de9a0fc048177a1c047c650c0b5cfced68 100644 (file)
--- a/src/runtime/env_posix.go
+++ b/src/runtime/env_posix.go
@@ -42,7 +42,26 @@ func lowerASCII(c byte) byte {
        return c
 }
 
-var _cgo_setenv unsafe.Pointer   // pointer to C function
+// _cgo_setenv should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/ebitengine/purego
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname _cgo_setenv
+var _cgo_setenv unsafe.Pointer // pointer to C function
+
+// _cgo_unsetenv should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/ebitengine/purego
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname _cgo_unsetenv
 var _cgo_unsetenv unsafe.Pointer // pointer to C function
 
 // Update the C environment if cgo is loaded.

diff --git a/src/runtime/linkname.go b/src/runtime/linkname.go
index f5f62cb54af209742af55e8cadce841d77fcc776..42d8d245a61565c58bdd27f5247bdeff4d276181 100644 (file)
--- a/src/runtime/linkname.go
+++ b/src/runtime/linkname.go
@@ -13,7 +13,6 @@ import _ "unsafe"
 //go:linkname goarm
 
 // used by cgo
-//go:linkname cgocall
 //go:linkname _cgo_panic_internal
 //go:linkname cgoAlwaysFalse
 //go:linkname cgoUse

diff --git a/src/runtime/malloc.go b/src/runtime/malloc.go
index 5820ac8594abedf370734202eb2333bd474b14f6..097946df66f71f0bb4669295baa529e31b6b49e1 100644 (file)
--- a/src/runtime/malloc.go
+++ b/src/runtime/malloc.go
@@ -971,6 +971,7 @@ func (c *mcache) nextFree(spc spanClass) (v gclinkptr, s *mspan, shouldhelpgc bo
 // Notable members of the hall of shame include:
 //   - github.com/bytedance/sonic
 //   - github.com/ugorji/go/codec
+//   - github.com/cockroachdb/pebble
 //
 // Do not remove or change the type signature.
 // See go.dev/issue/67401.
@@ -1429,6 +1430,7 @@ func newarray(typ *_type, n int) unsafe.Pointer {
 //   - github.com/bytedance/sonic
 //   - github.com/goccy/json
 //   - github.com/modern-go/reflect2
+//   - github.com/segmentio/kafka-go
 //
 // Do not remove or change the type signature.
 // See go.dev/issue/67401.

diff --git a/src/runtime/panic.go b/src/runtime/panic.go
index e182b0b733c1d18048232333b6f262c62241c4b9..433b54675abf659cb1e0c39b7a84c9336d824a0a 100644 (file)
--- a/src/runtime/panic.go
+++ b/src/runtime/panic.go
@@ -1031,6 +1031,7 @@ func sync_fatal(s string) {
 // but widely used packages access it using linkname.
 // Notable members of the hall of shame include:
 //   - github.com/bytedance/sonic
+//   - github.com/cockroachdb/pebble
 //   - github.com/dgraph-io/ristretto
 //
 // Do not remove or change the type signature.

diff --git a/src/runtime/runtime.go b/src/runtime/runtime.go
index 9b3ca719ea8cd4f5a123e211ff9f366a3f584e3d..e8e614815d236bacfd6d9d302854529216097820 100644 (file)
--- a/src/runtime/runtime.go
+++ b/src/runtime/runtime.go
@@ -300,6 +300,14 @@ var auxv []uintptr
 // Do not remove or change the type signature.
 // (See go.dev/issue/57336.)
 //
+// getAuxv should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/cilium/ebpf
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
 //go:linkname getAuxv
 func getAuxv() []uintptr { return auxv }
 

diff --git a/src/runtime/runtime1.go b/src/runtime/runtime1.go
index 7eeddfdf2c671e66e96e6afca77a64657810aa8b..378f0d8ea3bcc17319307163b2b081c2b8f6331b 100644 (file)
--- a/src/runtime/runtime1.go
+++ b/src/runtime/runtime1.go
@@ -619,6 +619,7 @@ func releasem(mp *m) {
 // Notable members of the hall of shame include:
 //   - github.com/goccy/json
 //   - github.com/modern-go/reflect2
+//   - github.com/vmware/govmomi
 //
 // Do not remove or change the type signature.
 // See go.dev/issue/67401.

diff --git a/src/runtime/stubs.go b/src/runtime/stubs.go
index 96f333bc0fe2aabb27d780f02b2a8b94802d3808..7ec24d30e4c74b5eb6d44dc5eb994e9272b195e6 100644 (file)
--- a/src/runtime/stubs.go
+++ b/src/runtime/stubs.go
@@ -120,6 +120,7 @@ func reflect_memclrNoHeapPointers(ptr unsafe.Pointer, n uintptr) {
 // Notable members of the hall of shame include:
 //   - github.com/bytedance/sonic
 //   - github.com/ugorji/go/codec
+//   - github.com/ebitengine/purego
 //
 // Do not remove or change the type signature.
 // See go.dev/issue/67401.
@@ -156,6 +157,15 @@ func memequal(a, b unsafe.Pointer, size uintptr) bool
 // compiles down to zero instructions.
 // USE CAREFULLY!
 //
+// noescape should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/ebitengine/purego
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname noescape
 //go:nosplit
 func noescape(p unsafe.Pointer) unsafe.Pointer {
        x := uintptr(p)

diff --git a/src/runtime/time_nofake.go b/src/runtime/time_nofake.go
index c7800c34e3a526242ac7134c3ef9ae0a99a9f24d..e455f64b9f8eba837f719034a1f9e625e4d67a17 100644 (file)
--- a/src/runtime/time_nofake.go
+++ b/src/runtime/time_nofake.go
@@ -14,7 +14,9 @@ import "unsafe"
 // Zero means not to use faketime.
 var faketime int64
 
-// Many external packages linkname nanotime to get a fast monotonic time.
+// Exported via linkname for use by time and internal/poll.
+//
+// Many external packages also linkname nanotime for a fast monotonic time.
 // Such code should be updated to use:
 //
 //     var start = time.Now() // at init time