Skip to contentSkip to conversation

prctl.2: Document Syscall User Dispatch

PATCH Superseded Gabriel Krisman Bertazi 2 participants 3 messages Dec 21, 2020 – Dec 22, 2020 Man-pages: manual pages for Linux -- Sections 2, 3, 4, 5, and 7

v3 of 8 Superseded Latest is v8 →

lore
Share & tools
lore
#0 lore raw

PATCH v3 1/1 prctl.2: Document Syscall User Dispatch

---
Changes since v2:
(suggested by Alejandro Colomar)
- selective -> selectively
- Add missing oxford comma.

Changes since v1:
(suggested by Alejandro Colomar)
- Use semantic lines
- Fix usage of .{B|I}R and .{B|I}
- Don't format literals
- Fix preferred spelling of userspace
- Fix case of word

---
 man2/prctl.2 | 100 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 100 insertions(+)
man2/prctl.2 +100 -0
index f25f05fdb593..8105c2a0c9de 100644
@@ -1533,6 +1533,78 @@ For more information, see the kernel source file
 (or
 .I Documentation/arm64/sve.txt
 before Linux 5.3).
+.TP
+.\" prctl PR_SET_SYSCALL_USER_DISPATCH
+.\" commit 1446e1df9eb183fdf81c3f0715402f1d7595d4
+.BR PR_SET_SYSCALL_USER_DISPATCH " (since Linux 5.11, x86 only)"
+.IP
+Configure the Syscall User Dispatch mechanism
+for the calling thread,
+to selectively intercept system calls
+and dispatch them back to user space through
+.IR SIGSYS .
+.IP
+The current Syscall User Dispatch mode is selected via
+.IR arg2 ,
+which can either be set to
+.B PR_SYS_DISPATCH_ON
+to enable the feature,
+or to
+.B PR_SYS_DISPATCH_OFF
+to turn it off.
+.IP
+With
+.I arg2
+set to
+.BR PR_SYS_DISPATCH_ON ,
+.I arg3
+and
+.I arg4
+respectively identify the
+.I offset
+and
+.I length
+of a memory region in the process map
+from where system calls are always allowed to be executed,
+regardless of the switch variable.
+.I arg5
+points to a char-sized variable
+that is a fast switch to enable/disable the mechanism
+without invoking the kernel.
+The variable pointed by
+.I arg5
+can either be set to
+.B PR_SYS_DISPATCH_ON
+to enable the mechanism
+or to
+.B PR_SYS_DISPATCH_OFF
+to temporarily disable it.
+Any other value will fail the application
+with a
+.IR SIGSYS .
+.IP
+When a system call is intercepted,
+.I SIGSYS
+is raised with
+.I si_code
+set to
+.BR SYS_USER_DISPATCH .
+.IP
+When
+.I arg2
+is set to
+.BR PR_SYS_DISPATCH_OFF ,
+the remaining arguments must be set to 0.
+.IP
+The setting is not preserved across
+.BR fork (2),
+.BR clone (2),
+or
+.BR execve (2).
+.IP
+For more information,
+see the kernel source file
+.IR Documentation/admin-guide/syscall-user-dispatch.rst
 .\" prctl PR_SET_TAGGED_ADDR_CTRL
 .\" commit 63f0c60379650d82250f22e4cf4137ef3dc4f43d
 .TP
@@ -2000,6 +2072,14 @@ and
 .I arg3
 is an invalid address.
 .TP
+.B EFAULT
+.I option
+is
+.B PR_SET_SYSCALL_USER_DISPATCH
+and
+.I arg5
+has an invalid address.
+.TP
 .B EINVAL
 The value of
 .I option
@@ -2229,6 +2309,26 @@ is
 and SVE is not available on this platform.
 .TP
 .B EINVAL
+.I option is
+.B PR_SET_SYSCALL_USER_DISPATCH
+and one of the following is true:
+.RS
+.IP * 3
+.I arg2
+is
+.B PR_SYS_DISPATCH_OFF
+and remaining arguments are not 0;
+.IP * 3
+.I arg2
+is
+.B PR_SYS_DISPATCH_ON
+and the memory region provided is invalid;
+.IP * 3
+.I arg2
+is invalid.
+.RE
+.TP
+.B EINVAL
 .I option
 is
 .BR PR_SET_TAGGED_ADDR_CTRL
Signature · 1 line
2.29.2
#1 lore raw
Quoted 27 lines · Gabriel Krisman Bertazi

---
Changes since v2:
(suggested by Alejandro Colomar)
- selective -> selectively
- Add missing oxford comma.

