From ef225d1c57a97af984af114ee52005314530bbe2 Mon Sep 17 00:00:00 2001
From: Russ Cox <rsc@golang.org>
Date: Tue, 21 May 2024 22:38:02 -0400
Subject: [PATCH] =?UTF-8?q?all:=20document=20legacy=20//go:linkname=20for?=
 =?UTF-8?q?=20modules=20with=20=E2=89=A5100,000=20dependents?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

For #67401.

Change-Id: I51f5b561ee11eb242e3b1585d591281d0df4fc24
Reviewed-on: https://go-review.googlesource.com/c/go/+/587215
Auto-Submit: Russ Cox <rsc@golang.org>
Reviewed-by: Cherry Mui <cherryyz@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
---
 src/reflect/badlinkname.go      |  1 -
 src/reflect/value.go            |  9 +++++++++
 src/runtime/iface.go            |  7 +++++++
 src/runtime/linkname.go         |  3 ---
 src/runtime/malloc.go           | 16 ++++++++++++++++
 src/runtime/map.go              | 32 ++++++++++++++++++++++++++++++++
 src/runtime/mbarrier.go         | 16 ++++++++++++++++
 src/runtime/runtime.go          |  7 ++++++-
 src/runtime/runtime1.go         | 16 ++++++++++++++++
 src/runtime/sys_darwin.go       | 24 ++++++++++++++++++++++++
 src/runtime/sys_openbsd3.go     | 20 ++++++++++++++++++++
 src/runtime/syscall_windows.go  |  8 ++++++++
 src/syscall/badlinkname_unix.go |  4 ++++
 src/syscall/linkname_bsd.go     |  4 +++-
 src/syscall/syscall_linux.go    |  9 +++++----
 15 files changed, 166 insertions(+), 10 deletions(-)

