* [PATCH v3] prctl.2: Document Syscall User Dispatch
@ 2020-12-21 20:06 Gabriel Krisman Bertazi
2020-12-22 19:17 ` Michael Kerrisk (man-pages)
0 siblings, 1 reply; 3+ messages in thread
From: Gabriel Krisman Bertazi @ 2020-12-21 20:06 UTC (permalink / raw)
To: alx.manpages, mtk.manpages; +Cc: linux-man, Gabriel Krisman Bertazi
Signed-off-by: Gabriel Krisman Bertazi <krisman@collabora.com>
---
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(+)
diff --git a/man2/prctl.2 b/man2/prctl.2
index f25f05fdb593..8105c2a0c9de 100644
--- a/man2/prctl.2
+++ b/man2/prctl.2
@@ -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
--
2.29.2
^ permalink raw reply related [flat|nested] 3+ messages in thread
* Re: [PATCH v3] prctl.2: Document Syscall User Dispatch
2020-12-21 20:06 [PATCH v3] prctl.2: Document Syscall User Dispatch Gabriel Krisman Bertazi
@ 2020-12-22 19:17 ` Michael Kerrisk (man-pages)
2020-12-22 19:39 ` Gabriel Krisman Bertazi
0 siblings, 1 reply; 3+ messages in thread
From: Michael Kerrisk (man-pages) @ 2020-12-22 19:17 UTC (permalink / raw)
To: Gabriel Krisman Bertazi, alx.manpages; +Cc: mtk.manpages, linux-man
On 12/21/20 9:06 PM, Gabriel Krisman Bertazi wrote:
> Signed-off-by: Gabriel Krisman Bertazi <krisman@collabora.com>
>
> ---
> 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(+)
>
> diff --git a/man2/prctl.2 b/man2/prctl.2
> index f25f05fdb593..8105c2a0c9de 100644
> --- a/man2/prctl.2
> +++ b/man2/prctl.2
> @@ -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 .
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?
> +.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?
> +.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.
Can there be more than one of these regions?
The text should be explicit about this, I think.
> +.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 .
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?
> +.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;
s/and/and the/
> +.IP * 3
> +.I arg2
> +is
> +.B PR_SYS_DISPATCH_ON
> +and the memory region provided is invalid;
Please define "invalid"
> +.IP * 3
> +.I arg2
> +is invalid.
> +.RE
> +.TP
> +.B EINVAL
> .I option
> is
> .BR PR_SET_TAGGED_ADDR_CTRL
Thanks,
Michael
--
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: [PATCH v3] prctl.2: Document Syscall User Dispatch
2020-12-22 19:17 ` Michael Kerrisk (man-pages)
@ 2020-12-22 19:39 ` Gabriel Krisman Bertazi
0 siblings, 0 replies; 3+ messages in thread
From: Gabriel Krisman Bertazi @ 2020-12-22 19:39 UTC (permalink / raw)
To: Michael Kerrisk (man-pages); +Cc: alx.manpages, linux-man
"Michael Kerrisk (man-pages)" <mtk.manpages@gmail.com> writes:
> On 12/21/20 9:06 PM, Gabriel Krisman Bertazi wrote:
>> Signed-off-by: Gabriel Krisman Bertazi <krisman@collabora.com>
>>
>> ---
>> 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(+)
>>
>> diff --git a/man2/prctl.2 b/man2/prctl.2
>> index f25f05fdb593..8105c2a0c9de 100644
>> --- a/man2/prctl.2
>> +++ b/man2/prctl.2
>> @@ -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 .
>
> 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?
>
>> +.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.
>> +.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.
>
> Can there be more than one of these regions?
> The text should be explicit about this, I think.
>
>> +.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 .
>
> 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,
--
Gabriel Krisman Bertazi
^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2020-12-22 19:40 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-12-21 20:06 [PATCH v3] prctl.2: Document Syscall User Dispatch Gabriel Krisman Bertazi
2020-12-22 19:17 ` Michael Kerrisk (man-pages)
2020-12-22 19:39 ` Gabriel Krisman Bertazi
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.