Changes since v1:
(suggested by Alejandro Colomar)
- Use semantic lines
- Fix usage of .{B|I}R and .{B|I}
- Don't format literals
- Fix preferred spelling of userspace
- Fix case of word

---
 man2/prctl.2 | 100 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 100 insertions(+)
man2/prctl.2 +0 -0
index f25f05fdb593..8105c2a0c9de 100644
@@ -1533,6 +1533,78 @@ For more information, see the kernel source file
 (or
 .I Documentation/arm64/sve.txt
 before Linux 5.3).

man2/prctl.2 For more information, see the kernel source file · line 1545

Quoted 10 lines
man2/prctl.2 +10 -0
+.TP
+.\" prctl PR_SET_SYSCALL_USER_DISPATCH
+.\" commit 1446e1df9eb183fdf81c3f0715402f1d7595d4
+.BR PR_SET_SYSCALL_USER_DISPATCH " (since Linux 5.11, x86 only)"
+.IP
+Configure the Syscall User Dispatch mechanism
+for the calling thread,
+to selectively intercept system calls
+and dispatch them back to user space through
+.IR SIGSYS .

s/IR/BR/

I think a bit more explanation would help here. Could you add a few sentences to explain what "dispatch back to user space through SIGSYS" means?

man2/prctl.2 For more information, see the kernel source file · line 1554

Quoted 9 lines
man2/prctl.2 +9 -0
+.IP
+The current Syscall User Dispatch mode is selected via
+.IR arg2 ,
+which can either be set to
+.B PR_SYS_DISPATCH_ON
+to enable the feature,
+or to
+.B PR_SYS_DISPATCH_OFF
+to turn it off.

By the way, why is there no PR_*G*ET_SYSCALL_USER_DISPATCH?

Quoted 5 lines
man2/prctl.2 +5 -0
+.IP
+With
+.I arg2
+set to
+.BR PR_SYS_DISPATCH_ON ,

man2/prctl.2 For more information, see the kernel source file · line 1569

Quoted 10 lines
man2/prctl.2 +10 -0
+.I arg3
+and
+.I arg4
+respectively identify the
+.I offset
+and
+.I length
+of a memory region in the process map
+from where system calls are always allowed to be executed,
+regardless of the switch variable.

Can there be more than one of these regions?
The text should be explicit about this, I think.

Quoted 5 lines
man2/prctl.2 +5 -0
+.I arg5
+points to a char-sized variable
+that is a fast switch to enable/disable the mechanism
+without invoking the kernel.
+The variable pointed by

man2/prctl.2 For more information, see the kernel source file · line 1584

Quoted 10 lines
man2/prctl.2 +10 -0
+.I arg5
+can either be set to
+.B PR_SYS_DISPATCH_ON
+to enable the mechanism
+or to
+.B PR_SYS_DISPATCH_OFF
+to temporarily disable it.
+Any other value will fail the application
+with a
+.IR SIGSYS .

How/when does that failure occur? At the time of the prctl() call, I presume? What if the caller later sets the variable pointed to by arg5 to another value?

Quoted 44 lines
man2/prctl.2 +31 -0
+.IP
+When a system call is intercepted,
+.I SIGSYS
+is raised with
+.I si_code
+set to
+.BR SYS_USER_DISPATCH .
+.IP
+When
+.I arg2
+is set to
+.BR PR_SYS_DISPATCH_OFF ,
+the remaining arguments must be set to 0.
+.IP
+The setting is not preserved across
+.BR fork (2),
+.BR clone (2),
+or
+.BR execve (2).
+.IP
+For more information,
+see the kernel source file
+.IR Documentation/admin-guide/syscall-user-dispatch.rst
 .\" prctl PR_SET_TAGGED_ADDR_CTRL
 .\" commit 63f0c60379650d82250f22e4cf4137ef3dc4f43d
 .TP
@@ -2000,6 +2072,14 @@ and
 .I arg3
 is an invalid address.
 .TP
+.B EFAULT
+.I option
+is
+.B PR_SET_SYSCALL_USER_DISPATCH
+and
+.I arg5
+has an invalid address.
+.TP
 .B EINVAL
 The value of
 .I option
@@ -2229,6 +2309,26 @@ is
 and SVE is not available on this platform.
 .TP

man2/prctl.2 is · line 2320

Quoted 10 lines
man2/prctl.2 +9 -0
 .B EINVAL
+.I option is
+.B PR_SET_SYSCALL_USER_DISPATCH
+and one of the following is true:
+.RS
+.IP * 3
+.I arg2
+is
+.B PR_SYS_DISPATCH_OFF
+and remaining arguments are not 0;

s/and/and the/

man2/prctl.2 is · line 2325

