]> Cypherpunks repositories - gostls13.git/commitdiff
all: document legacy //go:linkname for modules with ≥100,000 dependents
authorRuss Cox <rsc@golang.org>
Wed, 22 May 2024 02:38:02 +0000 (22:38 -0400)
committerGopher Robot <gobot@golang.org>
Wed, 22 May 2024 20:12:46 +0000 (20:12 +0000)
For #67401.

Change-Id: I51f5b561ee11eb242e3b1585d591281d0df4fc24
Reviewed-on: https://go-review.googlesource.com/c/go/+/587215
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>

15 files changed:
src/reflect/badlinkname.go
src/reflect/value.go
src/runtime/iface.go
src/runtime/linkname.go
src/runtime/malloc.go
src/runtime/map.go
src/runtime/mbarrier.go
src/runtime/runtime.go
src/runtime/runtime1.go
src/runtime/sys_darwin.go
src/runtime/sys_openbsd3.go
src/runtime/syscall_windows.go
src/syscall/badlinkname_unix.go
src/syscall/linkname_bsd.go
src/syscall/syscall_linux.go

index 597cc831fedab2835817744fa0eaca9b5132583b..e8fb4ff8c6cc9882c900b17ec05bc422333b4c39 100644 (file)
@@ -17,7 +17,6 @@ import (
 
 //go:linkname add
 //go:linkname ifaceIndir
-//go:linkname mapassign
 //go:linkname rtypeOff
 //go:linkname toType
 //go:linkname typesByString
index 8ee669f48309b435d7d4cdc718d5336e2cc82e42..c93afb99ebee07d0b86c71bcc204bdb23d5981e1 100644 (file)
@@ -3870,6 +3870,15 @@ func mapaccess_faststr(t *abi.Type, m unsafe.Pointer, key string) (val unsafe.Po
 //go:noescape
 func mapassign0(t *abi.Type, m unsafe.Pointer, key, val unsafe.Pointer)
 
+// mapassign should be an internal detail,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/modern-go/reflect2
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
+//go:linkname mapassign
 func mapassign(t *abi.Type, m unsafe.Pointer, key, val unsafe.Pointer) {
        contentEscapes(key)
        contentEscapes(val)
index 28eb8fb5ec1722f12abcbab63b5075c765e28d1e..f9c4c8e42d6963475199cf93664e850dfd26128c 100644 (file)
@@ -624,6 +624,13 @@ func buildInterfaceSwitchCache(oldC *abi.InterfaceSwitchCache, typ *_type, case_
 // causes a cache lookup to fail immediately.)
 var emptyInterfaceSwitchCache = abi.InterfaceSwitchCache{Mask: 0}
 
+// reflect_ifaceE2I is for package reflect,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/modern-go/reflect2
+//
+// Do not remove or change the type signature.
+//
 //go:linkname reflect_ifaceE2I reflect.ifaceE2I
 func reflect_ifaceE2I(inter *interfacetype, e eface, dst *iface) {
        *dst = iface{assertE2I(inter, e._type), e.data}
index 0f02c6b4e358a115636a1930db9476de084d7bf2..ebad9e1972c8b8ea338d974ac9c1f63a010d4eac 100644 (file)
@@ -37,9 +37,6 @@ import _ "unsafe"
 // used in runtime/coverage and in tests
 //go:linkname addExitHook
 
-// used in x/sys/cpu
-//go:linkname getAuxv
-
 // used in tests
 //go:linkname extraMInUse
 //go:linkname getm
index 1df900601105530871bfbd0241cf43594f6ac3b3..4034060424be8c7fde101505b50ea6cfd33d6d66 100644 (file)
@@ -1371,6 +1371,14 @@ func newobject(typ *_type) unsafe.Pointer {
        return mallocgc(typ.Size_, typ, true)
 }
 
+// reflect_unsafe_New is meant for package reflect,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/modern-go/reflect2
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
 //go:linkname reflect_unsafe_New reflect.unsafe_New
 func reflect_unsafe_New(typ *_type) unsafe.Pointer {
        return mallocgc(typ.Size_, typ, true)
@@ -1393,6 +1401,14 @@ func newarray(typ *_type, n int) unsafe.Pointer {
        return mallocgc(mem, typ, true)
 }
 
+// reflect_unsafe_NewArray is meant for package reflect,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/modern-go/reflect2
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
 //go:linkname reflect_unsafe_NewArray reflect.unsafe_NewArray
 func reflect_unsafe_NewArray(typ *_type, n int) unsafe.Pointer {
        return newarray(typ, n)
index 9e8ae67a357550ba289aefea66f5b3ca4ba90fc9..ebfe3b6707d69b23ef55e432a18a3bb619b9cd0c 100644 (file)
@@ -1293,6 +1293,14 @@ func advanceEvacuationMark(h *hmap, t *maptype, newbit uintptr) {
 
 // Reflect stubs. Called from ../reflect/asm_*.s
 
+// reflect_makemap is for package reflect,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/modern-go/reflect2
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
 //go:linkname reflect_makemap reflect.makemap
 func reflect_makemap(t *maptype, cap int) *hmap {
        // Check invariants and reflects math.
@@ -1332,6 +1340,14 @@ func reflect_makemap(t *maptype, cap int) *hmap {
        return makemap(t, cap, nil)
 }
 
+// reflect_mapaccess is for package reflect,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/modern-go/reflect2
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
 //go:linkname reflect_mapaccess reflect.mapaccess
 func reflect_mapaccess(t *maptype, h *hmap, key unsafe.Pointer) unsafe.Pointer {
        elem, ok := mapaccess2(t, h, key)
@@ -1374,11 +1390,27 @@ func reflect_mapdelete_faststr(t *maptype, h *hmap, key string) {
        mapdelete_faststr(t, h, key)
 }
 
+// reflect_mapiterinit is for package reflect,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/modern-go/reflect2
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
 //go:linkname reflect_mapiterinit reflect.mapiterinit
 func reflect_mapiterinit(t *maptype, h *hmap, it *hiter) {
        mapiterinit(t, h, it)
 }
 
+// reflect_mapiternext is for package reflect,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/modern-go/reflect2
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
 //go:linkname reflect_mapiternext reflect.mapiternext
 func reflect_mapiternext(it *hiter) {
        mapiternext(it)
index dc6922da54a324ac0fef80339f17c28d97979c62..89c45cfd29642f638ca11bcb776547e7b0ae0963 100644 (file)
@@ -199,6 +199,14 @@ func wbMove(typ *_type, dst, src unsafe.Pointer) {
        bulkBarrierPreWrite(uintptr(dst), uintptr(src), typ.PtrBytes, typ)
 }
 
+// reflect_typedmemmove is meant for package reflect,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/modern-go/reflect2
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
 //go:linkname reflect_typedmemmove reflect.typedmemmove
 func reflect_typedmemmove(typ *_type, dst, src unsafe.Pointer) {
        if raceenabled {
@@ -303,6 +311,14 @@ func typedslicecopy(typ *_type, dstPtr unsafe.Pointer, dstLen int, srcPtr unsafe
        return n
 }
 
+// reflect_typedslicecopy is meant for package reflect,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/modern-go/reflect2
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
 //go:linkname reflect_typedslicecopy reflect.typedslicecopy
 func reflect_typedslicecopy(elemType *_type, dst, src slice) int {
        if !elemType.Pointers() {
index cc6f03d2a086dfd76b80563a0f8c3646247cd55a..f854fd5e417bf0a2607faffd6b53fdf7ba84a526 100644 (file)
@@ -295,4 +295,9 @@ func setCrashFD(fd uintptr) uintptr {
 // It contains an even number of elements, (tag, value) pairs.
 var auxv []uintptr
 
-func getAuxv() []uintptr { return auxv } // accessed from x/sys/cpu; see issue 57336
+// golang.org/x/sys/cpu uses getAuxv via linkname.
+// Do not remove or change the type signature.
+// (See go.dev/issue/57336.)
+//
+//go:linkname getAuxv
+func getAuxv() []uintptr { return auxv }
index 33a1aa5a02e8506ce525a4bf2725b311d4d8a992..1a6f0366c4f15cb7f065b782e13d0756b3606f98 100644 (file)
@@ -614,6 +614,14 @@ func releasem(mp *m) {
        }
 }
 
+// reflect_typelinks is meant for package reflect,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/modern-go/reflect2
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
 //go:linkname reflect_typelinks reflect.typelinks
 func reflect_typelinks() ([]unsafe.Pointer, [][]int32) {
        modules := activeModules()
@@ -635,6 +643,14 @@ func reflect_resolveNameOff(ptrInModule unsafe.Pointer, off int32) unsafe.Pointe
 
 // reflect_resolveTypeOff resolves an *rtype offset from a base type.
 //
+// reflect_resolveTypeOff is meant for package reflect,
+// but widely used packages access it using linkname.
+// Notable members of the hall of shame include:
+//   - github.com/modern-go/reflect2
+//
+// Do not remove or change the type signature.
+// See go.dev/issue/67401.
+//
 //go:linkname reflect_resolveTypeOff reflect.resolveTypeOff
 func reflect_resolveTypeOff(rtype unsafe.Pointer, off int32) unsafe.Pointer {
        return unsafe.Pointer(toRType((*_type)(rtype)).typeOff(typeOff(off)))
index 8e728b9d177cdceac5e63d53eadf383f91d299e0..a96e2fe1e31ae6b51becd48d5beaa007710e91c9 100644 (file)
@@ -16,6 +16,10 @@ import (
 // and we need to know whether to check 32 or 64 bits of the result.
 // (Some libc functions that return 32 bits put junk in the upper 32 bits of AX.)
 
+// golang.org/x/sys linknames syscall_syscall
+// (in addition to standard package syscall).
+// Do not remove or change the type signature.
+//
 //go:linkname syscall_syscall syscall.syscall
 //go:nosplit
 func syscall_syscall(fn, a1, a2, a3 uintptr) (r1, r2, err uintptr) {
@@ -38,6 +42,10 @@ func syscall_syscallX(fn, a1, a2, a3 uintptr) (r1, r2, err uintptr) {
 }
 func syscallX()
 
+// golang.org/x/sys linknames syscall.syscall6
+// (in addition to standard package syscall).
+// Do not remove or change the type signature.
+//
 //go:linkname syscall_syscall6 syscall.syscall6
 //go:nosplit
 func syscall_syscall6(fn, a1, a2, a3, a4, a5, a6 uintptr) (r1, r2, err uintptr) {
@@ -49,6 +57,10 @@ func syscall_syscall6(fn, a1, a2, a3, a4, a5, a6 uintptr) (r1, r2, err uintptr)
 }
 func syscall6()
 
+// golang.org/x/sys linknames syscall.syscall9
+// (in addition to standard package syscall).
+// Do not remove or change the type signature.
+//
 //go:linkname syscall_syscall9 syscall.syscall9
 //go:nosplit
 //go:cgo_unsafe_args
@@ -71,6 +83,10 @@ func syscall_syscall6X(fn, a1, a2, a3, a4, a5, a6 uintptr) (r1, r2, err uintptr)
 }
 func syscall6X()
 
+// golang.org/x/sys linknames syscall.syscallPtr
+// (in addition to standard package syscall).
+// Do not remove or change the type signature.
+//
 //go:linkname syscall_syscallPtr syscall.syscallPtr
 //go:nosplit
 func syscall_syscallPtr(fn, a1, a2, a3 uintptr) (r1, r2, err uintptr) {
@@ -82,6 +98,10 @@ func syscall_syscallPtr(fn, a1, a2, a3 uintptr) (r1, r2, err uintptr) {
 }
 func syscallPtr()
 
+// golang.org/x/sys linknames syscall_rawSyscall
+// (in addition to standard package syscall).
+// Do not remove or change the type signature.
+//
 //go:linkname syscall_rawSyscall syscall.rawSyscall
 //go:nosplit
 func syscall_rawSyscall(fn, a1, a2, a3 uintptr) (r1, r2, err uintptr) {
@@ -90,6 +110,10 @@ func syscall_rawSyscall(fn, a1, a2, a3 uintptr) (r1, r2, err uintptr) {
        return args.r1, args.r2, args.err
 }
 
+// golang.org/x/sys linknames syscall_rawSyscall6
+// (in addition to standard package syscall).
+// Do not remove or change the type signature.
+//
 //go:linkname syscall_rawSyscall6 syscall.rawSyscall6
 //go:nosplit
 func syscall_rawSyscall6(fn, a1, a2, a3, a4, a5, a6 uintptr) (r1, r2, err uintptr) {
index 269bf86f10de43ca22e0f868d777492f556adafd..de09ec5e25818a9e5f89d99ce2e5f38bf67f7f0e 100644 (file)
@@ -17,6 +17,10 @@ import (
 // and we need to know whether to check 32 or 64 bits of the result.
 // (Some libc functions that return 32 bits put junk in the upper 32 bits of AX.)
 
+// golang.org/x/sys linknames syscall_syscall
+// (in addition to standard package syscall).
+// Do not remove or change the type signature.
+//
 //go:linkname syscall_syscall syscall.syscall
 //go:nosplit
 //go:cgo_unsafe_args
@@ -39,6 +43,10 @@ func syscall_syscallX(fn, a1, a2, a3 uintptr) (r1, r2, err uintptr) {
 }
 func syscallX()
 
+// golang.org/x/sys linknames syscall.syscall6
+// (in addition to standard package syscall).
+// Do not remove or change the type signature.
+//
 //go:linkname syscall_syscall6 syscall.syscall6
 //go:nosplit
 //go:cgo_unsafe_args
@@ -61,6 +69,10 @@ func syscall_syscall6X(fn, a1, a2, a3, a4, a5, a6 uintptr) (r1, r2, err uintptr)
 }
 func syscall6X()
 
+// golang.org/x/sys linknames syscall.syscall10
+// (in addition to standard package syscall).
+// Do not remove or change the type signature.
+//
 //go:linkname syscall_syscall10 syscall.syscall10
 //go:nosplit
 //go:cgo_unsafe_args
@@ -83,6 +95,10 @@ func syscall_syscall10X(fn, a1, a2, a3, a4, a5, a6, a7, a8, a9, a10 uintptr) (r1
 }
 func syscall10X()
 
+// golang.org/x/sys linknames syscall_rawSyscall
+// (in addition to standard package syscall).
+// Do not remove or change the type signature.
+//
 //go:linkname syscall_rawSyscall syscall.rawSyscall
 //go:nosplit
 //go:cgo_unsafe_args
@@ -91,6 +107,10 @@ func syscall_rawSyscall(fn, a1, a2, a3 uintptr) (r1, r2, err uintptr) {
        return
 }
 
+// golang.org/x/sys linknames syscall_rawSyscall6
+// (in addition to standard package syscall).
+// Do not remove or change the type signature.
+//
 //go:linkname syscall_rawSyscall6 syscall.rawSyscall6
 //go:nosplit
 //go:cgo_unsafe_args
index f0e7661a1ba9e2e26eb70977b44f288d40096086..69d720a395c48d5e2764a4b5bf0ac7b1bba11bcb 100644 (file)
@@ -423,6 +423,10 @@ func syscall_loadsystemlibrary(filename *uint16) (handle, err uintptr) {
        return
 }
 
+// golang.org/x/sys linknames syscall.loadlibrary
+// (in addition to standard package syscall).
+// Do not remove or change the type signature.
+//
 //go:linkname syscall_loadlibrary syscall.loadlibrary
 func syscall_loadlibrary(filename *uint16) (handle, err uintptr) {
        handle, _, err = syscall_SyscallN(uintptr(unsafe.Pointer(_LoadLibraryW)), uintptr(unsafe.Pointer(filename)))
@@ -433,6 +437,10 @@ func syscall_loadlibrary(filename *uint16) (handle, err uintptr) {
        return
 }
 
+// golang.org/x/sys linknames syscall.getprocaddress
+// (in addition to standard package syscall).
+// Do not remove or change the type signature.
+//
 //go:linkname syscall_getprocaddress syscall.getprocaddress
 func syscall_getprocaddress(handle uintptr, procname *byte) (outhandle, err uintptr) {
        outhandle, _, err = syscall_SyscallN(uintptr(unsafe.Pointer(_GetProcAddress)), handle, uintptr(unsafe.Pointer(procname)))
index 5e9247c51430116e90a4a809c53f6b23f5beaf60..4964a830b003d6bba3e6f8649ee8389d699b25b4 100644 (file)
@@ -14,5 +14,9 @@ import _ "unsafe"
 // This may change in the future. Please do not depend on them
 // in new code.
 
+// golang.org/x/sys linknames getsockopt.
+// Do not remove or change the type signature.
+//
 //go:linkname getsockopt
+
 //go:linkname setsockopt
index 65ef900241ce8e8e9d315b0c4ec5d4a79ab49628..c3c6a58420283751ed447d18d9d6c7bb81afdf23 100644 (file)
@@ -11,5 +11,7 @@ import _ "unsafe"
 // used by internal/syscall/unix
 //go:linkname ioctlPtr
 
-// used by x/net/route
+// golang.org/x/net linknames sysctl.
+// Do not remove or change the type signature.
+//
 //go:linkname sysctl
index 28727dc98a88be27e4f10fb534a5d8d984cbc625..2706973596657bbe0a355c800f04718385fb0f6a 100644 (file)
@@ -1284,12 +1284,13 @@ func Munmap(b []byte) (err error) {
 //sys  Mlockall(flags int) (err error)
 //sys  Munlockall() (err error)
 
-// prlimit is accessed from x/sys/unix.
-//go:linkname prlimit
-
 // prlimit changes a resource limit. We use a single definition so that
 // we can tell StartProcess to not restore the original NOFILE limit.
-// This is unexported but can be called from x/sys/unix.
+//
+// golang.org/x/sys linknames prlimit.
+// Do not remove or change the type signature.
+//
+//go:linkname prlimit
 func prlimit(pid int, resource int, newlimit *Rlimit, old *Rlimit) (err error) {
        err = prlimit1(pid, resource, newlimit, old)
        if err == nil && newlimit != nil && resource == RLIMIT_NOFILE && (pid == 0 || pid == Getpid()) {