Rework psx to compile more robustly and have clearer documentation.

There are some subtleties about caller conventions when using uintptr
arguments that are actually pointers to gc allocated things.

Signed-off-by: Andrew G. Morgan <morgan@kernel.org>
diff --git a/psx/psx.go b/psx/psx.go
index 529f19d..77648e2 100644
--- a/psx/psx.go
+++ b/psx/psx.go
@@ -3,13 +3,17 @@
 
 package psx // import "kernel.org/pub/linux/libs/security/libcap/psx"
 
-import (
-	"syscall"
-)
+import "syscall"
 
-// Syscall3 and Syscall6 are aliases for syscall.AllThreadsSyscall*
-// when compiled CGO_ENABLED=0.
-var (
-	Syscall3 = syscall.AllThreadsSyscall
-	Syscall6 = syscall.AllThreadsSyscall6
-)
+// Documentation for these functions are provided in the psx_cgo.go
+// file.
+
+//go:uintptrescapes
+func Syscall3(syscallnr, arg1, arg2, arg3 uintptr) (uintptr, uintptr, syscall.Errno) {
+	return syscall.AllThreadsSyscall(syscallnr, arg1, arg2, arg3)
+}
+
+//go:uintptrescapes
+func Syscall6(syscallnr, arg1, arg2, arg3, arg4, arg5, arg6 uintptr) (uintptr, uintptr, syscall.Errno) {
+	return syscall.AllThreadsSyscall6(syscallnr, arg1, arg2, arg3, arg4, arg5, arg6)
+}
diff --git a/psx/psx_cgo.go b/psx/psx_cgo.go
index c17b4f3..26aa15a 100644
--- a/psx/psx_cgo.go
+++ b/psx/psx_cgo.go
@@ -32,11 +32,21 @@
 	return int(C.__errno_too(C.long(v)))
 }
 
-// Syscall3 performs a 3 argument syscall using the libpsx C function
-// psx_syscall3(). Syscall3 differs from syscall.[Raw]Syscall()
-// insofar as it is simultaneously executed on every pthread of the
-// combined Go and CGo runtimes.
+//go:uintptrescapes
+
+// Syscall3 performs a 3 argument syscall. Syscall3 differs from
+// syscall.[Raw]Syscall() insofar as it is simultaneously executed on
+// every thread of the combined Go and CGo runtimes. It works
+// differently depending on whether CGO_ENABLED is 1 or 0 at compile
+// time.
+//
+// If CGO_ENABLED=1 it uses the libpsx function C.psx_syscall3().
+//
+// If CGO_ENABLED=0 it redirects to the go1.16+
+// syscall.AllThreadsSyscall() function.
 func Syscall3(syscallnr, arg1, arg2, arg3 uintptr) (uintptr, uintptr, syscall.Errno) {
+	// We lock to the OSThread here because we may need errno to
+	// be the one for this thread.
 	runtime.LockOSThread()
 	defer runtime.UnlockOSThread()
 
@@ -48,11 +58,15 @@
 	return uintptr(v), uintptr(v), errno
 }
 
-// Syscall6 performs a 6 argument syscall using the libpsx C function
-// psx_syscall6(). Syscall6 differs from syscall.[Raw]Syscall6() insofar as
-// it is simultaneously executed on every pthread of the combined Go
-// and CGo runtimes.
+//go:uintptrescapes
+
+// Syscall6 performs a 6 argument syscall on every thread of the
+// combined Go and CGo runtimes. Other than the number of syscall
+// arguments, its behavior is identical to that of Syscall3() - see
+// above for the full documentation.
 func Syscall6(syscallnr, arg1, arg2, arg3, arg4, arg5, arg6 uintptr) (uintptr, uintptr, syscall.Errno) {
+	// We lock to the OSThread here because we may need errno to
+	// be the one for this thread.
 	runtime.LockOSThread()
 	defer runtime.UnlockOSThread()