all: document legacy //go:linkname for final round of modules

Add linknames for most modules with ≥50 dependents.
Add linknames for a few other modules that we know
are important but are below 50.

Remove linknames from badlinkname.go that do not merit
inclusion (very small number of dependents).
We can add them back later if the need arises.

Fixes #67401. (For now.)

Change-Id: I1e49fec0292265256044d64b1841d366c4106002
Reviewed-on: https://go-review.googlesource.com/c/go/+/587756
Auto-Submit: Russ Cox <rsc@golang.org>
TryBot-Bypass: Russ Cox <rsc@golang.org>
Reviewed-by: Cherry Mui <cherryyz@google.com>

16 files changed, 94 insertions, 17 deletions

diff --git a/src/runtime/alg.go b/src/runtime/alg.go
index c55f916a7a..bfb9fa1d29 100644
--- a/src/runtime/alg.go
+++ b/src/runtime/alg.go
@@ -57,6 +57,9 @@ var useAeshash bool
 //   - github.com/puzpuzpuz/xsync/v2
 //   - github.com/puzpuzpuz/xsync/v3
 //   - github.com/segmentio/parquet-go
+//   - github.com/parquet-go/parquet-go
+//   - github.com/authzed/spicedb
+//   - github.com/pingcap/badger
 //
 // Do not remove or change the type signature.
 // See go.dev/issue/67401.
@@ -68,6 +71,7 @@ func memhash(p unsafe.Pointer, h, s uintptr) uintptr
 // but widely used packages access it using linkname.
 // Notable members of the hall of shame include:
 //   - github.com/segmentio/parquet-go
+//   - github.com/parquet-go/parquet-go
 //
 // Do not remove or change the type signature.
 // See go.dev/issue/67401.
@@ -79,6 +83,7 @@ func memhash32(p unsafe.Pointer, h uintptr) uintptr
 // but widely used packages access it using linkname.
 // Notable members of the hall of shame include:
 //   - github.com/segmentio/parquet-go
+//   - github.com/parquet-go/parquet-go
 //
 // Do not remove or change the type signature.
 // See go.dev/issue/67401.
@@ -94,6 +99,7 @@ func memhash64(p unsafe.Pointer, h uintptr) uintptr
 //   - github.com/bytedance/go-tagexpr/v2
 //   - github.com/cloudwego/frugal
 //   - github.com/cloudwego/dynamicgo
+//   - github.com/v2fly/v2ray-core/v5
 //
 // Do not remove or change the type signature.
 // See go.dev/issue/67401.
@@ -414,6 +420,16 @@ func ifaceeq(tab *itab, x, y unsafe.Pointer) bool {
 }
 
 // Testing adapters for hash quality tests (see hash_test.go)
+//
+// stringHash should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/k14s/starlark-go
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname stringHash
 func stringHash(s string, seed uintptr) uintptr {
 	return strhash(noescape(unsafe.Pointer(&s)), seed)
 }
diff --git a/src/runtime/badlinkname.go b/src/runtime/badlinkname.go
index 4094e0b9b2..b195bebbda 100644
--- a/src/runtime/badlinkname.go
+++ b/src/runtime/badlinkname.go
@@ -6,26 +6,17 @@ package runtime
 
 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.
-
 // 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 fastexprand
-//go:linkname gopanic
-//go:linkname sched
-//go:linkname startTheWorld
-//go:linkname stopTheWorld
-//go:linkname stringHash
-
 // Notable members of the hall of shame include:
 //   - github.com/dgraph-io/ristretto
 //   - github.com/outcaste-io/ristretto
 //   - github.com/clubpay/ronykit
 //go:linkname cputicks