Quoted 5 lines
man2/prctl.2 +5 -0
+.IP * 3
+.I arg2
+is
+.B PR_SYS_DISPATCH_ON
+and the memory region provided is invalid;

Please define "invalid"

man2/prctl.2 is · line 2334

Quoted 9 lines
man2/prctl.2 +6 -0
+.IP * 3
+.I arg2
+is invalid.
+.RE
+.TP
+.B EINVAL
 .I option
 is
 .BR PR_SET_TAGGED_ADDR_CTRL

Thanks,

Michael

Signature · 3 lines
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
#2 lore raw
Quoted 45 lines · Michael Kerrisk (man-pages)
Quoted 27 lines · Gabriel Krisman Bertazi

---
Changes since v2:
(suggested by Alejandro Colomar)
- selective -> selectively
- Add missing oxford comma.

Changes since v1:
(suggested by Alejandro Colomar)
- Use semantic lines
- Fix usage of .{B|I}R and .{B|I}
- Don't format literals
- Fix preferred spelling of userspace
- Fix case of word

---
 man2/prctl.2 | 100 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 100 insertions(+)
man2/prctl.2 +0 -0
index f25f05fdb593..8105c2a0c9de 100644
@@ -1533,6 +1533,78 @@ For more information, see the kernel source file
 (or
 .I Documentation/arm64/sve.txt
 before Linux 5.3).

man2/prctl.2 For more information, see the kernel source file · line 1545

Quoted 10 lines
man2/prctl.2 +10 -0
+.TP
+.\" prctl PR_SET_SYSCALL_USER_DISPATCH
+.\" commit 1446e1df9eb183fdf81c3f0715402f1d7595d4
+.BR PR_SET_SYSCALL_USER_DISPATCH " (since Linux 5.11, x86 only)"
+.IP
+Configure the Syscall User Dispatch mechanism
+for the calling thread,
+to selectively intercept system calls
+and dispatch them back to user space through
+.IR SIGSYS .

s/IR/BR/

I think a bit more explanation would help here. Could you add a few sentences to explain what "dispatch back to user space through SIGSYS" means?

Quoted 11 lines

man2/prctl.2 For more information, see the kernel source file · line 1554

Quoted 9 lines
man2/prctl.2 +9 -0
+.IP
+The current Syscall User Dispatch mode is selected via
+.IR arg2 ,
+which can either be set to
+.B PR_SYS_DISPATCH_ON
+to enable the feature,
+or to
+.B PR_SYS_DISPATCH_OFF
+to turn it off.

By the way, why is there no PR_*G*ET_SYSCALL_USER_DISPATCH?

Thanks for the feedback. I will prepare a new version.

Just to clarify this point, there isn't a strict reason why I didn't implement the PR_GET_* , I just didn't see much value in adding it because, 1) the same thread that enables the feature is the only affected by it, as it is reset across fork/clone, and (2) there isn't the case where a program inherit this setting from the parent, as it doesn't cross exec*(2).

Therefore, every case where a getter would be used, can just be solved in userspace quite easily, IMO.

Quoted 30 lines
Quoted 5 lines
man2/prctl.2 +5 -0
+.IP
+With
+.I arg2
+set to
+.BR PR_SYS_DISPATCH_ON ,

man2/prctl.2 For more information, see the kernel source file · line 1569

Quoted 10 lines
man2/prctl.2 +10 -0
+.I arg3
+and
+.I arg4
+respectively identify the
+.I offset
+and
+.I length
+of a memory region in the process map
+from where system calls are always allowed to be executed,
+regardless of the switch variable.

Can there be more than one of these regions?
The text should be explicit about this, I think.

Quoted 11 lines
man2/prctl.2 +11 -0
+.I arg5
+points to a char-sized variable
+that is a fast switch to enable/disable the mechanism
+without invoking the kernel.
+The variable pointed by
+.I arg5
+can either be set to
+.B PR_SYS_DISPATCH_ON
+to enable the mechanism
+or to
+.B PR_SYS_DISPATCH_OFF
Quoted 8 lines

man2/prctl.2 For more information, see the kernel source file · line 1584

Quoted 4 lines
man2/prctl.2 +4 -0
+to temporarily disable it.
+Any other value will fail the application
+with a
+.IR SIGSYS .

How/when does that failure occur? At the time of the prctl() call, I presume? What if the caller later sets the variable pointed to by arg5 to another value?

Actually, this happens at syscall-interception time. So you can have a bogus value in *arg5, as long as you don't invoke a syscall with a bad *arg5. Will properly document it.

Thanks,

Signature · 1 line
Gabriel Krisman Bertazi