runtime: mention linknamestd in HACKING.md

Change-Id: Icc89533e4cfc737bfee8b0c7a72006bdc79746c2
Reviewed-on: https://go-review.googlesource.com/c/go/+/762280
Reviewed-by: Michael Pratt <mpratt@google.com>
LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>

1 files changed, 11 insertions, 0 deletions

diff --git a/src/runtime/HACKING.md b/src/runtime/HACKING.md
index 924471e835..28b90c4455 100644
--- a/src/runtime/HACKING.md
+++ b/src/runtime/HACKING.md
@@ -279,6 +279,7 @@ Linkname conventions
 
 ```
 //go:linkname localname [importpath.name]
+//go:linknamestd localname [importpath.name]
 ```
 
 `//go:linkname` specifies the symbol name (`importpath.name`) used to a
@@ -286,10 +287,17 @@ reference a local identifier (`localname`). The target symbol name is an
 arbitrary ELF/macho/etc symbol name, but by convention we typically use a
 package-prefixed symbol name to keep things organized.
 
+`//go:linknamestd`, introduced in Go 1.27, is similar. The difference is that
+`linknamestd` allows the symbol to be accessed within the standard library
+only, whereas `linkname` permits external accesses. See "Linker check" below.
+The linkname conventions discussed here apply to `linknamestd` as well.
+
 The full generality of `//go:linkname` is very flexible, so as a convention to
 simplify things, we define three standard forms of `//go:linkname` directives.
 
 When possible, always prefer to use the linkname "handshake" described below.
+If the linkname is needed only within the standard library, `linknamestd` is
+preferred.
 
 "Push linkname"
 ---------------
@@ -389,6 +397,9 @@ package otherpkg
 func runtime_foo()
 ```
 
+Linker check
+------------
+
 As of Go 1.23, the linker forbids pull linknames of symbols in the standard
 library unless they participate in a handshake. Since many third-party packages
 already have pull linknames to standard library functions, for backwards