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

For #67401.


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

src/go/build/badlinkname.go

@@ -12,9 +12,6 @@ import _ "unsafe"
 // This may change in the future. Please do not depend on them
 // in new code.
 
-//go:linkname defaultReleaseTags
-//go:linkname defaultToolTags
-
 // The compiler doesn't allow linknames on methods, for good reasons.
 // We use this trick to push linknames of the methods.
 // Do not call them in this package.

src/go/build/build.go

@@ -29,6 +29,7 @@ import (
 	"strings"
 	"unicode"
 	"unicode/utf8"
+	_ "unsafe" // for linkname
 )
 
 // A Context specifies the supporting context for a build.
@@ -306,7 +307,27 @@ func defaultGOPATH() string {
 	return ""
 }
 
-var defaultToolTags, defaultReleaseTags []string
+// defaultToolTags should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/gopherjs/gopherjs
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname defaultToolTags
+var defaultToolTags []string
+
+// defaultReleaseTags should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/gopherjs/gopherjs
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname defaultReleaseTags
+var defaultReleaseTags []string
 
 func defaultContext() Context {
 	var c Context

src/internal/poll/badlinkname.go

@@ -1,15 +0,0 @@
-// Copyright 2024 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 poll
-
-import _ "unsafe"
-
-// As of Go 1.22, the symbols below are found to be pulled via
-// linkname in the wild. We provide a push linkname here, to
-// keep them accessible with pull linknames.
-// This may change in the future. Please do not depend on them
-// in new code.
-
-//go:linkname IsPollDescriptor

src/internal/poll/fd_poll_runtime.go

@@ -164,6 +164,16 @@ func setDeadlineImpl(fd *FD, t time.Time, mode int) error {
 
 // IsPollDescriptor reports whether fd is the descriptor being used by the poller.
 // This is only used for testing.
+//
+// IsPollDescriptor should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/opencontainers/runc
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname IsPollDescriptor
 func IsPollDescriptor(fd uintptr) bool {
 	return runtime_isPollServerDescriptor(fd)
 }

src/runtime/alg.go

@@ -45,7 +45,18 @@ func memhash_varlen(p unsafe.Pointer, h uintptr) uintptr {
 var useAeshash bool
 
 // in asm_*.s
+
+// memhash should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/dgraph-io/ristretto
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname memhash
 func memhash(p unsafe.Pointer, h, s uintptr) uintptr
+
 func memhash32(p unsafe.Pointer, h uintptr) uintptr
 func memhash64(p unsafe.Pointer, h uintptr) uintptr
 

src/runtime/badlinkname.go

@@ -12,11 +12,15 @@ import _ "unsafe"
 // This may change in the future. Please do not depend on them
 // in new code.
 
+// These should be an internal details
+// but widely used packages access them using linkname.
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+
 //go:linkname add
 //go:linkname atomicwb
 //go:linkname callers
 //go:linkname chanbuf
-//go:linkname cputicks
 //go:linkname entersyscallblock
 //go:linkname fastexprand
 //go:linkname gopanic
@@ -35,3 +39,7 @@ import _ "unsafe"
 //go:linkname typedslicecopy
 //go:linkname typehash
 //go:linkname wakep
+
+// Notable members of the hall of shame include:
+//   - github.com/dgraph-io/ristretto
+//go:linkname cputicks

src/runtime/panic.go

@@ -1038,6 +1038,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/dgraph-io/ristretto
 //
 // Do not remove or change the type signature.
 // See go.dev/issue/67401.

src/runtime/stubs.go

@@ -87,6 +87,7 @@ func badsystemstack() {
 // but widely used packages access it using linkname.
 // Notable members of the hall of shame include:
 //   - github.com/bytedance/sonic
+//   - github.com/dgraph-io/ristretto
 //
 // Do not remove or change the type signature.
 // See go.dev/issue/67401.

src/syscall/rlimit.go

@@ -8,9 +8,20 @@ package syscall
 
 import (
 	"sync/atomic"
+	_ "unsafe"
 )
 
 // origRlimitNofile, if non-nil, is the original soft RLIMIT_NOFILE.
+//
+// origRlimitNofile should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/opencontainers/runc
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname origRlimitNofile
 var origRlimitNofile atomic.Pointer[Rlimit]
 
 // Some systems set an artificially low soft limit on open file count, for compatibility