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>

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.

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

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

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

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.

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" {

src/runtime/env_posix.go

@@ -42,7 +42,26 @@ func lowerASCII(c byte) byte {
 	return c
 }
 
+// _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.

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

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.

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.

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 }
 

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.

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)

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