From: Cherry Mui <cherryyz@google.com>
Date: Tue, 11 Jun 2024 15:02:38 +0000 (-0400)
Subject: doc/next: document locking down linkname usages
X-Git-Tag: go1.23rc1~42
X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=816538d517055a8a9293671a88d6a19c4a5e7116;p=gostls13.git

doc/next: document locking down linkname usages

For #65614.
Updates #67401.

Change-Id: Ib38c134ea7ffc69434c79600ba75185e02809d0f
Reviewed-on: https://go-review.googlesource.com/c/go/+/591898
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Reviewed-by: Than McIntosh <thanm@google.com>
---

diff --git a/doc/next/5-toolchain.md b/doc/next/5-toolchain.md
index b1533ad8ac..51a1dbfbdf 100644
--- a/doc/next/5-toolchain.md
+++ b/doc/next/5-toolchain.md
@@ -21,8 +21,17 @@ Hot block alignment can be disabled with `-gcflags=[<packages>=]-d=alignhot=0`
 ## Linker {#linker}
 
 <!-- go.dev/issue/67401, CL 585556, CL 587220, and many more -->
-TODO: Say what needs to be said in Go 1.23 release notes regarding
-the locking down of future linkname uses.
+The linker now disallows using a `//go:linkname` directive to refer to
+internal symbols in the standard library (including the runtime) that
+are not marked with `//go:linkname` on their definitions.
+Similarly, the linker disallows references to such symbols from assembly
+code.
+For backward compatibility, existing usages of `//go:linkname` found in
+a large open-source code corpus remain supported.
+Any new references to standard library internal symbols will be disallowed.
+
+A linker command line flag `-checklinkname=0` can be used to disable
+this check, for debugging and experimenting purposes.
 
 <!-- CL 473495 -->
 When building a dynamically linked ELF binary (including PIE binary), the