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 <cherryyz@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Auto-Submit: Russ Cox <rsc@golang.org>

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.

cipher_suites.go

@@ -16,6 +16,7 @@ import (
 	"fmt"
 	"hash"
 	"runtime"
+	_ "unsafe" // for linkname
 
 	"golang.org/x/crypto/chacha20poly1305"
 	"golang.org/x/sys/cpu"
@@ -196,6 +197,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},