+
+// Notable members of the hall of shame include:
+//   - gvisor.dev/gvisor (from assembly)
+//go:linkname sched
diff --git a/src/runtime/cpuprof.go b/src/runtime/cpuprof.go
index 997a949a30..100a78258a 100644
--- a/src/runtime/cpuprof.go
+++ b/src/runtime/cpuprof.go
@@ -213,6 +213,7 @@ func CPUProfile() []byte {
 // but widely used packages access it using linkname.
 // Notable members of the hall of shame include:
 //   - github.com/grafana/pyroscope-go/godeltaprof
+//   - github.com/pyroscope-io/godeltaprof
 //
 // Do not remove or change the type signature.
 // See go.dev/issue/67401.
@@ -230,6 +231,14 @@ func pprof_cyclesPerSecond() int64 {
 // The returned data contains a whole number of records, and tags contains
 // exactly one entry per record.
 //
+// runtime_pprof_readProfile should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/pyroscope-io/pyroscope
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
 //go:linkname runtime_pprof_readProfile runtime/pprof.readProfile
 func runtime_pprof_readProfile() ([]uint64, []unsafe.Pointer, bool) {
 	lock(&cpuprof.lock)
diff --git a/src/runtime/iface.go b/src/runtime/iface.go
index 9dcc25cf23..41a10ae012 100644
--- a/src/runtime/iface.go
+++ b/src/runtime/iface.go
@@ -665,6 +665,7 @@ var emptyInterfaceSwitchCache = abi.InterfaceSwitchCache{Mask: 0}
 // Notable members of the hall of shame include:
 //   - gitee.com/quant1x/gox
 //   - github.com/modern-go/reflect2
+//   - github.com/v2pro/plz
 //
 // Do not remove or change the type signature.
 //
diff --git a/src/runtime/linkname.go b/src/runtime/linkname.go
index 39217b68a4..dd7f674251 100644
--- a/src/runtime/linkname.go
+++ b/src/runtime/linkname.go
@@ -9,9 +9,6 @@ import _ "unsafe"
 // used in internal/godebug and syscall
 //go:linkname write
 
-// used in internal/runtime/atomic
-//go:linkname goarm
-
 // used by cgo
 //go:linkname _cgo_panic_internal
 //go:linkname cgoAlwaysFalse
diff --git a/src/runtime/malloc.go b/src/runtime/malloc.go
index 8108419529..b92a213245 100644
--- a/src/runtime/malloc.go
+++ b/src/runtime/malloc.go
@@ -1392,6 +1392,7 @@ func newobject(typ *_type) unsafe.Pointer {
 //   - gitee.com/quant1x/gox
 //   - github.com/goccy/json
 //   - github.com/modern-go/reflect2
+//   - github.com/v2pro/plz
 //
 // Do not remove or change the type signature.
 // See go.dev/issue/67401.
@@ -1439,6 +1440,7 @@ func newarray(typ *_type, n int) unsafe.Pointer {
 //   - github.com/modern-go/reflect2
 //   - github.com/segmentio/encoding
 //   - github.com/segmentio/kafka-go
+//   - github.com/v2pro/plz
 //
 // Do not remove or change the type signature.
 // See go.dev/issue/67401.
diff --git a/src/runtime/map.go b/src/runtime/map.go
index 8757f18b3b..112084f5a7 100644
--- a/src/runtime/map.go
+++ b/src/runtime/map.go
@@ -868,6 +868,7 @@ search:
 //   - github.com/RomiChan/protobuf
 //   - github.com/segmentio/encoding
 //   - github.com/ugorji/go/codec
+//   - github.com/wI2L/jettison
 //
 // Do not remove or change the type signature.
 // See go.dev/issue/67401.
@@ -1394,6 +1395,7 @@ func advanceEvacuationMark(h *hmap, t *maptype, newbit uintptr) {
 //   - github.com/goccy/go-json
 //   - github.com/RomiChan/protobuf
 //   - github.com/segmentio/encoding
+//   - github.com/v2pro/plz
 //
 // Do not remove or change the type signature.
 // See go.dev/issue/67401.
@@ -1442,6 +1444,7 @@ func reflect_makemap(t *maptype, cap int) *hmap {
 // Notable members of the hall of shame include:
 //   - gitee.com/quant1x/gox
 //   - github.com/modern-go/reflect2
+//   - github.com/v2pro/plz
 //
 // Do not remove or change the type signature.
 // See go.dev/issue/67401.
@@ -1470,6 +1473,7 @@ func reflect_mapaccess_faststr(t *maptype, h *hmap, key string) unsafe.Pointer {
 // but widely used packages access it using linkname.
 // Notable members of the hall of shame include:
 //   - gitee.com/quant1x/gox
+//   - github.com/v2pro/plz
 //
 // Do not remove or change the type signature.
 //
@@ -1500,6 +1504,8 @@ func reflect_mapdelete_faststr(t *maptype, h *hmap, key string) {
 // Notable members of the hall of shame include:
 //   - github.com/modern-go/reflect2
 //   - gitee.com/quant1x/gox
+//   - github.com/v2pro/plz
+//   - github.com/wI2L/jettison
 //
 // Do not remove or change the type signature.
 // See go.dev/issue/67401.
@@ -1515,6 +1521,8 @@ func reflect_mapiterinit(t *maptype, h *hmap, it *hiter) {
 //   - gitee.com/quant1x/gox
 //   - github.com/modern-go/reflect2
 //   - github.com/goccy/go-json
+//   - github.com/v2pro/plz
+//   - github.com/wI2L/jettison
 //
 // Do not remove or change the type signature.
 // See go.dev/issue/67401.
@@ -1556,6 +1564,7 @@ func reflect_mapiterelem(it *hiter) unsafe.Pointer {
 // but widely used packages access it using linkname.
 // Notable members of the hall of shame include:
 //   - github.com/goccy/go-json
+//   - github.com/wI2L/jettison
 //
 // Do not remove or change the type signature.
 // See go.dev/issue/67401.
diff --git a/src/runtime/mbarrier.go b/src/runtime/mbarrier.go
index b4fc48977f..7dc8a1a5e5 100644
--- a/src/runtime/mbarrier.go
+++ b/src/runtime/mbarrier.go
@@ -216,6 +216,7 @@ func wbMove(typ *_type, dst, src unsafe.Pointer) {
 //   - github.com/goccy/json
 //   - github.com/modern-go/reflect2
 //   - github.com/ugorji/go/codec
+//   - github.com/v2pro/plz
 //
 // Do not remove or change the type signature.
 // See go.dev/issue/67401.
@@ -340,6 +341,7 @@ func typedslicecopy(typ *_type, dstPtr unsafe.Pointer, dstLen int, srcPtr unsafe
 //   - github.com/modern-go/reflect2
 //   - github.com/RomiChan/protobuf
 //   - github.com/segmentio/encoding
+//   - github.com/v2pro/plz
 //
 // 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 6929862a7d..98e96b12bf 100644
--- a/src/runtime/panic.go
+++ b/src/runtime/panic.go
@@ -720,6 +720,18 @@ func (*PanicNilError) RuntimeError() {}
 var panicnil = &godebugInc{name: "panicnil"}
 
 // The implementation of the predeclared function panic.
+// The compiler emits calls to this function.
+//
+// gopanic should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - go.undefinedlabs.com/scopeagent
+//   - github.com/goplus/igop
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname gopanic
 func gopanic(e any) {
 	if e == nil {
 		if debug.panicnil.Load() != 1 {
@@ -1036,6 +1048,7 @@ func sync_fatal(s string) {
 //   - github.com/outcaste-io/ristretto
 //   - github.com/pingcap/br
 //   - gvisor.dev/gvisor
+//   - github.com/sagernet/gvisor
 //
 // Do not remove or change the type signature.
 // See go.dev/issue/67401.
diff --git a/src/runtime/proc.go b/src/runtime/proc.go
index 9574628ee2..c4f175b0b7 100644
--- a/src/runtime/proc.go
+++ b/src/runtime/proc.go
@@ -398,6 +398,7 @@ func goschedIfBusy() {
 // but widely used packages access it using linkname.
 // Notable members of the hall of shame include:
 //   - gvisor.dev/gvisor
+//   - github.com/sagernet/gvisor
 //
 // Do not remove or change the type signature.
 // See go.dev/issue/67401.
@@ -433,6 +434,7 @@ func goparkunlock(lock *mutex, reason waitReason, traceReason traceBlockReason,
 // but widely used packages access it using linkname.
 // Notable members of the hall of shame include:
 //   - gvisor.dev/gvisor
+//   - github.com/sagernet/gvisor
 //
 // Do not remove or change the type signature.
 // See go.dev/issue/67401.
@@ -4218,6 +4220,7 @@ func preemptPark(gp *g) {
 // but widely used packages access it using linkname.
 // Notable members of the hall of shame include:
 //   - gvisor.dev/gvisor
+//   - github.com/sagernet/gvisor
 //
 // Do not remove or change the type signature.
 // See go.dev/issue/67401.
@@ -7123,6 +7126,7 @@ func sync_atomic_runtime_procUnpin() {
 // but widely used packages access it using linkname.
 // Notable members of the hall of shame include:
 //   - github.com/livekit/protocol
+//   - github.com/sagernet/gvisor
 //   - gvisor.dev/gvisor
 //
 // Do not remove or change the type signature.
@@ -7149,6 +7153,7 @@ func sync_runtime_canSpin(i int) bool {
 // but widely used packages access it using linkname.
 // Notable members of the hall of shame include:
 //   - github.com/livekit/protocol
+//   - github.com/sagernet/gvisor
 //   - gvisor.dev/gvisor
 //
 // Do not remove or change the type signature.
diff --git a/src/runtime/rand.go b/src/runtime/rand.go
index 7e313c19bd..021883dab1 100644
--- a/src/runtime/rand.go
+++ b/src/runtime/rand.go
@@ -182,6 +182,7 @@ func randn(n uint32) uint32 {
 // but widely used packages access it using linkname.
 // Notable members of the hall of shame include:
 //   - github.com/bytedance/gopkg
+//   - github.com/zhangyunhao116/fastrand
 //
 // Do not remove or change the type signature.
 // See go.dev/issue/67401.
@@ -222,6 +223,15 @@ func cheaprand() uint32 {
 // the rule is that other packages using runtime-provided
 // randomness must always use rand.
 //
+// cheaprand64 should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/zhangyunhao116/fastrand
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname cheaprand64
 //go:nosplit
 func cheaprand64() int64 {
 	return int64(cheaprand())<<31 ^ int64(cheaprand())
diff --git a/src/runtime/runtime1.go b/src/runtime/runtime1.go
index 6086d3a0d8..c74f6d2c72 100644
--- a/src/runtime/runtime1.go
+++ b/src/runtime/runtime1.go
@@ -621,6 +621,9 @@ func releasem(mp *m) {
 //   - github.com/goccy/json
 //   - github.com/modern-go/reflect2
 //   - github.com/vmware/govmomi
+//   - github.com/pinpoint-apm/pinpoint-go-agent
+//   - github.com/timandy/routine
+//   - github.com/v2pro/plz
 //
 // Do not remove or change the type signature.
 // See go.dev/issue/67401.
@@ -659,6 +662,8 @@ func reflect_resolveNameOff(ptrInModule unsafe.Pointer, off int32) unsafe.Pointe
 // Notable members of the hall of shame include:
 //   - gitee.com/quant1x/gox
 //   - github.com/modern-go/reflect2
+//   - github.com/v2pro/plz
+//   - github.com/timandy/routine
 //
 // Do not remove or change the type signature.
 // See go.dev/issue/67401.
diff --git a/src/runtime/runtime2.go b/src/runtime/runtime2.go
index 470b829912..8645532ae0 100644
--- a/src/runtime/runtime2.go
+++ b/src/runtime/runtime2.go
@@ -1250,8 +1250,21 @@ var (
 	// Set on startup in asm_{386,amd64}.s
 	processorVersionInfo uint32
 	isIntel              bool
+)
 
-	// set by cmd/link on arm systems
+// set by cmd/link on arm systems
+// accessed using linkname by internal/runtime/atomic.
+//
+// goarm should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/creativeprojects/go-selfupdate
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname goarm
+var (
 	goarm       uint8
 	goarmsoftfp uint8
 )
diff --git a/src/runtime/sema.go b/src/runtime/sema.go
index 0eb3c31a9f..f6b1b84f5f 100644
--- a/src/runtime/sema.go
+++ b/src/runtime/sema.go
@@ -61,6 +61,7 @@ func (t *semTable) rootFor(addr *uint32) *semaRoot {
 // but widely used packages access it using linkname.
 // Notable members of the hall of shame include:
 //   - gvisor.dev/gvisor
+//   - github.com/sagernet/gvisor
 //
 // Do not remove or change the type signature.
 // See go.dev/issue/67401.
@@ -79,6 +80,7 @@ func poll_runtime_Semacquire(addr *uint32) {
 // but widely used packages access it using linkname.
 // Notable members of the hall of shame include:
 //   - gvisor.dev/gvisor
+//   - github.com/sagernet/gvisor
 //
 // 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 d3f75bfcac..2aeb4774b9 100644
--- a/src/runtime/stubs.go
+++ b/src/runtime/stubs.go
@@ -137,6 +137,7 @@ func reflect_memclrNoHeapPointers(ptr unsafe.Pointer, n uintptr) {
 //   - github.com/tetratelabs/wazero
 //   - github.com/ugorji/go/codec
 //   - gvisor.dev/gvisor
+//   - github.com/sagernet/gvisor
 //
 // Do not remove or change the type signature.
 // See go.dev/issue/67401.
diff --git a/src/runtime/symtab.go b/src/runtime/symtab.go
index 993b29d5c0..10cdcf9c6e 100644
--- a/src/runtime/symtab.go
+++ b/src/runtime/symtab.go
@@ -238,6 +238,7 @@ func runtime_FrameSymbolName(f *Frame) string {
 // but widely used packages access it using linkname.
 // Notable members of the hall of shame include:
 //   - github.com/grafana/pyroscope-go/godeltaprof
+//   - github.com/pyroscope-io/godeltaprof
 //
 // Do not remove or change the type signature.
 // See go.dev/issue/67401.