From 186f953bfdc0d0c9d4e8d8c6b06cc90dd343d4b0 Mon Sep 17 00:00:00 2001
From: yuhan6665 <1588741+yuhan6665@users.noreply.github.com>
Date: Sun, 18 Aug 2024 23:33:32 -0400
Subject: [PATCH] =?UTF-8?q?all:=20document=20legacy=20//go:linkname=20for?=
 =?UTF-8?q?=20modules=20with=20=E2=89=A5200=20dependents?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Ignored these linknames which have not worked for a while:

github.com/xtls/xray-core:
	context.newCancelCtx removed in CL 463999 (Feb 2023)

github.com/u-root/u-root:
	funcPC removed in CL 513837 (Jul 2023)

tinygo.org/x/drivers:
	net.useNetdev never existed

For #67401.

Change-Id: I9293f4ef197bb5552b431de8939fa94988a060ce
Reviewed-on: https://go-review.googlesource.com/c/go/+/587576
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>
---
 badlinkname.go   |  1 -
 cipher_suites.go |  9 +++++++++
 common.go        | 10 ++++++++++
 3 files changed, 19 insertions(+), 1 deletion(-)

diff --git a/badlinkname.go b/badlinkname.go
index b83c7f6..ad44bab 100644
--- a/badlinkname.go
+++ b/badlinkname.go
@@ -12,7 +12,6 @@ import _ "unsafe"
 // This may change in the future. Please do not depend on them
 // in new code.
 
-//go:linkname aeadAESGCMTLS13
 //go:linkname cipherSuiteTLS13ByID
 //go:linkname errShutdown
 
diff --git a/cipher_suites.go b/cipher_suites.go
index fa90fe9..44d9057 100644
--- a/cipher_suites.go
+++ b/cipher_suites.go
@@ -520,6 +520,15 @@ func aeadAESGCM(key, noncePrefix []byte) aead {
 	return ret
 }
 
+// aeadAESGCMTLS13 should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/xtls/xray-core
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname aeadAESGCMTLS13
 func aeadAESGCMTLS13(key, nonceMask []byte) aead {
 	if len(nonceMask) != aeadNonceLength {
 		panic("tls: internal error: wrong nonce length")
diff --git a/common.go b/common.go
index 70695c1..8b99cf5 100644
--- a/common.go
+++ b/common.go
@@ -24,6 +24,7 @@ import (
 	"strings"
 	"sync"
 	"time"
+	_ "unsafe" // for linkname
 )
 
 const (
@@ -1149,6 +1150,15 @@ func (c *Config) mutualVersion(isClient bool, peerVersions []uint16) (uint16, bo
 	return 0, false
 }
 
+// errNoCertificates should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/xtls/xray-core
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname errNoCertificates
 var errNoCertificates = errors.New("tls: no certificates configured")
 
 // getCertificate returns the best certificate for the given ClientHelloInfo,