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

For #67401.

Change-Id: Ifea84af92017b405466937f50fb8f28e6893c8cb
Reviewed-on: https://go-review.googlesource.com/c/go/+/587220
Reviewed-by: Cherry Mui <[email protected]>
LUCI-TryBot-Result: Go LUCI <[email protected]>
Auto-Submit: Russ Cox <[email protected]>

Author: rsc

src/crypto/tls/badlinkname.go

@@ -14,9 +14,6 @@ import _ "unsafe"
 
 //go:linkname aeadAESGCMTLS13
 //go:linkname cipherSuiteTLS13ByID
-//go:linkname cipherSuitesTLS13
-//go:linkname defaultCipherSuitesTLS13
-//go:linkname defaultCipherSuitesTLS13NoAES
 //go:linkname errShutdown
 
 // The compiler doesn't allow linknames on methods, for good reasons.

src/crypto/tls/cipher_suites.go

@@ -18,6 +18,7 @@ import (
 	"hash"
 	"internal/cpu"
 	"runtime"
+	_ "unsafe" // for linkname
 
 	"golang.org/x/crypto/chacha20poly1305"
 )
@@ -197,6 +198,15 @@ type cipherSuiteTLS13 struct {
 	hash   crypto.Hash
 }
 
+// cipherSuitesTLS13 should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/quic-go/quic-go
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname cipherSuitesTLS13
 var cipherSuitesTLS13 = []*cipherSuiteTLS13{ // TODO: replace with a map.
 	{TLS_AES_128_GCM_SHA256, 16, aeadAESGCMTLS13, crypto.SHA256},
 	{TLS_CHACHA20_POLY1305_SHA256, 32, aeadChaCha20Poly1305, crypto.SHA256},

src/math/big/arith_decl.go

@@ -6,28 +6,93 @@
 
 package big
 
+import _ "unsafe" // for linkname
+
 // implemented in arith_$GOARCH.s
 
+// addVV should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/remyoudompheng/bigfft
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname addVV
 //go:noescape
 func addVV(z, x, y []Word) (c Word)
 
+// subVV should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/remyoudompheng/bigfft
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname subVV
 //go:noescape
 func subVV(z, x, y []Word) (c Word)
 
+// addVW should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/remyoudompheng/bigfft
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname addVW
 //go:noescape
 func addVW(z, x []Word, y Word) (c Word)
 
+// subVW should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/remyoudompheng/bigfft
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname subVW
 //go:noescape
 func subVW(z, x []Word, y Word) (c Word)
 
+// shlVU should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/remyoudompheng/bigfft
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname shlVU
 //go:noescape
 func shlVU(z, x []Word, s uint) (c Word)
 
 //go:noescape
 func shrVU(z, x []Word, s uint) (c Word)
 
+// mulAddVWW should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/remyoudompheng/bigfft
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname mulAddVWW
 //go:noescape
 func mulAddVWW(z, x []Word, y, r Word) (c Word)
 
+// addMulVVW should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/remyoudompheng/bigfft
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname addMulVVW
 //go:noescape
 func addMulVVW(z, x []Word, y Word) (c Word)

src/math/big/badlinkname.go

@@ -6,9 +6,6 @@ package runtime
 
 import _ "unsafe"
 
-// used in time and internal/poll
-//go:linkname nanotime
-
 // used in internal/godebug and syscall
 //go:linkname write
 

src/runtime/linkname.go

@@ -917,6 +917,7 @@ func mapiterinit(t *maptype, h *hmap, it *hiter) {
 // Notable members of the hall of shame include:
 //   - github.com/bytedance/sonic
 //   - github.com/ugorji/go/codec
+//   - gonum.org/v1/gonum
 //
 // Do not remove or change the type signature.
 // See go.dev/issue/67401.
@@ -1493,6 +1494,7 @@ func reflect_mapiternext(it *hiter) {
 // but widely used packages access it using linkname.
 // Notable members of the hall of shame include:
 //   - github.com/goccy/go-json
+//   - gonum.org/v1/gonum
 //
 // Do not remove or change the type signature.
 // See go.dev/issue/67401.
@@ -1506,6 +1508,7 @@ func reflect_mapiterkey(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
+//   - gonum.org/v1/gonum
 //
 // Do not remove or change the type signature.
 // See go.dev/issue/67401.

src/runtime/map.go

@@ -31,6 +31,7 @@ var faketimeState struct {
 	lastfd uintptr
 }
 
+//go:linkname nanotime
 //go:nosplit
 func nanotime() int64 {
 	return faketime

src/runtime/time_fake.go

@@ -14,6 +14,18 @@ import "unsafe"
 // Zero means not to use faketime.
 var faketime int64
 
+// Many external packages linkname nanotime to get a fast monotonic time.
+// Such code should be updated to use:
+//
+//	var start = time.Now() // at init time
+//
+// and then replace nanotime() with time.Since(start), which is equally fast.
+//
+// However, all the code linknaming nanotime is never going to go away.
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname nanotime
 //go:nosplit
 func nanotime() int64 {
 	return nanotime1()

src/runtime/time_nofake.go

@@ -21,3 +21,13 @@ import _ "unsafe"
 // used by cmd/link
 //go:linkname msync
 //go:linkname fcntl
+
+// mmap should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - modernc.org/memory
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname mmap

src/syscall/linkname_darwin.go

@@ -13,3 +13,13 @@ import _ "unsafe"
 //go:linkname openat
 //go:linkname fstatat
 //go:linkname getentropy
+
+// mmap should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - modernc.org/memory
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname mmap