unsafe: document if `syscall.Syscall` exemption to `unsafe.Pointer` rules also applies to other assembly functions

[DemiMarie]

Go version

1.22.5 (this is from pkg.go.dev)

Output of go env in your module/workspace:

N/A (this is from viewing the docs online on pkg.go.dev)

What did you do?

Looked at the docs for unsafe.Pointer

What did you see happen?

Point 4 in the list of allowed uses for unsafe.Pointer states:

Conversion of a Pointer to a uintptr when calling syscall.Syscall.

but the subsequent explanation implies that any function written in assembly can be used, including syscall.Syscall as a special case.

What did you expect to see?

Consistent documentation

[gabyhelp]

Related Issues

• proposal: unsafe: clarify unsafe.Pointer rules for package syscall #34684
• cmd/compile: mishandling of Pointer-to-uintptr conversion for Syscall #23051 (closed)
• x/sys: invalid use of unsafe.Pointer in ioctl arg parameters #44834 (closed)
• unsafe: allow conversion of uintptr to unsafe.Pointer when it points to non-Go memory #58625
• x/sys/windows: uintptr(unsafe.Pointer) calls outside of syscalls #67437 (closed)
• syscall,x/sys/unix: ptrace wrappers erroneously pass Go pointers as type uintptr #58387 (closed)

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}

[ianlancetaylor]

A typical function written in assembler should know which parameters are pointers and which are not. syscall.Syscall is a special case because we don't want to have to write every possible variant. Still, I tweaked it to "functions like syscall.Syscall" in https://go.dev/cl/596936. Thanks.

[gopherbot]

Change https://go.dev/cl/596936 mentions this issue: unsafe: say "functions like syscall.Syscall", not only Syscall