diff --git a/src/reflect/badlinkname.go b/src/reflect/badlinkname.go
index 597cc831fedab..e8fb4ff8c6cc9 100644
--- a/src/reflect/badlinkname.go
+++ b/src/reflect/badlinkname.go
@@ -17,7 +17,6 @@ import (
 
 //go:linkname add
 //go:linkname ifaceIndir
-//go:linkname mapassign
 //go:linkname rtypeOff
 //go:linkname toType
 //go:linkname typesByString
diff --git a/src/reflect/value.go b/src/reflect/value.go
index 8ee669f48309b..c93afb99ebee0 100644
--- a/src/reflect/value.go
+++ b/src/reflect/value.go
@@ -3870,6 +3870,15 @@ func mapaccess_faststr(t *abi.Type, m unsafe.Pointer, key string) (val unsafe.Po
 //go:noescape
 func mapassign0(t *abi.Type, m unsafe.Pointer, key, val unsafe.Pointer)
 
+// mapassign should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/modern-go/reflect2
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname mapassign
 func mapassign(t *abi.Type, m unsafe.Pointer, key, val unsafe.Pointer) {
 	contentEscapes(key)
 	contentEscapes(val)
diff --git a/src/runtime/iface.go b/src/runtime/iface.go
index 28eb8fb5ec172..f9c4c8e42d696 100644
--- a/src/runtime/iface.go
+++ b/src/runtime/iface.go
@@ -624,6 +624,13 @@ func buildInterfaceSwitchCache(oldC *abi.InterfaceSwitchCache, typ *_type, case_
 // causes a cache lookup to fail immediately.)
 var emptyInterfaceSwitchCache = abi.InterfaceSwitchCache{Mask: 0}
 
+// reflect_ifaceE2I is for package reflect,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/modern-go/reflect2
+//
+// Do not remove or change the type signature.
+//
 //go:linkname reflect_ifaceE2I reflect.ifaceE2I
 func reflect_ifaceE2I(inter *interfacetype, e eface, dst *iface) {
 	*dst = iface{assertE2I(inter, e._type), e.data}
diff --git a/src/runtime/linkname.go b/src/runtime/linkname.go
index 0f02c6b4e358a..ebad9e1972c8b 100644
--- a/src/runtime/linkname.go
+++ b/src/runtime/linkname.go
@@ -37,9 +37,6 @@ import _ "unsafe"
 // used in runtime/coverage and in tests
 //go:linkname addExitHook
 
-// used in x/sys/cpu
-//go:linkname getAuxv
-
 // used in tests
 //go:linkname extraMInUse
 //go:linkname getm
diff --git a/src/runtime/malloc.go b/src/runtime/malloc.go
index 1df9006011055..4034060424be8 100644
--- a/src/runtime/malloc.go
+++ b/src/runtime/malloc.go
@@ -1371,6 +1371,14 @@ func newobject(typ *_type) unsafe.Pointer {
 	return mallocgc(typ.Size_, typ, true)
 }
 
+// reflect_unsafe_New is meant for package reflect,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/modern-go/reflect2
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
 //go:linkname reflect_unsafe_New reflect.unsafe_New
 func reflect_unsafe_New(typ *_type) unsafe.Pointer {
 	return mallocgc(typ.Size_, typ, true)
@@ -1393,6 +1401,14 @@ func newarray(typ *_type, n int) unsafe.Pointer {
 	return mallocgc(mem, typ, true)
 }
 
+// reflect_unsafe_NewArray is meant for package reflect,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/modern-go/reflect2
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
 //go:linkname reflect_unsafe_NewArray reflect.unsafe_NewArray
 func reflect_unsafe_NewArray(typ *_type, n int) unsafe.Pointer {
 	return newarray(typ, n)
diff --git a/src/runtime/map.go b/src/runtime/map.go
index 9e8ae67a35755..ebfe3b6707d69 100644
--- a/src/runtime/map.go
+++ b/src/runtime/map.go
@@ -1293,6 +1293,14 @@ func advanceEvacuationMark(h *hmap, t *maptype, newbit uintptr) {
 
 // Reflect stubs. Called from ../reflect/asm_*.s
 
+// reflect_makemap is for package reflect,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/modern-go/reflect2
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
 //go:linkname reflect_makemap reflect.makemap
 func reflect_makemap(t *maptype, cap int) *hmap {
 	// Check invariants and reflects math.
@@ -1332,6 +1340,14 @@ func reflect_makemap(t *maptype, cap int) *hmap {
 	return makemap(t, cap, nil)
 }
 
+// reflect_mapaccess is for package reflect,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/modern-go/reflect2
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
 //go:linkname reflect_mapaccess reflect.mapaccess
 func reflect_mapaccess(t *maptype, h *hmap, key unsafe.Pointer) unsafe.Pointer {
 	elem, ok := mapaccess2(t, h, key)
@@ -1374,11 +1390,27 @@ func reflect_mapdelete_faststr(t *maptype, h *hmap, key string) {
 	mapdelete_faststr(t, h, key)
 }
 
+// reflect_mapiterinit is for package reflect,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/modern-go/reflect2
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
 //go:linkname reflect_mapiterinit reflect.mapiterinit
 func reflect_mapiterinit(t *maptype, h *hmap, it *hiter) {
 	mapiterinit(t, h, it)
 }
 
+// reflect_mapiternext is for package reflect,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/modern-go/reflect2
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
 //go:linkname reflect_mapiternext reflect.mapiternext
 func reflect_mapiternext(it *hiter) {
 	mapiternext(it)
diff --git a/src/runtime/mbarrier.go b/src/runtime/mbarrier.go
index dc6922da54a32..89c45cfd29642 100644
--- a/src/runtime/mbarrier.go
+++ b/src/runtime/mbarrier.go
@@ -199,6 +199,14 @@ func wbMove(typ *_type, dst, src unsafe.Pointer) {
 	bulkBarrierPreWrite(uintptr(dst), uintptr(src), typ.PtrBytes, typ)
 }
 
+// reflect_typedmemmove is meant for package reflect,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/modern-go/reflect2
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
 //go:linkname reflect_typedmemmove reflect.typedmemmove
 func reflect_typedmemmove(typ *_type, dst, src unsafe.Pointer) {
 	if raceenabled {
@@ -303,6 +311,14 @@ func typedslicecopy(typ *_type, dstPtr unsafe.Pointer, dstLen int, srcPtr unsafe
 	return n
 }
 
+// reflect_typedslicecopy is meant for package reflect,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/modern-go/reflect2
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
 //go:linkname reflect_typedslicecopy reflect.typedslicecopy
 func reflect_typedslicecopy(elemType *_type, dst, src slice) int {
 	if !elemType.Pointers() {
diff --git a/src/runtime/runtime.go b/src/runtime/runtime.go
index cc6f03d2a086d..f854fd5e417bf 100644
--- a/src/runtime/runtime.go
+++ b/src/runtime/runtime.go
@@ -295,4 +295,9 @@ func setCrashFD(fd uintptr) uintptr {
 // It contains an even number of elements, (tag, value) pairs.
 var auxv []uintptr
 
-func getAuxv() []uintptr { return auxv } // accessed from x/sys/cpu; see issue 57336
+// golang.org/x/sys/cpu uses getAuxv via linkname.
+// Do not remove or change the type signature.
+// (See go.dev/issue/57336.)
+//
+//go:linkname getAuxv
+func getAuxv() []uintptr { return auxv }
diff --git a/src/runtime/runtime1.go b/src/runtime/runtime1.go
index 33a1aa5a02e85..1a6f0366c4f15 100644
--- a/src/runtime/runtime1.go
+++ b/src/runtime/runtime1.go
@@ -614,6 +614,14 @@ func releasem(mp *m) {
 	}
 }
 
+// reflect_typelinks is meant for package reflect,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/modern-go/reflect2
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
 //go:linkname reflect_typelinks reflect.typelinks
 func reflect_typelinks() ([]unsafe.Pointer, [][]int32) {
 	modules := activeModules()
@@ -635,6 +643,14 @@ func reflect_resolveNameOff(ptrInModule unsafe.Pointer, off int32) unsafe.Pointe
 
 // reflect_resolveTypeOff resolves an *rtype offset from a base type.
 //
+// reflect_resolveTypeOff is meant for package reflect,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/modern-go/reflect2
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
 //go:linkname reflect_resolveTypeOff reflect.resolveTypeOff
 func reflect_resolveTypeOff(rtype unsafe.Pointer, off int32) unsafe.Pointer {
 	return unsafe.Pointer(toRType((*_type)(rtype)).typeOff(typeOff(off)))
diff --git a/src/runtime/sys_darwin.go b/src/runtime/sys_darwin.go
index 8e728b9d177cd..a96e2fe1e31ae 100644
--- a/src/runtime/sys_darwin.go
+++ b/src/runtime/sys_darwin.go
@@ -16,6 +16,10 @@ import (
 // and we need to know whether to check 32 or 64 bits of the result.
 // (Some libc functions that return 32 bits put junk in the upper 32 bits of AX.)
 
+// golang.org/x/sys linknames syscall_syscall
+// (in addition to standard package syscall).
+// Do not remove or change the type signature.
+//
 //go:linkname syscall_syscall syscall.syscall
 //go:nosplit
 func syscall_syscall(fn, a1, a2, a3 uintptr) (r1, r2, err uintptr) {
@@ -38,6 +42,10 @@ func syscall_syscallX(fn, a1, a2, a3 uintptr) (r1, r2, err uintptr) {
 }
 func syscallX()
 
+// golang.org/x/sys linknames syscall.syscall6
+// (in addition to standard package syscall).
+// Do not remove or change the type signature.
+//
 //go:linkname syscall_syscall6 syscall.syscall6
 //go:nosplit
 func syscall_syscall6(fn, a1, a2, a3, a4, a5, a6 uintptr) (r1, r2, err uintptr) {
@@ -49,6 +57,10 @@ func syscall_syscall6(fn, a1, a2, a3, a4, a5, a6 uintptr) (r1, r2, err uintptr)
 }
 func syscall6()
 
+// golang.org/x/sys linknames syscall.syscall9
+// (in addition to standard package syscall).
+// Do not remove or change the type signature.
+//
 //go:linkname syscall_syscall9 syscall.syscall9
 //go:nosplit
 //go:cgo_unsafe_args
@@ -71,6 +83,10 @@ func syscall_syscall6X(fn, a1, a2, a3, a4, a5, a6 uintptr) (r1, r2, err uintptr)
 }
 func syscall6X()
 
+// golang.org/x/sys linknames syscall.syscallPtr
+// (in addition to standard package syscall).
+// Do not remove or change the type signature.
+//
 //go:linkname syscall_syscallPtr syscall.syscallPtr
 //go:nosplit
 func syscall_syscallPtr(fn, a1, a2, a3 uintptr) (r1, r2, err uintptr) {
@@ -82,6 +98,10 @@ func syscall_syscallPtr(fn, a1, a2, a3 uintptr) (r1, r2, err uintptr) {
 }
 func syscallPtr()
 
+// golang.org/x/sys linknames syscall_rawSyscall
+// (in addition to standard package syscall).
+// Do not remove or change the type signature.
+//
 //go:linkname syscall_rawSyscall syscall.rawSyscall
 //go:nosplit
 func syscall_rawSyscall(fn, a1, a2, a3 uintptr) (r1, r2, err uintptr) {
@@ -90,6 +110,10 @@ func syscall_rawSyscall(fn, a1, a2, a3 uintptr) (r1, r2, err uintptr) {
 	return args.r1, args.r2, args.err
 }
 
+// golang.org/x/sys linknames syscall_rawSyscall6
+// (in addition to standard package syscall).
+// Do not remove or change the type signature.
+//
 //go:linkname syscall_rawSyscall6 syscall.rawSyscall6
 //go:nosplit
 func syscall_rawSyscall6(fn, a1, a2, a3, a4, a5, a6 uintptr) (r1, r2, err uintptr) {
diff --git a/src/runtime/sys_openbsd3.go b/src/runtime/sys_openbsd3.go
index 269bf86f10de4..de09ec5e25818 100644
--- a/src/runtime/sys_openbsd3.go
+++ b/src/runtime/sys_openbsd3.go
@@ -17,6 +17,10 @@ import (
 // and we need to know whether to check 32 or 64 bits of the result.
 // (Some libc functions that return 32 bits put junk in the upper 32 bits of AX.)
 
+// golang.org/x/sys linknames syscall_syscall
+// (in addition to standard package syscall).
+// Do not remove or change the type signature.
+//
 //go:linkname syscall_syscall syscall.syscall
 //go:nosplit
 //go:cgo_unsafe_args
@@ -39,6 +43,10 @@ func syscall_syscallX(fn, a1, a2, a3 uintptr) (r1, r2, err uintptr) {
 }
 func syscallX()
 
+// golang.org/x/sys linknames syscall.syscall6
+// (in addition to standard package syscall).
+// Do not remove or change the type signature.
+//
 //go:linkname syscall_syscall6 syscall.syscall6
 //go:nosplit
 //go:cgo_unsafe_args
@@ -61,6 +69,10 @@ func syscall_syscall6X(fn, a1, a2, a3, a4, a5, a6 uintptr) (r1, r2, err uintptr)
 }
 func syscall6X()
 
+// golang.org/x/sys linknames syscall.syscall10
+// (in addition to standard package syscall).
+// Do not remove or change the type signature.
+//
 //go:linkname syscall_syscall10 syscall.syscall10
 //go:nosplit
 //go:cgo_unsafe_args
@@ -83,6 +95,10 @@ func syscall_syscall10X(fn, a1, a2, a3, a4, a5, a6, a7, a8, a9, a10 uintptr) (r1
 }
 func syscall10X()
 
+// golang.org/x/sys linknames syscall_rawSyscall
+// (in addition to standard package syscall).
+// Do not remove or change the type signature.
+//
 //go:linkname syscall_rawSyscall syscall.rawSyscall
 //go:nosplit
 //go:cgo_unsafe_args
@@ -91,6 +107,10 @@ func syscall_rawSyscall(fn, a1, a2, a3 uintptr) (r1, r2, err uintptr) {
 	return
 }
 
+// golang.org/x/sys linknames syscall_rawSyscall6
+// (in addition to standard package syscall).
+// Do not remove or change the type signature.
+//
 //go:linkname syscall_rawSyscall6 syscall.rawSyscall6
 //go:nosplit
 //go:cgo_unsafe_args
diff --git a/src/runtime/syscall_windows.go b/src/runtime/syscall_windows.go
index f0e7661a1ba9e..69d720a395c48 100644
--- a/src/runtime/syscall_windows.go
+++ b/src/runtime/syscall_windows.go
@@ -423,6 +423,10 @@ func syscall_loadsystemlibrary(filename *uint16) (handle, err uintptr) {
 	return
 }
 
+// golang.org/x/sys linknames syscall.loadlibrary
+// (in addition to standard package syscall).
+// Do not remove or change the type signature.
+//
 //go:linkname syscall_loadlibrary syscall.loadlibrary
 func syscall_loadlibrary(filename *uint16) (handle, err uintptr) {
 	handle, _, err = syscall_SyscallN(uintptr(unsafe.Pointer(_LoadLibraryW)), uintptr(unsafe.Pointer(filename)))
@@ -433,6 +437,10 @@ func syscall_loadlibrary(filename *uint16) (handle, err uintptr) {
 	return
 }
 
+// golang.org/x/sys linknames syscall.getprocaddress
+// (in addition to standard package syscall).
+// Do not remove or change the type signature.
+//
 //go:linkname syscall_getprocaddress syscall.getprocaddress
 func syscall_getprocaddress(handle uintptr, procname *byte) (outhandle, err uintptr) {
 	outhandle, _, err = syscall_SyscallN(uintptr(unsafe.Pointer(_GetProcAddress)), handle, uintptr(unsafe.Pointer(procname)))
diff --git a/src/syscall/badlinkname_unix.go b/src/syscall/badlinkname_unix.go
index 5e9247c514301..4964a830b003d 100644
--- a/src/syscall/badlinkname_unix.go
+++ b/src/syscall/badlinkname_unix.go
@@ -14,5 +14,9 @@ import _ "unsafe"
 // This may change in the future. Please do not depend on them
 // in new code.
 
+// golang.org/x/sys linknames getsockopt.
+// Do not remove or change the type signature.
+//
 //go:linkname getsockopt
+
 //go:linkname setsockopt
diff --git a/src/syscall/linkname_bsd.go b/src/syscall/linkname_bsd.go
index 65ef900241ce8..c3c6a58420283 100644
--- a/src/syscall/linkname_bsd.go
+++ b/src/syscall/linkname_bsd.go
@@ -11,5 +11,7 @@ import _ "unsafe"
 // used by internal/syscall/unix
 //go:linkname ioctlPtr
 
-// used by x/net/route
+// golang.org/x/net linknames sysctl.
+// Do not remove or change the type signature.
+//
 //go:linkname sysctl
diff --git a/src/syscall/syscall_linux.go b/src/syscall/syscall_linux.go
index 28727dc98a88b..2706973596657 100644
--- a/src/syscall/syscall_linux.go
+++ b/src/syscall/syscall_linux.go
@@ -1284,12 +1284,13 @@ func Munmap(b []byte) (err error) {
 //sys	Mlockall(flags int) (err error)
 //sys	Munlockall() (err error)
 
-// prlimit is accessed from x/sys/unix.
-//go:linkname prlimit
-
 // prlimit changes a resource limit. We use a single definition so that
 // we can tell StartProcess to not restore the original NOFILE limit.
-// This is unexported but can be called from x/sys/unix.
+//
+// golang.org/x/sys linknames prlimit.
+// Do not remove or change the type signature.
+//
+//go:linkname prlimit
 func prlimit(pid int, resource int, newlimit *Rlimit, old *Rlimit) (err error) {
 	err = prlimit1(pid, resource, newlimit, old)
 	if err == nil && newlimit != nil && resource == RLIMIT_NOFILE && (pid == 0 || pid == Getpid()) {