all: document legacy //go:linkname for modules with ≥100 dependents

For #67401.

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

src/go/build/build.go

@@ -1626,6 +1626,15 @@ func (ctxt *Context) shouldBuild(content []byte, allTags map[string]bool) (shoul
 	return shouldBuild, sawBinaryOnly, nil
 }
 
+// parseFileHeader should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/bazelbuild/bazel-gazelle
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname parseFileHeader
 func parseFileHeader(content []byte) (trimmed, goBuild []byte, sawBinaryOnly bool, err error) {
 	end := 0
 	p := content

src/go/build/read.go

@@ -18,6 +18,7 @@ import (
 	"strings"
 	"unicode"
 	"unicode/utf8"
+	_ "unsafe" // for linkname
 )
 
 type importReader struct {
@@ -378,6 +379,16 @@ func (r *importReader) readImport() {
 
 // readComments is like io.ReadAll, except that it only reads the leading
 // block of comments in the file.
+//
+// readComments should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/bazelbuild/bazel-gazelle
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname readComments
 func readComments(f io.Reader) ([]byte, error) {
 	r := newImportReader("", f)
 	r.peekByte(true)

src/go/types/badlinkname.go

@@ -6,15 +6,15 @@ package types
 
 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.
-
-// 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.
+// This should properly be in infer.go, but that file is auto-generated.
 
+// infer should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/goplus/gox
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
 //go:linkname badlinkname_Checker_infer go/types.(*Checker).infer
 func badlinkname_Checker_infer(*Checker, positioner, []*TypeParam, []Type, *Tuple, []*operand, bool, *error_) []Type

src/internal/bytealg/compare_generic.go

@@ -45,6 +45,7 @@ func CompareString(a, b string) int {
 // but widely used packages access it using linkname.
 // Notable members of the hall of shame include:
 //   - github.com/bytedance/gopkg
+//   - github.com/songzhibin97/gkit
 //
 // Do not remove or change the type signature.
 // See go.dev/issue/67401.

src/internal/cpu/cpu_arm64_darwin.go

@@ -30,6 +30,7 @@ func getsysctlbyname(name []byte) (int32, int32)
 // but widely used packages access it using linkname.
 // Notable members of the hall of shame include:
 //   - github.com/bytedance/gopkg
+//   - github.com/songzhibin97/gkit
 //
 // Do not remove or change the type signature.
 // See go.dev/issue/67401.

src/reflect/badlinkname.go

@@ -12,6 +12,7 @@ import (
 // Widely used packages access these symbols using linkname,
 // most notably:
 //	- github.com/goccy/go-json
+//     - github.com/goccy/go-reflect
 //
 // Do not remove or change the type signature.
 // See go.dev/issue/67401

src/reflect/type.go

@@ -1664,6 +1664,7 @@ func rtypeOff(section unsafe.Pointer, off int32) *abi.Type {
 // but widely used packages access it using linkname.
 // Notable members of the hall of shame include:
 //   - github.com/aristanetworks/goarista
+//   - fortio.org/log
 //
 // Do not remove or change the type signature.
 // See go.dev/issue/67401.
@@ -2920,7 +2921,9 @@ func appendVarint(x []byte, v uintptr) []byte {
 // toType should be an internal detail,
 // but widely used packages access it using linkname.
 // Notable members of the hall of shame include:
+//   - fortio.org/log
 //   - github.com/goccy/go-json
+//   - github.com/goccy/go-reflect
 //
 // Do not remove or change the type signature.
 // See go.dev/issue/67401.

src/runtime/alg.go

@@ -51,18 +51,39 @@ var useAeshash bool
 // Notable members of the hall of shame include:
 //   - github.com/aacfactory/fns
 //   - github.com/dgraph-io/ristretto
+//   - github.com/minio/simdjson-go
 //   - github.com/nbd-wtf/go-nostr
 //   - github.com/outcaste-io/ristretto
 //   - github.com/puzpuzpuz/xsync/v2
 //   - github.com/puzpuzpuz/xsync/v3
+//   - github.com/segmentio/parquet-go
 //
 // 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
 
+// memhash32 should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/segmentio/parquet-go
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname memhash32
 func memhash32(p unsafe.Pointer, h uintptr) uintptr
+
+// memhash64 should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/segmentio/parquet-go
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname memhash64
 func memhash64(p unsafe.Pointer, h uintptr) uintptr
 
 // strhash should be an internal detail,
@@ -72,6 +93,7 @@ func memhash64(p unsafe.Pointer, h uintptr) uintptr
 //   - github.com/bytedance/sonic
 //   - github.com/bytedance/go-tagexpr/v2
 //   - github.com/cloudwego/frugal
+//   - github.com/cloudwego/dynamicgo
 //
 // Do not remove or change the type signature.
 // See go.dev/issue/67401.

src/runtime/atomic_pointer.go

@@ -22,6 +22,7 @@ import (
 // but widely used packages access it using linkname.
 // Notable members of the hall of shame include:
 //   - github.com/bytedance/gopkg
+//   - github.com/songzhibin97/gkit
 //
 // Do not remove or change the type signature.
 // See go.dev/issue/67401.

src/runtime/badlinkname.go

@@ -17,8 +17,6 @@ import _ "unsafe"
 // Do not remove or change the type signature.
 // See go.dev/issue/67401.
 
-//go:linkname add
-//go:linkname callers
 //go:linkname fastexprand
 //go:linkname gopanic
 //go:linkname sched

src/runtime/cpuprof.go

@@ -209,7 +209,15 @@ func CPUProfile() []byte {
 	panic("CPUProfile no longer available")
 }
 
-//go:linkname pprof_cyclesPerSecond
+// runtime/pprof.runtime_cyclesPerSecond should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/grafana/pyroscope-go/godeltaprof
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname pprof_cyclesPerSecond runtime/pprof.runtime_cyclesPerSecond
 func pprof_cyclesPerSecond() int64 {
 	return ticksPerSecond()
 }

src/runtime/linkname.go

@@ -31,7 +31,6 @@ import _ "unsafe"
 
 // used in tests
 //go:linkname extraMInUse
-//go:linkname getm
 //go:linkname blockevent
 //go:linkname haveHighResSleep
 //go:linkname blockUntilEmptyFinalizerQueue

src/runtime/malloc.go

@@ -1411,6 +1411,7 @@ func reflectlite_unsafe_New(typ *_type) unsafe.Pointer {
 // newarray should be an internal detail,
 // but widely used packages access it using linkname.
 // Notable members of the hall of shame include:
+//   - github.com/RomiChan/protobuf
 //   - github.com/segmentio/encoding
 //   - github.com/ugorji/go/codec
 //

src/runtime/map.go

@@ -604,6 +604,7 @@ func mapaccess2_fat(t *maptype, h *hmap, key, zero unsafe.Pointer) (unsafe.Point
 // Notable members of the hall of shame include:
 //   - github.com/bytedance/sonic
 //   - github.com/cloudwego/frugal
+//   - github.com/RomiChan/protobuf
 //   - github.com/segmentio/encoding
 //   - github.com/ugorji/go/codec
 //
@@ -864,6 +865,7 @@ search:
 //   - github.com/bytedance/sonic
 //   - github.com/cloudwego/frugal
 //   - github.com/goccy/go-json
+//   - github.com/RomiChan/protobuf
 //   - github.com/segmentio/encoding
 //   - github.com/ugorji/go/codec
 //
@@ -922,6 +924,7 @@ func mapiterinit(t *maptype, h *hmap, it *hiter) {
 // Notable members of the hall of shame include:
 //   - github.com/bytedance/sonic
 //   - github.com/cloudwego/frugal
+//   - github.com/RomiChan/protobuf
 //   - github.com/segmentio/encoding
 //   - github.com/ugorji/go/codec
 //   - gonum.org/v1/gonum
@@ -1389,6 +1392,7 @@ func advanceEvacuationMark(h *hmap, t *maptype, newbit uintptr) {
 //   - gitee.com/quant1x/gox
 //   - github.com/modern-go/reflect2
 //   - github.com/goccy/go-json
+//   - github.com/RomiChan/protobuf
 //   - github.com/segmentio/encoding
 //
 // Do not remove or change the type signature.

src/runtime/mbarrier.go

@@ -151,6 +151,7 @@ import (
 // typedmemmove should be an internal detail,
 // but widely used packages access it using linkname.
 // Notable members of the hall of shame include:
+//   - github.com/RomiChan/protobuf
 //   - github.com/segmentio/encoding
 //
 // Do not remove or change the type signature.
@@ -337,6 +338,7 @@ func typedslicecopy(typ *_type, dstPtr unsafe.Pointer, dstLen int, srcPtr unsafe
 // Notable members of the hall of shame include:
 //   - gitee.com/quant1x/gox
 //   - github.com/modern-go/reflect2
+//   - github.com/RomiChan/protobuf
 //   - github.com/segmentio/encoding
 //
 // Do not remove or change the type signature.

src/runtime/mgc.go

@@ -1708,6 +1708,7 @@ var uniqueMapCleanup chan struct{} // for unique
 // but widely used packages access it using linkname.
 // Notable members of the hall of shame include:
 //   - github.com/bytedance/gopkg
+//   - github.com/songzhibin97/gkit
 //
 // Do not remove or change the type signature.
 // See go.dev/issue/67401.

src/runtime/panic.go

@@ -1034,6 +1034,7 @@ func sync_fatal(s string) {
 //   - github.com/cockroachdb/pebble
 //   - github.com/dgraph-io/ristretto
 //   - github.com/outcaste-io/ristretto
+//   - github.com/pingcap/br
 //   - gvisor.dev/gvisor
 //
 // Do not remove or change the type signature.

src/runtime/pprof/pprof.go

@@ -948,7 +948,7 @@ func writeProfileInternal(w io.Writer, debug int, name string, runtimeProfile fu
 //go:linkname pprof_goroutineProfileWithLabels runtime.pprof_goroutineProfileWithLabels
 func pprof_goroutineProfileWithLabels(p []profilerecord.StackRecord, labels []unsafe.Pointer) (n int, ok bool)
 
-//go:linkname pprof_cyclesPerSecond runtime.pprof_cyclesPerSecond
+//go:linkname pprof_cyclesPerSecond runtime/pprof.runtime_cyclesPerSecond
 func pprof_cyclesPerSecond() int64
 
 //go:linkname pprof_memProfileInternal runtime.pprof_memProfileInternal

src/runtime/proc.go

@@ -2577,6 +2577,16 @@ func cgoBindM() {
 }
 
 // A helper function for EnsureDropM.
+//
+// getm should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - fortio.org/log
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname getm
 func getm() uintptr {
 	return uintptr(unsafe.Pointer(getg().m))
 }
@@ -7051,6 +7061,7 @@ func setMaxThreads(in int) (out int) {
 // Notable members of the hall of shame include:
 //   - github.com/bytedance/gopkg
 //   - github.com/choleraehyq/pid
+//   - github.com/songzhibin97/gkit
 //
 // Do not remove or change the type signature.
 // See go.dev/issue/67401.
@@ -7070,6 +7081,7 @@ func procPin() int {
 // Notable members of the hall of shame include:
 //   - github.com/bytedance/gopkg
 //   - github.com/choleraehyq/pid
+//   - github.com/songzhibin97/gkit
 //
 // Do not remove or change the type signature.
 // See go.dev/issue/67401.

src/runtime/proflabel.go

@@ -11,6 +11,7 @@ var labelSync uintptr
 // runtime_setProfLabel should be an internal detail,
 // but widely used packages access it using linkname.
 // Notable members of the hall of shame include:
+//   - github.com/cloudwego/localsession
 //   - github.com/DataDog/datadog-agent
 //
 // Do not remove or change the type signature.
@@ -45,6 +46,7 @@ func runtime_setProfLabel(labels unsafe.Pointer) {
 // runtime_getProfLabel should be an internal detail,
 // but widely used packages access it using linkname.
 // Notable members of the hall of shame include:
+//   - github.com/cloudwego/localsession
 //   - github.com/DataDog/datadog-agent
 //
 // Do not remove or change the type signature.

src/runtime/rand.go

@@ -233,6 +233,15 @@ func cheaprand64() int64 {
 // the rule is that other packages using runtime-provided
 // randomness must always use randn.
 //
+// cheaprandn should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/phuslu/log
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname cheaprandn
 //go:nosplit
 func cheaprandn(n uint32) uint32 {
 	// See https://lemire.me/blog/2016/06/27/a-fast-alternative-to-the-modulo-reduction/

src/runtime/slice.go

@@ -167,6 +167,7 @@ func makeslice64(et *_type, len64, cap64 int64) unsafe.Pointer {
 // Notable members of the hall of shame include:
 //   - github.com/bytedance/sonic
 //   - github.com/chenzhuoyu/iasm
+//   - github.com/cloudwego/dynamicgo
 //   - github.com/ugorji/go/codec
 //
 // Do not remove or change the type signature.
@@ -319,6 +320,14 @@ func nextslicecap(newLen, oldCap int) int {
 	return newcap
 }
 
+// reflect_growslice should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/cloudwego/dynamicgo
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
 //go:linkname reflect_growslice reflect.growslice
 func reflect_growslice(et *_type, old slice, num int) slice {
 	// Semantically equivalent to slices.Grow, except that the caller